SpiGetHandler

The SpiGetHandler function retrieves the internal handler IDs (**HID**) for a specified stream handler name. These IDs are necessary to identify which handler will act as the source and which will act as the target when creating a stream.

Syntax

SpiGetHandler(pszHName, phidSrc, phidTgt)

Parameters

pszHName (PSZ) - input: A pointer to a null-terminated string containing the name of the stream handler (maximum 9 characters). Examples include `"FSSH"` (File System Stream Handler) or `"AUDIOSH$"` (Audio Stream Handler).
phidSrc (PHID) - output: A pointer to an HID variable that receives the ID used when this handler serves as a **source** (data provider).
phidTgt (PHID) - output: A pointer to an HID variable that receives the ID used when this handler serves as a **target** (data consumer/renderer).

Return Value

rc (ULONG) - returns

Return codes indicating success or failure:

NO_ERROR: Success.
ERROR_INVALID_HNDLR_NAME: The provided name is invalid.
ERROR_HNDLR_NOT_FOUND: The handler name is not registered in the system.
ERROR_HNDLR_NOT_IN_INI: The handler name was not found in the `SPI.INI` file.
ERROR_INI_FILE: The `SPI.INI` file could not be located.
ERROR_LOADING_HNDLR: A DLL-based handler failed to load or connect to the Sync/Stream Manager.
ERROR_READING_INI: A file I/O error occurred while reading `SPI.INI`.
ERROR_INVALID_BLOCK: An invalid pointer was passed.

Remarks

This function serves as the gateway for using a stream handler in an OS/2 Multimedia application.

**Dynamic Loading**: If a handler is implemented as a DLL and is not currently in memory, SpiGetHandler will automatically load the DLL and initialize it.
**Source vs. Target**: Handlers often have different IDs depending on their role.
- If a handler only supports being a source (e.g., a file reader), the target HID returned will be `0`.
- If a handler only supports being a target (e.g., an audio speaker driver), the source HID returned will be `0`.
**Hardware Handlers**: Physical Device Driver (PDD) handlers are typically loaded at boot time via `CONFIG.SYS`, but must still be queried through this function to get their runtime IDs.

Example Code

The following code demonstrates how to obtain the source ID for a file handler and the target ID for an audio handler to set up a playback scenario.

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

ULONG   ulRC;          /* Error return code */
HID     hidSource;     /* Source handler ID */
HID     hidTarget;     /* Target handler ID */
HID     hidUnused;     /* Dummy placeholder */

/* Get the HID for the File System Stream Handler as a source */
ulRC = SpiGetHandler("FSSH", &hidSource, &hidUnused);
if (ulRC) return(ulRC);

/* Get the HID for the Audio Stream Handler as a target */
ulRC = SpiGetHandler("AUDIOSH$", &hidUnused, &hidTarget);
if (ulRC) return(ulRC);

/* hidSource and hidTarget are now ready for SpiCreateStream */

Related Functions

Related Messages

SHC_INSTALL_PROTOCOL