Endpoint Interface

Using the Endpoint Interface

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