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