# 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