Endpoint Interface

Using the Endpoint Interface

within the binary object at which to stream data. For more information on receiving
binary data and using the

target

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

target

frame in the output spec. Within the

target

frame, the

offset

slot

defines the offset from the beginning of the binary object at which to begin sending
data, and the

length

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

Translate

, you can flatten a frame. Then you can packetize the transmission by

using the

target

frame in the output spec.

On the receiving end, you can preallocate a virtual binary object, and then assemble
the packets using the

target

frame in the input spec. Once all binary data has

been received, you can unflatten the frame using the

Translate

function again.

Canceling Operations

23

To stop endpoint operations, you can use the endpoint method

Cancel

or

Disconnect

. 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

CompletionScript

message resulting from the

Cancel

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

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.