Apple Newton Programmer’s Newton 2.0 (for Newton 2.0) - Manual (Page 849)

C H A P T E R 2 3
Endpoint Interface
Using the Endpoint Interface 23-21
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.