The Audio Stream Handler is used to control streaming of audio data. In some cases, the Audio Stream Handler acts as a consumer of audio data, and in other cases it acts as a producer. The audio data in each of these cases is always digital. It is sometimes compressed and sometimes uncompressed. Each of these cases is discussed in detail below. In addition to these discussions, information is included concerning interaction between this module and the Sync/Stream Manager.
This module is implemented as a DLL running at Ring 3 as well as a stub device driver module (PDD) running at Ring 0 (system kernel privilege level).
The Audio Stream Handler running at Ring 3 can call Ring 3 DLL audio CODECs to assist in compressing and decompressing audio data. The Ring 3 Audio Stream Handler communicates with audio device drivers through the DDCMD interfaces in the VSD. (Refer to the OS/2 Multimedia Programming Reference for the VSD DDCMD interface definitions.)
Existing audio device drivers use standard audio-device-driver interface (DDCMDs) to communicate with the Ring 0 stub device driver module.
External Interface Description
The description for the Ring 3 Audio Stream Handler external interface follows:
File Name
The output of this stream handler can be in several different forms such as uncompressed 16-bit PCM, and several styles of compressed ADPCM.
The exact number and size of these stream buffers will depend on the type of data being streamed. The information needed to determine the size and number of stream buffers is contained in the stream protocol control block (SPCB) for a particular type of stream.
This stream handler supports audio data in several different formats (stream types) such as 16-bit PCM, AVC's 8-bit ADPCM, CD-ROM XA's 8-bit ADPCM, and so forth.
In addition to handling the playback of audio data, this stream handler generates sync pulses based on the playback of an audio stream. Therefore, this stream handler can be a master or a slave in a sync relationship. The application can set up a sync relationship between two streams and define the sync pulse granularity. Sync pulses would then be generated by the Audio Stream Handler, possibly on a recurring interval, based on the sync granularity defined in the SPCB for the data type.
Device Control Blocks
The Ring 3 Audio Stream Handler supports two device control blocks (DCBs). The DCB is used to associate an audio device driver with this stream handler for this stream instance. The DCB is passed as a parameter on a call to SpiCreateStream.
/********************************************** * * DCB_AUDIOSH - Device Control Block for the * Audio Stream Handler. * (*** PACKED STRUCTURE ***) **********************************************/ typedef struct _dcb_audiosh { /* dcb_audiosh - Device Control Block */ ULONG ulDCBLen; /* Length of structure */ SZ szDevName[MAX_SPI_NAME]; /* Device driver name */ ULONG ulSysFileNum; /* File handle number - From an */ /* audio_init call */ } DCB_AUDIOSH; typedef struct _dcb_audiosh FAR *PDCB_AUDIOSH;
The Ring 3 Audio Stream Handler also supports the VSD device control block (VSD_DCB) which identifies the VSD DLL to be used by the Ring 3 Audio Stream Handler. The VSD_DCB is passed as a parameter on a call to SpiCreateStream.
/*************************************************************************** * * VSD_DCB - VSD Device Control Block * * This structure will allow stream handlers to use the VSD DLL * by using by the additional fields in the structure. * * (*** PACKED STRUCTURE ***) ***************************************************************************/ typedef struct _VSD_DCB { /* vsd_dcb - VSD Device Control Block */ ULONG ulDCBLen; /* Length of structure */ SZ szDevName[MAX_SPI_NAME]; /* Device driver name */ ULONG ulSysFileNum; /* File handle number */ ULONG hvsd; /* Handle to VSD instance */ PFN pfnvsdEntryPoint; /* Address of VSD entry point */ ULONG ulReserved1; /* Reserved for system */ ULONG ulReserved2; /* Reserved for system */ } VSD_DCB; typedef VSD_DCB FAR *PVSD_DCB;
Associate Control Blocks
The Audio Stream Handler does not support an associate control block.
Implicit Events (EVENT_IMPLICIT_TYPE) Supported
The following implicit (EVENT_IMPLICIT_TYPE) events for the Audio Stream Handler are supported:
The ulStatus field will contain the error code. The possible error codes that can be generated and returned by this stream handler are:
This will be generated only when this stream handler is a target and it finds a cuepoint indicator in the buffer table from the Sync/Stream Manager. The event will be reported after the data has been written to the file system using MMIO. The ulMessageParm field of the PLAYL_EVCB will be filled in with the message supplied in the playlist instruction. The mmtimeStream field will not be filled in.
Explicit Events Supported
The following explicit events for the Audio Stream Handler are supported:
Explicit Events Not Supported
The following explicit events for the Audio Stream Handler are not supported:
Stream Handler Commands Supported
The following stream handler commands (SHC) are supported. Refer to the OS/2 Multimedia Programming Reference for a description of these SHC commands and the error return codes.
Possible Return Codes:
Possible Return Codes:
Possible Return Codes:
Possible Return Codes:
Possible Return Codes:
Possible Return Codes:
Possible Return Codes:
Possible Return Codes:
Possible Return Codes:
Possible Return Codes:
Possible Return Codes:
Possible Return Codes:
Possible Return Codes:
Possible Return Codes:
Possible Return Codes:
Possible Return Codes:
Base Stream Protocol Control Blocks Supported
The Audio Stream Handler supports the following SPCBs:
Subtypes:
Subtypes:
Subtypes: