SpiSeekStream

The SpiSeekStream function repositions the current stream index or sets the current stream time for a specified stream. This allows applications to jump to a specific point, fast-forward, or rewind within a data object.

Syntax

#include <os2.h>

rc = SpiSeekStream(hstream, ulFlags, lSeekPoint);

Parameters

hstream (HSTREAM) - input

The handle of the stream to perform the seek operation.

ulFlags (ULONG) - input

Specifies how the seek is performed. You can combine a movement flag with a unit flag:

Movement Flags:

SPI_SEEK_ABSOLUTE: Seek from the beginning of the stream (default).
SPI_SEEK_RELATIVE: Seek relative to the current position (positive for forward, negative for backward).
SPI_SEEK_FROMEND: Seek relative to the end of the data object.
SPI_SEEK_SLAVES: Reposition the master stream and all associated slave streams in a synchronization group.

Unit Flags:

SPI_SEEK_MMTIME: lSeekPoint is in MMTIME units (1/3000th of a second, default).
SPI_SEEK_BYTES: lSeekPoint is in bytes.
SPI_SEEK_IFRAME: Seek to the nearest preceding I-frame (used in video compression).

lSeekPoint (LONG) - input: The target position or offset for the seek operation.

Return Value

rc (ULONG) - returns

Return codes indicating success or failure:

NO_ERROR: Success.
ERROR_INVALID_STREAM: Invalid stream handle.
ERROR_STREAM_NOT_STOP: The stream must be in a stopped state to seek.
ERROR_STREAM_NOT_SEEKABLE: The stream or data type does not support seeking (e.g., live microphone input).
ERROR_NOT_SEEKABLE_BY_TIME: The data object cannot be seeked using MMTIME.
ERROR_NOT_SEEKABLE_BY_BYTES: The data object cannot be seeked using byte offsets.
FAILURE: A stream handler-specific error occurred.

Remarks

Seeking is effectively the same as changing the stream's internal clock or position pointer.

**State Requirements**: This function is only valid for streams that are:

Newly created but not yet started.
Stopped (via a flush or discard stop).
At the end of the stream (EOS reached).

**Invalid States**: You cannot seek while a stream is paused, prerolling, or actively playing. You must stop the stream first.
**Synchronization**: When using `SPI_SEEK_SLAVES`, the Sync/Stream Manager ensures that all streams in the synchronization group maintain their relative positions.

Example Code

The following example shows how to seek to the 5-minute mark in an audio stream.

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

ULONG   ulRC;
HSTREAM hStream;
LONG    lSeekPoint;

/* 
 * Seek to 5 minutes. 
 * calculation: 5 min * 60 sec * 3000 units/sec = 900,000 units
 */
lSeekPoint = 900000;

/* Reposition the stream to an absolute time from the start */
ulRC = SpiSeekStream(hStream, 
                     SPI_SEEK_ABSOLUTE | SPI_SEEK_MMTIME, 
                     lSeekPoint);

if (ulRC) {
    /* Handle error (e.g., stream was playing or not seekable) */
}

Related Functions

Related Messages

SHC_SEEK