man3/AFListProperties.3

#

    AFGetProperty(3)					     AFGetProperty(3)

    NAME
      AFGetProperty, AFListProperties, AFChangeProperty, AFDeleteProperty -
      obtain and change properties

    SYNTAX
      #include <AF/AFlib.h>
      int AFGetProperty(AC ac, AAtom property, long	long_offset,
    		      long long_length,	ABool delete, AAtom req_type,
    		      AAtom *actual_type_return, int *actual_format_return,
    		      unsigned long *nitems_return,
    		      unsigned long *bytes_after_return,
    		      unsigned char **prop_return)

      AAtom	*AFListProperties(AC ac, int *num_prop_return)

      AFChangeProperty(AC ac, AAtom	property, AAtom	type, int format,
    		      int mode,	unsigned char *data, int nelements)

      AFDeleteProperty(AC ac, AAtom	property)

    ARGUMENTS

      actual_format_return
    	    Returns the	actual format of the property.

      actual_type_return
    	    Returns the	atom identifier	 that defines the actual type of the
    	    property.

      bytes_after_return
    	    Returns the	number of bytes	remaining to be	read in	the property
    	    if a partial read was performed.

      data	    Specifies the property data.

      delete    Specifies a	Boolean	value that determines whether the property is
    	    deleted.

      ac	    Specifies the device to use	(via an	audio context).

      format    Specifies whether the data should be viewed	as a list of 8-bit,
    	    16-bit, or 32-bit quantities.  Possible values are 8, 16, and 32.
    	    This information allows the	AF server to correctly perform byte-
    	    swap operations as necessary.  If the format is 16-bit or 32-bit,
    	    you	must explicitly	cast your data pointer to an (unsigned char
    	    *) in the call to AFChangeProperty.

      long_length
    	    Specifies the length in 32-bit multiples of	the data to be
    	    retrieved.

      long_offset
    	    Specifies the offset in the	specified property (in 32-bit
    	    quantities)	where the data is to be	retrieved.

      mode	    Specifies the mode of the operation.  You can pass APropModeRe-
    	    place, APropModePrepend, or	APropModeAppend.

      nelements Specifies the number of elements of	the specified data format.

      nitems_return
    	    Returns the	actual number of 8-bit,	16-bit,	or 32-bit items
    	    stored in the prop_return data.

      num_prop  Specifies the length of the	properties array.

      num_prop_return
    	    Returns the	length of the properties array.

      npositions
    	    Specifies the rotation amount.

      prop_return
    	    Returns the	data in	the specified format.

      property  Specifies the property name.

      properties
    	    Specifies the array	of properties that are to be rotated.

      req_type  Specifies the atom identifier associated with the property type
    	    or AAnyPropertyType.

      type	    Specifies the type of the property.	 The AF	server does not
    	    interpret the type but simply passes it back to an application
    	    that later calls AFGetProperty.

    DESCRIPTION
      The AFGetProperty function returns the actual	type of	the property; the
      actual format	of the property; the number of 8-bit, 16-bit, or 32-bit	items
      transferred; the number of bytes remaining to	be read	in the property; and
      a pointer to the data	actually returned.  AFGetProperty sets the return
      arguments as follows:

      o    If the specified	property does not exist	for the	specified device,
           AFGetProperty returns None to actual_type_return	and the	value zero to
           actual_format_return and	bytes_after_return.  The nitems_return argu-
           ment is empty.  In this case, the delete	argument is ignored.

      o    If the specified	property exists	but its	type does not match the
           specified type, AFGetProperty returns the actual	property type to
           actual_type_return, the actual property format (never zero) to
           actual_format_return, and the property length in	bytes (even if the
           actual_format_return is 16 or 32) to bytes_after_return.	 It also
           ignores the delete argument.  The nitems_return argument	is empty.

      o    If the specified	property exists	and either you assign AAnyProper-
           tyType to the req_type argument or the specified	type matches the
           actual property type, AFGetProperty returns the actual property type
           to actual_type_return and the actual property format (never zero) to
           actual_format_return. It	also returns a value to	bytes_after_return
           and nitems_return, by defining the following values:

    	       N = actual length of the	stored property	in bytes
    		    (even if the format	is 16 or 32)
    	       I = 4 * long_offset
    	       T = N - I
    	       L = MINIMUM(T, 4	* long_length)
    	       A = N - (I + L)

           The returned value starts at byte index I in the	property (indexing
           from zero), and its length in bytes is L.  If the value for
           long_offset causes L to be negative, a BadValue error results. The
           value of	bytes_after_return is A, giving	the number of trailing unread
           bytes in	the stored property.

      AFGetProperty	always allocates one extra byte	in prop_return (even if	the
      property is zero length) and sets it to ASCII	null so	that simple proper-
      ties consisting of characters	do not have to be copied into yet another
      string before	use.  If delete	is True	and bytes_after_return is zero,
      AFGetProperty	deletes	the property from the device and generates a Proper-
      tyNotify event on the	device.

      The function returns Success if it executes successfully.  To	free the
      resulting data, use Afree.

      AFGetProperty	can generate BadAtom, BadValue,	and BadAC errors.

      The AFListProperties function	returns	a pointer to an	array of atom proper-
      ties that are	defined	for the	specified device or returns NULL if no pro-
      perties were found.  To free the memory allocated by this function, use
      Afree.

      AFListProperties can generate	a BadAC	error.

      The AFChangeProperty function	alters the property for	the specified device
      and causes the AudioFIle server to generate a	PropertyNotify event on	that
      device.  AFChangeProperty performs the following:

      o    If mode is APropModeReplace, AFChangeProperty discards the previous
           property	value and stores the new data.

      o    If mode is APropModePrepend or APropModeAppend, AFChangeProperty
           inserts the specified data before the beginning of the existing data
           or onto the end of the existing data, respectively.  The	type and for-
           mat must	match the existing property value, or a	BadMatch error
           results.	 If the	property is undefined, it is treated as	defined	with
           the correct type	and format with	zero-length data.

      The lifetime of a property is	not tied to the	storing	client.	 Properties
      remain until explicitly deleted, or until the	server resets.	The maximum
      size of a property is	server dependent and can vary dynamically depending
      on the amount	of memory the server has available.  (If there is insuffi-
      cient	space, a ABadAlloc error results.)

      AFChangeProperty can generate	ABadAlloc, ABadAtom, ABadMatch,	ABadValue,
      and ABadAC errors.

      The AFDeleteProperty function	deletes	the specified property only if the
      property was defined on the specified	device and causes the AF server	to
      generate a PropertyNotify event on the device	unless the property does not
      exist.

      AFDeleteProperty can generate	ABadAtom and ABadAC errors.

    DIAGNOSTICS

      ABadAlloc The	server failed to allocate the requested	resource or server
    	    memory.

      ABadAtom  A value for	an Atom	argument does not name a defined Atom.

      ABadValue Some numeric value falls outside the range of values accepted by
    	    the	request.  Unless a specific range is specified for an
    	    argument, the full range defined by	the argument's type is
    	    accepted.  Any argument defined as a set of	alternatives can gen-
    	    erate this error.

      ABadAC    A value for	a audio	context	argument is not	valid.

    SEE ALSO
      AF(1)

    BUGS
      If you encounter a reproducible bug, please submit a problem report to
      (af-bugs@crl.dec.com).

    COPYRIGHT
      Copyright 1990-1994, Digital Equipment Corporation.
      See AF(1) for	a full statement of rights and permissions.

    AUTHORS
      Digital Cambridge Research Lab