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