DSControl

Sends a control message.

Synopsis

int32 DSControl (Item msgItem, DSRequestMsgPtr reqMsg, DSStreamCBPtr streamCBPtr, DSDataType streamType, long userDefinedOpcode, void* userDefinedArgPtr)

Description

Sends a control message to the DataStreamer, which broadcasts it to all subscribers receiving data of the type specified by streamType.

DSControl() sets

the members of the message data structure required to identify it as a control message
the type of stream to which it should be broadcast
the actual action code. (The message is the DSRequestMsg identified by reqMsg.)

If a message is specified, DSControl() sends the message and returns immediately. If no message is specified (if reqMsg is NULL), DSControl() creates a message, sends it to the DataStreamer, and waits until the message has been received before returning.

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.

streamType: Type of stream to which the control message applies.

userDefinedOpcode: Defined by the subscriber.

userDefinedArgPtr: Defined by the subscriber.

Messages

The members of reqMsg are set to the following values:

whatToDo: kDSOpControl



msg.control.streamType
streamType


msg.control.userDefinedOpcode



msg.control.userDefinedArgPtr


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