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

C H A P T E R 2 3
Endpoint Interface
About the Endpoint Interface 23-7
Endpoint Options 23
You configure the communication tool underlying an endpoint object by setting
endpoint options. An endpoint option is specified in an endpoint option frame that
is passed in an array as an argument to one of the endpoint methods. Options select
the communication tool to use, control its configuration and operation, and return
result code information from each endpoint method call. An alternative way to set
options is to directly call the endpoint
Option method.
There are three kinds of options you can set, each identified by a unique symbol:
■ 'service options, which specify the kind of communication service, or tool,
to be controlled by the endpoint
■ 'option options, which control characteristics of the communication tool
■ 'address options, which specify address information used by the
communication tool
For details on the particular options you can use with the built-in communication
tools, see Chapter 24, “Built-in Communications Tools.”
Compatibility 23
The protoBasicEndpoint and protoStreamingEndpoint objects and all
the utility functions described in this chapter are new in Newton system software
version 2.0. The
protoEndpoint interface used in system software version 1.x is
obsolete, but still supported for compatibility with older applications. Do not use
the
protoEndpoint interface, as it will not be supported in future system
software versions.
Specific enhancements introduced by the new endpoint protos in system software
2.0 include the following:
■ Data forms. You can handle and identify many more types of data by tagging it
using data forms specified in the
form slot of an option frame.
■ Asynchronous behavior and callback specs. Most endpoint methods can now
be called asynchronously.
■ Flexible input specs. Enhancements include support for time-outs and the
ability to specify multiple termination sequences.
■ Better error handling. Consistent with other system services, errors resulting
from synchronous methods are signaled by throwing an exception.
■ Binary data handling. The way binary (raw) data is handled has changed
significantly. For input, you can now target a direct data input object, which
results in significantly faster performance. For output, you can specify offsets
and lengths, which allows you to send the data in chunks.