SpiInstallProtocol

The SpiInstallProtocol function registers a new stream protocol or removes an existing one from a specific stream handler. This allows applications to define custom streaming parameters, such as buffer sizes and counts, for a particular data type.

Syntax

#include <os2.h>

rc = SpiInstallProtocol(hid, pspcbkey, pspcb, ulFlags);

Parameters

hid (HID) - input

The Stream Handler ID to which the protocol will be added or from which it will be removed.

pspcbkey (PSPCBKEY) - input

A pointer to the key identifying the protocol. The `ulIntKey` field must be non-zero to create a unique instance of the protocol.

pspcb (PSPCB) - input

A pointer to the SPCB structure containing the protocol definition. The `spcbkey` field inside this structure must match the pspcbkey parameter.

ulFlags (ULONG) - input

Flags specifying the action to take:

SPI_INSTALL_PROTOCOL: Adds the protocol to the handler (default).
SPI_DEINSTALL_PROTOCOL: Removes the protocol from the handler.

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 protocol key was not recognized.
ERROR_INVALID_BLOCK: An invalid pointer was passed.
ERROR_INVALID_BUFFER_SIZE: The SPCB structure size is incorrect.
ERROR_SPCBKEY_MISMATCH: The key in the SPCB structure does not match pspcbkey.
FAILURE: A stream handler-specific error occurred.

Remarks

This function is vital for optimizing data throughput in multimedia applications.

**Unique Keys (`ulIntKey`)**: To support multitasking, you cannot modify the system-default protocols (where `ulIntKey` is 0). You must provide a unique, non-zero value—such as a device ID or a handle—to create a private protocol instance.
**Replacement**: You cannot "update" an installed protocol directly. To change settings, you must first deinstall the protocol using `SPI_DEINSTALL_PROTOCOL` and then reinstall it with the new values.
**Internal Matching**: Ensure that `pspcbkey->ulIntKey` is identical to `pspcb->spcbkey.ulIntKey`, otherwise the function will return `ERROR_SPCBKEY_MISMATCH`.

Example Code

The following code demonstrates how to take a default audio protocol, increase the buffer size for better performance, and install it as a custom protocol.

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

ULONG    ulRC;
HID      hidTarget;
SPCBKEY  spcbkey;
SPCB     spcb;

/* 1. Get default protocol (ulIntKey = 0) */
spcbkey.ulDataType    = DATATYPE_WAVEFORM;
spcbkey.ulDataSubType = WAVE_FORMAT_4S16;
spcbkey.ulIntKey      = 0;

SpiGetProtocol(hidTarget, &spcbkey, &spcb);

/* 2. Customize the SPCB */
spcbkey.ulIntKey      = 100;      /* Unique identifier */
spcb.spcbkey.ulIntKey = 100;      /* Must match        */
spcb.ulMaxBuf         = 8;        /* Increase buffers  */
spcb.ulBufSize        = 65536;    /* 64KB buffers      */

/* 3. Install the custom protocol */
ulRC = SpiInstallProtocol(hidTarget, 
                          &spcbkey, 
                          &spcb, 
                          SPI_INSTALL_PROTOCOL);

if (ulRC) return(ulRC);

Related Functions

Related Messages

SHC_INSTALL_PROTOCOL