CHAPTER 1 Introduction ..

Status

[$XConsortium: api.mif /main/9 1996/06/06 13:44:18 mw $ (revision should appear here only for html, since hardcopy has the revision in the footer.)]

This document is a work in progress. As such, some areas are incomplete, vague, or have open questions. Such areas are marked with comments enclosed in brackets such as the following: [The status section should be removed in the final document.]

This document has some rough parts, but the need to distribute to consortium members for comment outweighs the need for further editing. Please send comments to audio@x.org. Typographical comments should be sent directly to the author, Mark Welch (mw@x.org).

Using This Specification

The library specification is presented as a collection of manual pages. There is an intro man page, which presents some basic information about the library API, definitions of certain commonly used data types and calling con ventions, as well as an overall list of interface pages. Following the intro man page are the remainder of the man pages, which contain definitions of the X Audio API, as well as definitions of object classes not covered in the protocol specification. See Chapter 2 ("Object Model") of the protocol specification for more information.

Where possible, the function man pages approximately follow Unix-style man page conventions. The object def inition man pages approximately follow the Motif man page standard, as used in OSF/Motif Programmer's Ref erence (Englewood Cliffs, NJ : Prentice-Hall : 1993).

Interface Notes

Integer sizes

Integers are represented in the specification explicitly by size and sign. [want to follow the IDL convention] The one exception to this rule is in the function XaXtProcessEvents, where the file descriptor parameter is an int in the native architecture. [this is because file descriptors are always ints; what should replace this text?]

Following is a table showing the various integer types used in the interface and their respective meanings:

----------------------------------------
| Type      | Definition               |
========================================
| XaUint8   | unsigned 8-bit integer   |
----------------------------------------
| XaInt8    | signed 8-bit integer     |
----------------------------------------
| XaUint16  | unsigned 16-bit integer  |
----------------------------------------
| XaInt16   | signed 16-bit integer    |
----------------------------------------
| XaUint32  | unsigned 32-bit integer  |
----------------------------------------
| XaInt32   | signed 32-bit integer    |
----------------------------------------

Usage of const

The const keyword is used in API functions according to that specified on page 72 of Harbison & Steele, C: A Reference Manual, 3rd Edition (Englewood Cliffs, NJ : Prentice-Hall, 1991). Following are examples of the usage of const:

const char *foo; pointer to constant characters

char * const foo; constant pointer to non-constant characters
const char * const foo; constant pointer to constant characters

An example function here provides a summary of constant usage [will replace with something else later]:

/* For simple declarations, read right to left to get const stuff right.
** in the comments below,
** p = "pointer"
** c = "constant"
** i = "integer"
**
** compile with gcc -c -pedantic to show errors
*/
ConstDemo()
{
int victim = -1;

const int * pfoo0 = &victim; /* pic */
int const * pfoo1 = &victim; /* pci (same as above) */
int * const pfoo2 = &victim; /* cpi */
const int * const pfoo3 = &victim; /* cpic */
int const * const pfoo4 = &victim; /* cpci (same as above) */

/* legal assignments */
pfoo0 = &victim;
pfoo1 = &victim;
*pfoo2 = 0;

/* illegal assignments */
*pfoo0 = 0;
*pfoo1 = 0;
pfoo2 = &victim;
*pfoo3 = 0;
pfoo3 = &victim;
*pfoo4 = 0;
pfoo4 = &victim;
}

CHAPTER 2 X Audio Interfaces ..

This chapter is a series of manual pages describing the X Audio library interfaces. There are three major sec tions: the intro page, function definitions, and object definitions. Following is a list of man pages in this chapter.

[table of contents here - take Name section from each page]


Name

Intro --

Synopsis

Description

Object model

Argument lists

Varargs interface

See also


Name

XaOpenAudio -- open a connection to an audio server

Synopsis

Parameters

networkID
Specifies the network ID of the audio server.
errStringLenIn
Specifies the maximum length of the error string that can be stored in err_string_out.
errStringOut
A string into which an error message may be written.
argcInOut
A pointer to the number of command line parameters passed to the program.
argvInOut
A pointer to the list of command line parameters passed to the program.

