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
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."
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
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
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:
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
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.
be called asynchronously.
Flexible input specs. Enhancements include support for time-outs and the
ability to specify multiple termination sequences.
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.
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.
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.