SpiSendMsg

The SpiSendMsg function sends a stream-handler-specific message to a particular stream handler. This provides a direct communication channel between an application and a handler, allowing for the exchange of information or commands that fall outside the standard SPI function set.

Syntax

#include <os2.h>

rc = SpiSendMsg(hstream, hid, ulMsgType, pMsg);

Parameters

hstream (HSTREAM) - input

The handle of the stream instance that contains the target stream handler.

hid (HID) - input

The Stream Handler ID of the specific handler (source or target) within the stream that should receive the message.

ulMsgType (ULONG) - input

The specific message type being sent. Standard types include:

SHC_REPORT_INT: Reports an interrupt (pMsg points to a MSG_REPORTINT structure).
SHC_REPORT_EVENT: Reports an event (pMsg points to a MSG_REPORTEVENT structure).
Custom message types defined by specific stream handlers.

pMsg (PVOID) - input: A pointer to a control block structure specific to the ulMsgType.; Note: The first field of this control block must be a `ULONG` specifying the total length of the structure (see MSG_COMMON).

Return Value

rc (ULONG) - returns

Return codes indicating success or failure:

NO_ERROR: Success.
ERROR_INVALID_FUNCTION: Invalid function requested.
ERROR_INVALID_STREAM: The provided stream handle is not valid.
FAILURE: A stream handler-specific error occurred.

Remarks

SpiSendMsg is the primary mechanism for "out-of-band" communication during active streaming.

**Usage**: Unlike SpiAssociate, which is used to link a data object to a stream, SpiSendMsg is used for real-time signaling and information updates.
**Active Streaming**: This function is valid while the stream is in an active state.
**Handler Specificity**: Because the contents of `pMsg` are defined by the stream handler, developers must consult the documentation for the specific handler (e.g., Audio, MIDI, or Video handlers) to understand the supported messages and structure layouts.

Example Code

The following example demonstrates the setup for sending a specific message to a source stream handler.

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

ULONG       rc;          /* Error return code        */
HID         hidSource;   /* Source handler ID        */
HSTREAM     hStream;     /* Stream handle            */
ULONG       ulMsgType;   /* Message type identifier  */
PMSG_COMMON pMsg;        /* Pointer to message block */

/* ... hStream and hidSource obtained via SpiCreateStream/SpiGetHandler ... */

/* 
 * Define a hypothetical handler-specific message. 
 * The first field MUST be the length of the structure.
 */
ulMsgType = SOME_HANDLER_MESSAGE;
pMsg->ulMsgLen = sizeof(MY_CUSTOM_MSG_BLOCK);

/* Send the message to the source handler */
rc = SpiSendMsg(hStream, hidSource, ulMsgType, (PVOID)pMsg);

if (rc) {
    return (rc); /* Handle error */
}

Related Functions

Related Messages

SHC_SENDMSG