The endpoint object created from this proto encapsulates and maintains the details of the specific connection. It allows you to control the underlying communication tool to perform your communication tasks.

The Endpoint interface uses an asynchronous, state-driven communications model. In asynchronous operation, communication requests are queued, and control is returned to your application after each request is made but before it is completed. Many endpoint methods can also be called synchronously. In synchronous operation, execution of your application is blocked until the request completes; that is, the endpoint method does not return until the communication operation is finished.

The Endpoint interface supports multiple simultaneous connections. That is, you can have more than one active endpoint at a time. Each endpoint object controls an underlying communication tool, and these tools run as separate operating system tasks. However, remember that the endpoint objects you create and control all execute within the single Application task.

The number of simultaneously active endpoints you can use is limited in practice by available system memory and processor speed. Each communi-cation tool task requires significant memory and processor resources. Note that memory for the communication tools that underlie endpoints is allocated from the operating system domain, whereas memory for the endpoint objects is allocated from the NewtonScript heap.

Asynchronous Operation

23

Almost all endpoint methods can be called asynchronously. This means that calling the method queues a request for a particular operation with the underlying communi-cation tool task, and then the method returns. When the operation completes, the communication tool sends a callback message to notify the endpoint that the request has been completed. The callback message is the

CompletionScript

message, and it is defined by your application in a frame called the callback specification, or callback spec. (For more details, see "Callback Spec Frame" (page 20-9) in Newton Programmer's Reference.)

You define the callback spec frame in your application and pass it as an argument to each endpoint method you call asynchronously. The callback spec frame contains slots that control how the endpoint method executes, and it contains a

CompletionScript

method that is called when the endpoint operation

completes. The

CompletionScript

method is passed a result code parameter

that indicates if the operation completed successfully or with an error.

A special type of callback spec, called an output spec, is used with the

Output

method. An output spec contains a few additional slots that allow you to pass special protocol flags and to define how the data being sent is translated. Output specs are described in "Output Spec Frame" (page 20-10) in Newton Programmer's Reference.