DSConnect

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