C H A P T E R 2 3
Using the Endpoint Interface
within the binary object at which to stream data. For more information on receiving
binary data and using the
frame, see the section "Specifying the Data
Form and Target" beginning on page 23-13.
For sending data, the data is expected to be a binary object and is interpreted as a
raw byte stream. That is, the data is not converted and is passed directly to the
communication tool. This is the default data form for sending binary objects.
If you wish to send only a portion of your binary data at once, you can specify a
frame in the output spec. Within the
defines the offset from the beginning of the binary object at which to begin sending
data, and the
slot defines the length of the data to send.
These binary capabilities are very useful if you wish to send and receive flattened
frames "packetized" for a communication protocol. By using the global function
, you can flatten a frame. Then you can packetize the transmission by
frame in the output spec.
On the receiving end, you can preallocate a virtual binary object, and then assemble
the packets using the
frame in the input spec. Once all binary data has
been received, you can unflatten the frame using the
To stop endpoint operations, you can use the endpoint method
. Endpoint operations can also be canceled indirectly as a result of a
time-out expiring. Remember that you can set a time-out for a request in the
callback spec that you pass to most endpoint methods, and you can set a time-out
in an input spec.
Note that you cannot specify what is canceled. When you or the system cancel
operations, all outstanding synchronous and asynchronous requests are canceled.
The cancellation process proceeds differently depending on whether you are
canceling asynchronous or synchronous requests that you have previously queued.
Following a cancellation, it is safe to proceed with other endpoint operations at
different times, according to the following rules:
If you use only asynchronous calls in your application, you can safely proceed
after you receive the
message resulting from the
call (or from the method whose time-out expired).
If you use only synchronous calls in your application, you can safely proceed
after the cancelled synchronous call throws an exception as a result of the
Mixing asynchronous and synchronous methods in your application is not
recommended. However, if you do so, you should treat the cancellation process as
if you had used all synchronous calls, and proceed only after an exception is thrown.