SpiEnumerateProtocols

The SpiEnumerateProtocols function retrieves a list of SPCB (Stream Protocol Control Block) keys supported by a specific stream handler. These keys identify the data types and formats (protocols) that the handler is capable of processing.

Syntax

#include <os2.h>

rc = SpiEnumerateProtocols(hid, paSPCBKeys, pulNumSPCBKeys);

Parameters

hid (HID) - input: The Stream Handler ID of the handler to query. This ID is typically obtained by calling SpiGetHandler or SpiEnumerateHandlers.
paSPCBKeys (PVOID) - in/out: A pointer to an array of SPCBKEY structures. This buffer is filled with the keys that identify the protocols (e.g., PCM audio, MIDI, digital video) supported by the handler.
pulNumSPCBKeys (PULONG) - in/out: A pointer to a variable specifying the number of entries in the paSPCBKeys array.; On return, this variable is updated with the number of keys actually copied. If the buffer is too small, the function returns `ERROR_INVALID_BUFFER_SIZE`, and this parameter is updated with the required number of entries.

Return Value

rc (ULONG) - returns

Return codes indicating success or the type of failure:

NO_ERROR: Success.
ERROR_INVALID_FUNCTION: Invalid function requested.
ERROR_INVALID_HID: The provided Stream Handler ID is not valid.
ERROR_INVALID_BUFFER_SIZE: The provided array is too small. Check pulNumSPCBKeys for the required size.
ERROR_INVALID_BLOCK: Invalid pointer provided.
FAILURE: Stream handler-specific error.

Remarks

Use SpiEnumerateProtocols to dynamically discover what media formats a stream handler supports.

**SPCB Keys**: An SPCB key is a unique identifier for a protocol. Once you have a key, you can call SpiGetProtocol to retrieve the full SPCB structure, which contains detailed technical information such as data rate, buffer sizes, and flags.
**Negotiation**: This function is often used during the stream creation process to ensure that the source and target stream handlers share a compatible protocol for data exchange.

Example Code

The following code demonstrates how to retrieve the protocol list for a specific target stream handler.

#include <os2.h>
#include <os2me.h>

ULONG    ulRC;               /* Error return code      */
HID      hidTarget;          /* Target handler ID      */
ULONG    ulNumSPCBKeys = 20; /* Array capacity         */
SPCBKEY  aspcbkey[20];       /* Array of SPCB keys     */

/* ... hidTarget is obtained via SpiGetHandler ... */

/* Get the list of protocols for the target handler */
ulRC = SpiEnumerateProtocols(hidTarget, &aspcbkey, &ulNumSPCBKeys);

if (ulRC) {
    if (ulRC == ERROR_INVALID_BUFFER_SIZE) {
        /* Reallocate buffer based on ulNumSPCBKeys and retry */
    }
    return(ulRC); /* Error handling */
}

/* aspcbkey now contains ulNumSPCBKeys valid protocol identifiers */

Related Functions

Related Messages

SHC_ENUMERATE_PROTOCOLS