Description

hostName
Specifies the name of the host machine on which audio devices supported by the audio server are physically attached.
portNumber
An optional TCP/IP port number on which the audio server is listening. If no port number is specified, port [n] is used.
objName
[Explanation for DECnet equivalent of ports.]
path
[Need reasonable explanation here.]

Return values

Notes

See also


Name

XaCloseAudio -- close a connection to an audio server

Synopsis

Parameters

connection
A valid audio server connection.
callbackFunc
Specifies a function to be called when the audio connection closes asynchronously.
callbackData
Specifies a utility pointer to be passed to callbackFunc upon completion of an asynchronous checkpoint call.

Description

Return values

Notes

See also


Name

XaFlush -- flush the output buffer of a connection

Synopsis

Parameters

connection
A valid audio server connection.

Description

Return values

Notes

See also


Name

XaPing -- wait until all pending requests on a connection have been processed

Synopsis

Parameters

connection
A valid audio server connection.
discard
Specifies a Boolean value that indicates whether XaPing should discard all events on the event queue. Only uised when the call is synchronous (callbackFunc is NULL).
callbackFunc
If non-NULL, specifies a function to be called by the Xa library upon completion of the asynchronous call.
callbackData
Specifies a utility pointer to be passed to callbackFunc upon completion of an asynchronous checkpoint call.

Description

Return values

Notes

See also


Name

XaFindObject -- find the unique identifier (tag) for a particular object

Synopsis

Parameters

connection
Specifies the tag of a valid audio server connection.
searchRemote
Specifies whether to search for the object(s) on the server (if true) or in the client (if false).
objectClass
Specifies the tag of the class of the object to be found.
numReturnTags
Specifies the number of tags returned by the Find request.
returnTags
A library-allocated array of tags representing the results of the Find request. When returned from synchronous calls, this array must be freed by the client library. [??]
callbackFunc
Specifies a function to be called if XaFindObject is to execute asynchronously. If callbackFunc is NULL, XaFindObject executes synchronously.
callbackData
Specifies a utility pointer to be passed to callbackFunc upon completion of the asynchronous request.
...
A NULL-terminated variable parameter list of attribute name and value pairs to be used to search for the object.

Description

Return values

Notes

See also


Name

XaFindAtom -- find/create the unique identifier (atom) for a particular string value

Synopsis

Parameters

connection
A pointer to a valid audio server connection.
searchString
A pointer to a string whose tag is to be looked up.
create
Specifies whether a string object should be created in the server if none is found matching searchString.
returnAtom
Specifies the result of an asynchronous call to XaFindAtom.
callbackFunc
Specifies a function to be called if XaFindObject is to execute asynchronously. If callbackFunc is NULL, XaFindObject executes synchronously.
callbackData
Specifies a utility pointer to be passed to callbackFunc upon completion of the asynchronous request.

Description

Return values

Notes

See also


Name

XaCreate -- create an object and return its tag

Synopsis

Parameters

connection
A pointer to a valid audio server connection.
objectClassName
The tag of the class name of the object to be created.
...
Specifies a NULL-terminated variable parameter list of resource name and value pairs.

Description

Resource Specification

XaPfetchArgs
The value parameter contains [a list of resource names, coupled with sufficient information to extract the values from a resource database -- not fully specified].
XaPargList
The value parameter contains an XaArgList, in which are stored name-value pairs to be copied into object.
XaParray
The value of the next name-value pair contains a pointer to an array of a length described by the value in this name-value pair. The parameter sequence is as follows: {XaParray, arrayLength, attributeName, arrayPointer}
XaParrayPart
Like XaParray, but in addition a third name-value pair contains a NULL name and a value corresponding to a starting offset in the array to be changed. Therefore, the parameter sequence is as follows: {XaParrayPart, arrayLength, attributeName, arrayPointer, NULL, arrayOffset}
XaPtypedArg
Specifies a type cast to be applied to the value in the next name- value pair. The parameter sequence is as follows: {XaPtypedArg, valueType, attributeName, attributeValue}
XaPfinish
The value is a pointer to an XaFinish record, which specifies a function to call upon completion of this function call.

