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

C H A P T E R 2 3
Endpoint Interface
About the Endpoint Interface 23-3
This kind of asynchronous operation lends itself nicely to creating state-machine
based code, where each part of the communication process is a state that is invoked
by calling an endpoint method. The
CompletionScript method of each state
invokes the next state, and the state machine automatically progresses from one
state to the next in a predefined fashion.
Synchronous Operation 23
Many endpoint methods can be called synchronously as well as asynchronously.
Synchronous operation means that invoking a method queues a request for a
particular operation with the underlying communication tool task, and the method
does not return until the operation is completed. This means that your application is
blocked from execution until the synchronous method returns.
Only a few endpoint methods must be called synchronously. Most can be called
either asynchronously or synchronously. For methods that can be called in either
mode, it is recommended that you use the asynchronous mode whenever possible.
If you call such a method synchronously, the communication system spawns a
separate task associated with the method call, while putting your application task
on hold. This results in higher system overhead and can reduce overall system
performance if you use many synchronous method calls.
Input 23
In the Endpoint interface, you receive data by defining a frame called an input
specification, or input spec, and then waiting for input. The input spec defines how
incoming data should be formatted, termination conditions that control when the
input should be stopped, data filtering options, and callback methods. The main
callback method is the
InputScript method, which is passed the received data
when the input operation terminates normally. Receiving data with the Endpoint
interface is always asynchronous.
Here is an overview of the way you can use input spec methods to obtain the
received data:
■ Let the termination conditions specified in the input spec be triggered by the
received data, thus calling your
InputScript method. For example, when a
particular string is received, the InputScript method is called.
■ Periodically sample incoming data by using the input spec PartialScript
method, which is called periodically at intervals you specify in the input spec.
■ Cause the system to send the InputScript callback method by using the
Input method. This immediately returns the contents of the input buffer and
clears it.
■ Immediately return the input buffer contents without terminating the active input
spec and without clearing the buffer by using the
Partial method.