# DSSubscribe

Subscribes to a data stream.

### Synopsis

`int32 DSSubscribe (Item msgItem, DSRequestMsgPtr reqMsg, DSStreamCBPtr streamCBPtr, DSDataType dataType, Item subscriberPort)`

### Description

Sends a subscription request to the DataStreamer. The subscribing process receives a stream of the specified type of data. It is possible to subscribe to a stream even if it isn't running.

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

`dataType`
  Type of data to be supplied by the DataStreamer.

`subscriberPort`
  DataStreamer port from which the subscriber receives data.

### Messages

The members of `reqMsg` are set to the following values:

`whatToDo`
  kDSOpSubscribe

`msg.subscribe.dataType`
  dataType

`msg.subscribe.subscriberPort`

### Return Value

Value
  Error Condition

(First free entry in the memory pool)

Subscriber exists for data type

`kDSubMaxErr`
  Maximum number of subscribers already connected.

`kDSNoMsgErr`
  Could not allocate initialization reply message

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