Endpoint Interface

About the Endpoint Interface

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.