	      Network Audio System Protocol Description

($Id: protocol.txt 9 1999-07-08 00:51:49Z jon $)
($NCDId: @(#)protocol.txt,v 1.2 1994/06/01 17:50:38 greg Exp $)

Common Types

__________________________________________________________________
Name	       Value
__________________________________________________________________

LISTofFOO      A type name of the form LISTofFOO means a counted
	       list of elements of type FOO.  The size of the
	       length field may vary (it is not necessarily the
	       same size as a FOO), and in some cases, it may be
	       implicit. Except where explicitly noted, zero-length
	       lists are legal.
AUID	       32-bit value (top three bits guaranteed to be zero)
AUDEVICEID     32-bit value (top three bits guaranteed to be zero)
AUBUCKETID     32-bit value (top three bits guaranteed to be zero)
AUFLOWID       32-bit value (top three bits guaranteed to be zero)
BYTE	       8-bit value
INT8	       8-bit signed integer
INT16	       16-bit signed integer
INT32	       32-bit signed integer
CARD8	       8-bit unsigned integer
CARD16	       16-bit unsigned integer
CARD32	       32-bit unsigned integer
AUFIXED	       CARD32
TIMESTAMP      CARD32
BOOL	       {True, False}
STRING8	       LISTofCARD8

Connection Setup

    Connection Initiation

	byte-order: CARD8
	protocol-major-version: CARD16
	protocol-minor-version: CARD16
	authorization-protocol-name: STRING8
	authorization-protocol-data: STRING8

    Server Response

	success: BOOL
	protocol-major-version: CARD16
	protocol-minor-version: CARD16
	length: CARD16

    The client receives the following additional data if authorization
    fails:

	reason: STRING8

    The client receives the following additional data if authorization
    is accepted:

	vendor: STRING8
	release-number: CARD32
	resource-id-base, resource-id-mask: CARD32
	maximum-request-length: CARD16
	min-sample-rate, max-sample-rate: CARD16
	max-tracks: CARD8
	data-formats: LISTofCARD8
	elements: LISTofCARD8
	wave-forms: LISTofCARD8
	actions: LISTofCARD8
	devices: LISTofDEVICEATTRIBUTES
	buckets: LISTofBUCKETATTRIBUTES
	radios: LISTofRADIOATTRIBUTES

    where:

	COMMON			value-mask: CARD32
				changable-mask: CARD32
				id: AUID
				kind: CARD8
				use: CARD8
				format: CARD8
				num-tracks: CARD8
				access: CARD32
				description: STRING8

	DEVICE			location: CARD32
				gain: CARD32
				min-sample-rate: CARD16
				max-sample-rate: CARD16
				line-mode: CARD8
				children: LISTofAUDEVICEID

	BUCKET			sample-rate: CARD16
				num-samples: CARD32

	DEVICEATTRIBUTES	common: COMMON
				device: DEVICE

	BUCKETATTRIBUTES	common: COMMON
				bucket: BUCKET

	RADIOATTRIBUTES		XXX unimplemented XXX

Requests

*** ListDevices
    -->
	devices: LISTofDEVICEATTRIBUTES

*** GetDeviceAttributes
	device: AUDEVICEID
    -->
	attributes: DEVICEATTRIBUTES

*** SetDeviceAttributes
	device: AUDEVICEID
	attributes: DEVICEATTRIBUTES

*** CreateBucket
	bucket: AUBUCKETID
	attributes: BUCKETATTRIBUTES

*** DestroyBucket
	bucket: AUBUCKETID

*** ListBuckets
    -->
	buckets: LISTofBUCKETATTRIBUTES

*** GetBucketAttributes
	bucket: AUBUCKETID
    -->
	attributes: BUCKETATTRIBUTES

*** SetBucketAttributes				XXX unimplemented XXX
	bucket: AUBUCKETID
	attributes: BUCKETATTRIBUTES

*** CreateRadio					XXX unimplemented XXX
*** DestroyRadio				XXX unimplemented XXX
*** ListRadios					XXX unimplemented XXX
*** GetRadioAttributes				XXX unimplemented XXX
*** SetRadioAttributes				XXX unimplemented XXX

*** CreateFlow
	flow: AUFLOWID

*** DestroyFlow
	flow: AUFLOWID

*** GetFlowAttributes				XXX unimplemented XXX
*** SetFlowAttributes				XXX unimplemented XXX

*** GetElements
	flow: AUFLOWID
    -->
	clocked: BOOL
	flow: AUFLOWID
	elements: LISTofELEMENT

where:

	ELEMENT			type: CARD16
				element: IMPORTCLIENT or
					 IMPORTDEVICE or
					 IMPORTBUCKET or
					 IMPORTWAVEFORM or
					 IMPORTRADIO or
					 BUNDLE or
					 MULTIPLYCONSTANT or
					 ADDCONSTANT or
					 SUM or
					 EXPORTCLIENT or
					 EXPORTDEVICE or
					 EXPORTBUCKET or
					 EXPORTRADIO or
					 EXPORTMONITOR

	ACTION			flow: AUFLOWID
				element-num: CARD8
				trigger-state: CARD8
				trigger-prev-state: CARD8
				trigger-reason: CARD8
				action: CARD8
				new-state: CARD8

	TRACK			element-num: CARD8
				track: CARD8

	IMPORTCLIENT		sample-rate: CARD16
				format: CARD8
				num-tracks: CARD8
				discard: BOOL
				max-samples: CARD32
				low-water-mark: CARD32
				actions: LISTofACTION

	IMPORTDEVICE		sample-rate: CARD16
				num-samples: CARD32
				device: AUDEVICEID
				actions: LISTofACTION

	IMPORTBUCKET		sample-rate: CARD16
				num-samples: CARD32
				bucket: AUBUCKETID
				offset: CARD32
				actions: LISTofACTION

	IMPORTWAVEFORM		sample-rate: CARD16
				num-samples: CARD32
				wave-form: CARD8
				frequency: CARD32
				actions: LISTofACTION

	IMPORTRADIO		XXX unimplemented XXX

	BUNDLE			tracks: LISTofTRACK

	MULTIPLYCONSTANT	input: CARD16
				constant: AUFIXED

	ADDCONSTANT		input: CARD16
				constant: AUFIXED

	SUM			inputs: LISTofCARD16

	EXPORTCLIENT		sample-rate: CARD16
				input: CARD16
				format: CARD8
				num-tracks: CARD8
				discard: BOOL
				max-samples: CARD32
				high-water-mark: CARD32
				actions: LISTofACTION

	EXPORTDEVICE		sample-rate: CARD16
				input: CARD16
				num-samples: CARD32
				actions: LISTofACTION
				device: AUDEVICEID
				actions: LISTofACTION

	EXPORTBUCKET		input: CARD16
				num-samples: CARD32
				bucket: AUBUCKETID
				offset: CARD32
				actions: LISTofACTION

	EXPORTRADIO		XXX unimplemented XXX

	EXPORTMONITOR		event-rate: CARD16
				input: CARD16
				format: CARD8
				num-tracks: CARD8

*** SetElements
	flow: AUFLOWID
	clocked: BOOL
	elements: LISTofELEMENT

*** GetElementStates
	states: LISTofELEMENTSTATE
    -->
	states: LISTofELEMENTSTATE

where:

	ELEMENTSTATE		flow: AUFLOWID
				element-num: CARD8
				state: CARD8

*** SetElementStates
	states: LISTofELEMENTSTATE

*** GetElementParameters			XXX unimplemented XXX

*** SetElementParameters
	parameters: LISTofPARAMETER

where:

	PARAMETER		flow: AUFLOWID
				element-num: CARD8
				parameters: LISTofCARD32

*** WriteElement
	flow: AUFLOWID
	element-num: CARD8
	state: CARD8
	data: LISTofBYTE

*** ReadElement
	flow: AUFLOWID
	element-num: CARD8
	num-bytes: CARD32
    -->
	data: LISTofBYTE

*** GrabComponent				XXX unimplemented XXX
*** UngrabComponent				XXX unimplemented XXX
*** SendEvent					XXX unimplemented XXX

*** GetAllowedUsers				XXX unimplemented XXX
*** SetAllowedUsers				XXX unimplemented XXX

*** ListExtensions				XXX unimplemented XXX
*** QueryExtension				XXX unimplemented XXX

*** GetCloseDownMode
*** SetCloseDownMode
*** KillClient
*** GetServerTime
*** NoOperation
