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

C H A P T E R 2 3
Endpoint Interface
Using the Endpoint Interface 23-23
Next, the Cancel (or Disconnect ) method returns, and any pending
synchronous request is canceled by throwing an exception that contains error code
–16005. Or, if the cancellation was invoked as the result of a time-out expiration,
then whatever method timed out throws an exception containing error code –16005.
Other Operations 23
The Option method allows you to get and set options apart from the options
parameter to the Bind , Connect , Listen , Accept , and Output methods.
You can check the state of a connection by calling the State method.
Custom communication tools can return special events to the endpoint object
through the
EventHandler message. This message is sent to the endpoint
whenever an event occurs that is not handled by one of the usual endpoint event
handlers. A custom communication tool and an endpoint can use this mechanism to
pass events from the communication tool up to the endpoint layer.
Error Handling 23
By specifying an ExceptionHandler method in your endpoint, you can handle
exception conditions not caught by local try...onexception clauses, as well
as exceptions not caught by CompletionScript methods.
When you call an endpoint method synchronously, and an error occurs in that
method, the system throws an exception (usually of type
|evt.ex.comm| ). You
can catch these exceptions in your application by using the try . . .
onexception construct. It’s a good idea to bracket every endpoint method call
with this exception catching construct.
If an error occurs as a result of an asynchronous request, no exception is thrown,
but the error is returned in the
result parameter to the CompletionScript
method associated with that request. If you did not define a CompletionScript
method, or if the error is unsolicited, the error is forwarded to your
ExceptionHandler method. If you did not define an ExceptionHandler
method, then the communication system throws an exception. This exception is
caught by the operating system, which displays a warning message to the user.
Constants for error codes generated by the Endpoint interface are defined in
“Endpoint Error Code Constants” (Table 20-4 on page 20-4) in
Newton
Programmer’s Reference .
When you use the Option method (or any method that takes options as a
parameter), not only can the method itself fail, but a failure can occur in processing
each of the individual option requests. If the latter happens, the
result slot in the
returned option frame is set to one of the option error codes listed in “Option Error
Code Constants” (Table 20-5 on page 20-5) in
Newton Programmer’s Reference . If