Return values

See also


Name

XaDestroy -- destroy an object

Synopsis

Parameters

connection
A pointer to a valid audio server connection.
targetObject
The object to be destroyed.
[deepDelete
If TRUE, delete objects to whom references are stored in targetObject.]

Description

Return values

Notes

See also


Name

XaSet -- set one or more attributes on an object

Synopsis

Parameters

connection
A valid audio server connection.
object
The object upon which attributes are to be set.
...
Specifies a NULL-terminated variable parameter list of resource name and value pairs.

Description

Resource Specification

XaPargList
The value parameter contains an XaArgList, in which are stored name-value pairs to be copied into object.
XaParray
The value of the next name-value pair contains a pointer to an array of a length described by the value in this name-value pair. The parameter sequence is as follows: {XaParray, arrayLength, attributeName, arrayPointer}
XaParrayPart
Like XaParray, but in addition a third name-value pair contains a NULL name and a value corresponding to a starting offset in the array to be changed. Therefore, the parameter sequence is as follows: {XaParrayPart, arrayLength, attributeName, arrayPointer, NULL, arrayOffset}
XaPtypedArg
Specifies a type cast to be applied to the value in the next name- value pair. The parameter sequence is as follows: {XaNTypedArg, valueType, attributeName, attributeValue}

Return values

Notes

See also


Name

XaGet -- retrieve values of one or more attributes of an object

Synopsis

Parameters

connection
A pointer to a valid audio server connection.
object
The object from which attribute values are to be retrieved.
returnValues
An XaArgList which specifies the names and values of the attributes whose values were requested by the XaGet function.
callbackFunc
Specifies a function to be called if XaGet is to execute asynchronously. If callbackFunc is NULL, XaFindObject executes synchronously.
callbackData
Specifies a utility pointer to be passed to callback upon completion of the asynchronous request.
...
Specifies a NULL-terminated variable parameter list of request data, consisting of attribute name strings and return value pointer addresses.

Description

Resource Specification

XaPargList
The value parameter contains the address of a pointer to an XaArgList, in which are stored name-pointer pairs into which are copied attribute data from object.
(pointer attribute)
There are two attributes whose type is a pointer in the client library's architecture: XaAcallbackFunc and XaAcallbackData (found in event handler objects). The pointers corresponding to these attributes are expected to contain the address of a pointer of appropriate size for the client architecture. See Client Object Definitions below [not yet completed] for more information on these attributes.
XaPcollection
The value of the next name-value pair contains a handle (address of pointer) onto an array of a length described by the value in this name-value pair. The parameter sequence is as follows: {XaParray, numElements, attributeName, arrayPointer}. The client may specify storage for the retrieved attribute value by passing in arrayPointer the address of a non- NULL array pointer, and by specifying the length of this memory (in number of elements) in 32-bit integer values pointed to by the dereferenced value of numElements. If the value of the dereferenced arrayPointer is NULL or the size indicated by *numElements is not large enough to accommodate the incoming data, a new array is allocated (using malloc(3)) and filled with the attribute data.
XaParray
Like XaPcollection, except that numElements above is replaced with a handle to an XaArrayExtents structure, described below. Therefore, the parameter sequence is as follows: {XaParray, arrayExtents, attributeName, arrayPointer}.

The dereferenced value of the arrayExtents parameter may either point to an allocated XaArrayExtents structure or may be NULL, in which case the arrayExtents structure will be allocated (using malloc(3)).

#define XA_MAX_DIMENSIONS 6

struct XaArrayExtents
{
XaUint32 dimensions[XA_MAX_DIMENSIONS];
/* size of each dimension */
};

typedef struct XaArrayExtents XaArrayExtents;

dimensions contains the size of each dimension in the array; unused dimensions are considered to have 0 elements. If the dereferenced value of arrayExtents is non-NULL and the dereferenced arrayPointer is also non-NULL, then [**arrayExtents] should contain valid size information which describes the number of allocated elements pointed to by arrayPointer. This allows the client application to specify pre- allocated memory to which attribute data may be written. Regardless of how arrayExtents is allocated or whether it is initialized, the values of arrayExtents are changed upon return to reflect the actual size of the returned array.

