DSGoMarker

Shifts to a location in the stream.

Synopsis

int32 DSGoMarker (Item msgItem, DSRequestMsgPtr reqMsg, DSStreamCBPtr streamCBPtr, unsigned long markerValue, unsigned long options)

Description

Sends a message telling the acquisition thread to shift to a specified location in the stream. Stream locations are normally defined by the clock timestamps embedded in streamed data.

DSGoMarker() sets the members of the message data structure required to move the acquisition thread to the specified location. (The message is the DSRequestMsg identified by reqMsg.) If a message is specified, DSGoMarker() sends the message and returns immediately. If no message is specified (if reqMsg is NULL), DSGoMarker() creates a message, sends it to the DataStreamer, and waits until the message has been received before returning.

You have the following options

GOMARKER_ABSOLUTE                absolute marker FILE POSITION
GOMARKER_FORWARD                 count of markers to skip forward
GOMARKER_BACKWARD                count of markers to skip backward
GOMARKER_ABS_TIME                absolute stream time of destination
GOMARKER_FORW_TIME               stream time by which to advance
GOMARKER_BACK_TIME               stream time by which to regress
GOMARKER_NAMED                   ptr to name of destination marker
GOMARKER_NUMBER                  go to given marker number
If you are using the ShuttlePlayer example, which is currently still an independent branch from the main DataStreamer branch, you have the following additional options:

GOMARKER_NUMBER                        go to given marker number: ccw mod 
GOMARKER_FWD_POS_RELATIVE              number of blocks to skip forward relative 
                                       to our current position
GOMARKER_BWD_POS_RELATIVE              number of blocks to skip backward 
                                       relative to our current position

Arguments

msgItem
Item of the request message.
reqMsg
Pointer to the DSRequestMsg message that is formatted and sent to the DataStreamer. A value of NULL forces creation of an internal DSRequestMsg message and synchronous operation.
streamCBPtr
Pointer to the Stream context block
markerValue
the Stream location, normally defined as a DataStreamer clock value.
options
options to specify marker handling and flushing.

Messages

The members of reqMsg are set to the following values:

whatToDo
kDSOpGoMarker
msg.goMarker.markerValue
markerValue
msg.goMarker.options
options

Return Value

Value
Error Condition
0
None
These values are returned if the DataStreamer encounters an error while processing the message request:

kDSInvalidDSRequest
Invalid message (whatToDo set to invalid value)
kDSNoReplyPortErr
Could not locate item of the reply port
-1
Could not locate pointer to msgItem
(Portfolio error code)
SendMsg() or WaitPort() failed
The DataStreamer checks the validity of messages only if message checking is enabled when the DataStreamer is compiled (if the VALIDATE_REQUEST_CODE symbol is enabled).

See "Error Messages" in the 3DO Portfolio Reference Manual for a listing of error messages returned by SendMsg() and WaitPort().

Associated Files

DataStreamLib.h

See Also

DSIsMarker