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

C H A P T E R 2 3
Endpoint Interface
23-20 Using the Endpoint Interface
IMPORTANT
Do not call the Input or Partial methods in a polling loop to
look for incoming data. The Newton communications architecture
requires a return to the main event loop in order to process
incoming data from the endpoint’s underlying communication
tool. These methods are included as an alternate way of retrieving
data from the incoming data buffer, not as a way to implement
synchronous data receives.
▲
To flush data from the input buffer, you can use the methods FlushInput and
FlushPartial . The FlushInput method discards all data in the input buffer,
and FlushPartial discards all data read by the last call to the Partial method.
Streaming Data In and Out 23
Besides protoBasicEndpoint , there is another type of endpoint proto called
protoStreamingEndpoint . The purpose of this streaming endpoint is to
provide a way to send and receive large frames without having first to flatten or
unflatten them.
Flattening refers to the process of converting a frame object into a stream of bytes.
Unflattening refers to the process of converting those bytes back into a frame object.
With the streaming endpoint, frame data is flattened or unflattened in chunks as it is
sent or received. This allows large objects to be sent and received without causing
the NewtonScript heap to overflow as a result of having to convert an entire object
at once.
The protoStreamingEndpoint proto is based on protoBasicEndpoint
and includes a method, StreamIn , that allows you to receive streamed data. This
method automatically unflattens received data into a frame object in memory, and
can place embedded virtual binary objects directly on a store. Another method,
StreamOut , allows you to send frame data as a byte stream. Note that these two
methods are synchronous; that is, they don’t return until the operation is complete.
However, they do provide progress information during the operation by means of a
periodic callback.
Working With Binary Data 23
For receiving binary data, the data is returned as a raw byte stream. The data is not
converted and is block-moved directly into a binary object that you have
preallocated and specified as the target for the input.
To create this target object, specify a target frame in your input spec. This frame
contains a data slot and optionally an offset slot. The data slot contains the
preallocated binary (or virtual binary) object, while the offset slot is the offset