attributeName contains a string which specifies the name of the array attribute whose value is to be retrieved.

arrayPointer is the address of a pointer which points to the returned array values. The dereferenced value of arrayPointer must either be NULL or point to a block of allocated memory whose size is described in arrayExtents above. If the dereferenced arrayPointer is NULL or the size of the allocated memory is not sufficient to hold the returned values, a new array is allocated (using malloc(3)) and the new array pointer will be stored in arrayPointer.

Return values

Notes

See also


Name

XaRead -- read audio data from a port

Synopsis

typedef void (*XaReadReplyFunc)(XaAudio connection, XaTime start, XaTime end, 
       XaTag referenceTime, XaUint32 numBits, CARD8 leftPad, char 
       *returnBuff, void *handlerData);
void XaRead(XaAudio connection, XaTag port, 
       XaTime atTime, XaTag referenceTime, 
       XaUint32 minBits, XaUint32 maxBits,
       char **buff, XaUint32 *bitsReturned, INT8 *leftPad,
       XaReadReplyFunc callback, void *callbackData);

Parameters

connection
A pointer to a valid audio server connection.
port
The tag of the port from which to read data.
atTime
The time offset at which to read the data.
referenceTime
Specifies the reference time against which the read is to occur.
minBits
The minimum number of bits of audio data to be read.
maxBits
The maximum number of bits of audio data to be read.
buff
A handle to a buffer to which audio data from the server will be written.
bitsReturned
The number of bits actually read from the port
leftPad
The number of unused bits in the first byte of the audio data buffer.
callback
Specifies a function to be called if XaGet is to execute asynchronously. If callback is NULL, XaFindObject executes synchronously.
callbackData
Specifies a utility pointer to be passed to callback upon completion of the asynchronous request.
startTime, endTime
Specify the time range represented by the returned audio data in the reply function.
numBits
The number of bits of audio data passed to the reply function.
returnBuff
A pointer to a returned buffer of audio data.

Description

Return values

Notes

See also


Name

XaWrite -- write audio data to a port

Synopsis

void XaWrite(XaAudio connection, XaTag port, 
       XaTime atTime, XaTag referenceTime, 
       XaUint32 *numBits, char *buff, CARD8 leftPad);

Parameters

connection
A pointer to a valid audio server connection.
port
The tag of the port to which to write data.
atTime
The time offset at which to write the data.
referenceTime
Specifies the reference time against which the write is to occur.
numBits
The number of bits of audio data to write.
buff
A pointer to a buffer from which audio data is to be sent to the server.
leftPad
The number of unused bits in the first byte of the audio data buffer.

Description

Return values

Notes

See also


Name

XaPending, XaProcessNextEvent, XaMainLoop, XaXtProcessEvents -- check for and process messages from the server

Synopsis

Parameters

connection
A valid connection to an audio server.
wait
Specifies whether to block while waiting for an incoming event.

Description

See also


Name

XaPushErrorHandler, XaPopErrorHandler -- manage error handlers

Synopsis

Parameters

connection
A valid connection to an audio server.
handlerFunc
Specifies the error handler routine to be added/removed to the error handler stack for the connection.

Description

See also


Name

Connection -- represents a connection from a client to an audio server

Synopsis

Description

Classes

New Attributes

Inherited Attributes


Name

EventHandler -- represents a connection from a client to an audio server

Synopsis

Description

Classes

New Attributes

XaNhandlerFunc

XaNhandlerData

XaNactive

XaNeventType

XaNtargetObject

XaNmonAttributes

XaNalarms

XaNconditions

XaNretAttributes

Inherited Attributes


Name

ClientCondition --

Synopsis

Description

Classes

New Attributes

[attribute name]

Inherited Attributes


Name

File --

Synopsis

Description

Classes

New Attributes

[attribute name]

Inherited Attributes


Name

Player -- spools data from an audio file on the client

Synopsis

Description

Classes

New Attributes

[attribute name]

Inherited Attributes


Name

Recorder -- record data from the server into a file on the client

Synopsis

Description

Classes

New Attributes

[attribute name]

Inherited Attributes