SpiGetProtocol
The SpiGetProtocol function queries a specific stream handler for the technical details of a supported protocol. It populates a Stream Protocol Control Block (SPCB) based on a provided SPCBKEY.
Syntax
#include <os2.h> rc = SpiGetProtocol(hid, pspcbkey, pspcb);
Parameters
- hid (HID) - input
- The Stream Handler ID from which to retrieve the protocol information.
- pspcbkey (PSPCBKEY) - input
- A pointer to the key that identifies the specific protocol (data type and subtype) being queried.
- pspcb (PSPCB) - in/out
- A pointer to a memory block where the function will copy the SPCB structure. This structure contains details like buffer sizes, number of buffers, and synchronization flags.
Return Value
- rc (ULONG) - returns
- Return codes indicating success or failure:
- NO_ERROR: Success.
- ERROR_INVALID_FUNCTION: Invalid function requested.
- ERROR_INVALID_HID: The provided handler ID is not valid.
- ERROR_INVALID_SPCBKEY: The handler does not recognize the protocol identified by the key.
- ERROR_INVALID_BLOCK: An invalid pointer was passed.
- FAILURE: A stream handler-specific error occurred.
Remarks
This function is essential for applications that need to fine-tune stream performance or verify hardware capabilities.
- **Modification**: A common use case is to call SpiGetProtocol to get the default settings for a data type, modify specific fields (such as increasing the number of buffers to prevent underflow), and then use SpiInstallProtocol to register the customized version.
- **Compatibility**: Before creating a stream, an application should ensure that both the source and target handlers can support the protocol returned by this function.
Example Code
The following code demonstrates how to retrieve the protocol details for 16-bit, 44.1kHz Stereo waveform audio from a specific handler.
#include <os2.h>
#include <os2me.h>
ULONG ulRC; /* Error return code */
HID hidTarget; /* Target handler ID */
SPCBKEY spcbkey; /* Protocol key */
SPCB spcb; /* Protocol details */
/* ... hidTarget obtained via SpiGetHandler ... */
/* Define the protocol we are looking for */
spcbkey.ulDataType = DATATYPE_WAVEFORM;
spcbkey.ulDataSubType = WAVE_FORMAT_4S16;
spcbkey.ulIntKey = 0;
/* Retrieve the full protocol control block */
ulRC = SpiGetProtocol(hidTarget, &spcbkey, &spcb);
if (ulRC) {
return(ulRC); /* Handle error: protocol might not be supported */
}
/*
* spcb now contains defaults like:
* spcb.ulBytesPerUnit, spcb.ulNumBuffers, etc.
*/
Related Functions
Related Messages
- SHC_GET_PROTOCOL