Endpoint Interface

Using the Endpoint Interface

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