SpiCreateStream

The SpiCreateStream function initializes a stream instance between a source stream handler and a target stream handler. This function allocates the necessary system resources and sets up the buffer management protocol required for data to flow between devices or memory.

Syntax

SpiCreateStream(hidSrc, hidTgt, pspcbkey, pdcbSrc, pdcbTgt, 
                pevcb, EventEntry, hstreamBuf, phstream, phevent)

Parameters

hidSrc (HID) - input

The ID of the source stream handler (e.g., File System Stream Handler).

hidTgt (HID) - input

The ID of the target stream handler (e.g., Audio Stream Handler).

pspcbkey (PSPCBKEY) - input

Pointer to the data type and subtype to be streamed (e.g., Waveform, MIDI).

pdcbSrc / pdcbTgt (PDCB) - input

Pointers to device control blocks containing specific instance information. Use `NULL` if the handler does not require a DCB.

pevcb (PIMPL_EVCB) - input

A pointer to a statically allocated Implicit Event Control Block. This is filled during event notifications.

EventEntry (PEVFN) - input

The entry point for the callback routine that handles stream-specific events.

hstreamBuf (HSTREAM) - input

For **split streams**, this is the handle of the primary stream whose buffers will be shared. Otherwise, this is ignored (passed as 0).

phstream (PHSTREAM) - output

Address where the newly created stream handle will be stored.

phevent (PHEVENT) - output

Address where the implicit event handle will be stored.

Return Value

rc (ULONG) - returns

Return codes indicating success or failure:

• NO_ERROR: Success.
• ERROR_INVALID_SPCBKEY: Unknown stream type or handlers cannot support this type.
• ERROR_INVALID_PROTOCOL: Error negotiating the buffer protocol.
• ERROR_ALLOC_HEAP: Failed to allocate stream resources from the SSM heap.
• ERROR_NOT_ENOUGH_MEMORY: Insufficient system memory for buffers.
• ERROR_TOO_MANY_STREAMS: System stream limit reached.

Remarks

• **Resource Allocation**: System resources and buffers are allocated during this call.
• **Split Streams**: Used for interleaved data (like audio and video in one file). Multiple streams can share a single set of buffers by referencing a primary stream handle in hstreamBuf.
• **Event Handling**: The `EventEntry` routine is called for state changes or errors. Since these calls are serialized, the routine should be kept brief to avoid blocking the Sync/Stream Manager. Never call SpiDestroyStream from inside this routine.
• **Null Streams**: To create a null stream (useful for testing or synchronization), both `hidSrc` and `hidTgt` should be set to the NULL stream handler ID.

Example Code

This example creates a stream from a file (source) to an audio card (target).

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

ULONG      ulRC;
HID        hidSource, hidTarget, hidUnused;
SPCBKEY    spcbkey;
DCB_AUDIOSH dcb;
IMPL_EVCB  evcb;
HSTREAM    hStream;
HEVENT     hEvent;

/* 1. Get Handler IDs */
SpiGetHandler("FSSH", &hidSource, &hidUnused);
SpiGetHandler("AUDIOSH$", &hidUnused, &hidTarget);

/* 2. Setup Data Type (16-bit, 44.1kHz Stereo Wave) */
spcbkey.ulDataType    = DATATYPE_WAVEFORM;
spcbkey.ulDataSubType = WAVE_FORMAT_4S16;
spcbkey.ulIntKey      = 0;

/* 3. Setup Target Device Control Block */
strcpy(dcb.szDevName, "AUDIO01$");

/* 4. Create the Stream */
ulRC = SpiCreateStream(hidSource, hidTarget, &spcbkey, NULL, 
                       (PDCB)&dcb, &evcb, (PEVFN)EventsRtn, 
                       0, &hStream, &hEvent);

/* Event Callback Routine */
ULONG APIENTRY EventsRtn(PEVCB pevcb) {
    /* Handle events like End of Stream here */
    return(0);
}

Related Functions

• SpiGetHandler
• SpiDestroyStream
• SpiStartStream
• SpiStopStream

Related Messages

• SHC_CREATE
• SHC_NEGOTIATE_RESULT