SpiStartStream
The SpiStartStream function initiates data streaming for a single stream instance or a group of synchronized streams. It can also be used to "preroll" a stream, filling its buffers to ensure a smooth, immediate start.
Syntax
#include <os2.h> rc = SpiStartStream(hstream, ulFlags);
Parameters
- hstream (HSTREAM) - input
- The handle of the stream to be started or prerolled.
- ulFlags (ULONG) - input
- Specifies how the stream should start. You can use one of the following:
- SPI_START_STREAM: Starts only the specified stream. This is the default.
- SPI_START_SLAVES: Starts the master stream and all associated slave streams in a synchronization group. hstream must be a master stream handle.
- SPI_START_PREROLL: Fills the stream buffers without starting playback/recording. This is an asynchronous operation.
Return Value
- rc (ULONG) - returns
- Return codes indicating success or failure:
- NO_ERROR: Success.
- ERROR_INVALID_STREAM: Invalid stream handle.
- ERROR_STREAM_NOTMASTER: `SPI_START_SLAVES` was used on a non-master stream.
- ERROR_START_STREAM: The stream is already started or currently prerolling.
- ERROR_DATA_ITEM_NOT_SPECIFIED: No data object is associated with the stream.
- FAILURE: A stream handler-specific error occurred.
Remarks
SpiStartStream transitions a stream from an idle state (created, stopped, or paused) into an active state.
- Prerolling: Using the `SPI_START_PREROLL` flag tells the source handler to begin loading data into buffers immediately. Once buffers are full, the Sync/Stream Manager sends an `EVENT_SYNC_PREROLLED` notification. Starting a prerolled stream provides a much faster response time because the hardware doesn't have to wait for the initial data chunk.
- Synchronization: If you have synchronized audio and video (master/slave via SpiEnableSync), calling SpiStartStream with `SPI_START_SLAVES` ensures both start at the exact same moment.
- Asynchronous Errors: A `NO_ERROR` return only means the request was accepted. Hardware failures occurring during data movement are reported asynchronously via the event routine as an `EVENT_ERROR`.
Example Code
This snippet shows how to start a previously created and associated stream.
#include <os2.h>
#include <os2me.h>
ULONG ulRC;
HSTREAM hStream;
/* ... assume hStream was created and associated ... */
/* Start the stream normally */
ulRC = SpiStartStream(hStream, SPI_START_STREAM);
if (ulRC) {
/* Handle immediate start failure */
}
Related Functions
Related Messages
- SHC_START