Sends a control message.

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

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.

• 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.

The members of reqMsg are set to the following values:

• whatToDo kDSOpControl

• msg.control.streamType streamType

• msg.control.userDefinedOpcode

• msg.control.userDefinedArgPtr

• 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().

DataStreamLib.h