C H A P T E R 2 3
Endpoint Interface
23-2
About the Endpoint Interface
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.
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.
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.
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.
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
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.)
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
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.
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.