SpiEnumerateHandlers

The SpiEnumerateHandlers function retrieves a list of all stream handlers (both device drivers and DLL-based) currently installed and registered in the `SPI.INI` file.

Syntax

#include <os2.h>

rc = SpiEnumerateHandlers(pahand, pulNumHand);

Parameters

pahand (PHAND) - in/out: Pointer to a buffer to be filled with HAND structures. Each structure contains the name and class name of an installed stream handler.
pulNumHand (PULONG) - in/out: Pointer to a variable that specifies the number of HAND structures the buffer can hold.; On return, this variable is updated with the actual number of handlers copied into the buffer. If the buffer is too small, this variable receives the total number of handlers existing in the system.

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_BLOCK: Invalid pointer provided.
ERROR_INVALID_BUFFER_SIZE: The provided buffer is too small. Check pulNumHand for the required size.
ERROR_READING_INI: The system could not access or read the `SPI.INI` configuration file.

Remarks

This function is the primary way for an application or Media Control Driver (MCD) to discover the multimedia capabilities of the operating system at runtime.

**SPI.INI**: This file acts as the central registry for the Sync/Stream Manager. It is typically populated during the installation of OS/2 Multimedia or third-party stream handlers.
**Handler Types**: The enumeration includes:
- **Physical Device Driver (PDD) Handlers**: Direct interfaces to hardware.
- **DLL Handlers**: Software-based handlers (e.g., file system handlers or data converters).
**Usage Strategy**: It is common practice to call this function once with a small or null buffer to determine the total number of handlers (receiving `ERROR_INVALID_BUFFER_SIZE`), allocate the necessary memory, and then call it a second time to retrieve the full list.

Example Code

The following example demonstrates how to retrieve the names of up to five installed stream handlers.

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

ULONG   ulRC;             /* Error return code           */
HAND    ahand[5];         /* Array of handler info       */
ULONG   ulNumHand = 5;    /* Maximum handlers to return  */

/*---------------------------------------------------------------*/
/* Get list of all stream handlers in the system                 */
/*---------------------------------------------------------------*/
ulRC = SpiEnumerateHandlers((PHAND)&ahand, &ulNumHand);

if (ulRC) {
    if (ulRC == ERROR_INVALID_BUFFER_SIZE) {
        /* ulNumHand now contains the actual count needed */
    }
    return(ulRC); /* Error handling */
}

/* ahand[0].szHandlerName now contains the first handler's name */

Related Functions

Related Messages

None.