# DSConnect

Connects to the DataStreamer.

### Synopsis

`int32 DSConnect (Item msgItem, DSRequestMsgPtr reqMsg, DSStreamCBPtr streamCBPtr, Item acquirePort)`

### Description

Sends a message to the DataStreamer requesting a data acquisition connection. `DSConnect()` is normally used to initialize a data acquisition source for a stream or to switch between data acquisition sources.

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

When the DataStreamer connects to a new acquisition thread, it sends a disconnect message to the previous acquisition thread.

Passing NULL as the acquirePort argument causes a disconnect.

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

`acquirePort`
  DataStreamer port to which a connection is requested. If NULL, causes a disconnect.

### Messages

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

`whatToDo`
  kDSOpConnect

`msg.connect.acquirePort`
  acquirePort

### Return Value

Value
  Error Condition

(First Free entry in the memory pool)

`kDSInvalidDSRequest`
  Could not acquire port specified by `acquirePort`

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 only the validity of messages if message checking is enabled when the DataStreamer is was compiled (if the `VALIDATE_REQUEST_CODE` symbol was enabled). `DSConnect()` checks whether it can acquire the specified port only if port checking is enabled when the DataStreamer is compiled (if the `VALIDATE_CONNECT_PORT` 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

`NewDataAcq`