Transport Interface

Using the Transport Interface

After sending an item (successfully or unsuccessfully), you must call

ItemCompleted

to inform the In/Out Box. If there was an error,

the

ItemCompleted

method informs the In/Out Box that an item was not sent.

ItemCompleted

uses

HandleError

to inform the user of an error. If you want

to perform your own error notification, you can override the

HandleError

method.

Sending All Items

22

If your transport establishes a connection, and you want to take advantage of it to
send all queued items from the Out Box, you can send your transport the message

CheckOutbox

. This method is defined in

protoTransport

and it causes the

In/Out Box to send your transport a

SendRequest

for all queued items waiting to

be sent. The

SendRequest

message sent back to your transport includes a request

argument in which the

cause

slot is set to

'user

.

Applications can also send the

CheckOutbox

message directly to transports by

using the

TransportNotify

global function.

Note that a side effect of the

CheckOutbox

message is that if there is nothing to

send, an alert explaining that is displayed to the user. If you want to perform this
operation but avoid the alert in that case, you can use the function

QuietSendAll

.

This function causes the In/Out Box to send your transport a

SendRequest

for all

queued items waiting to be sent, however the

cause

slot of the

SendRequest

argument is set to

'periodic

.

Converting an E-Mail Address to an Internet Address

22

If you are implementing a new e-mail transport that communicates with another
e-mail system, you may need to convert e-mail addresses from that system to
Internet-compatible addresses. The transport method

NormalizeAddress

allows

you to do this. You pass it a name reference containing an e-mail address, and it
returns a string containing an Internet-compatible e-mail address.

To register a new e-mail system so that it shows up on e-mail pickers throughout
the system and to register a conversion for Internet addresses, use the function

RegEmailSystem

.

Receiving Data

22

The Out Box sends the

ReceiveRequest

message to your transport to request

the transport to receive items. If your transport supports receiving data, you must
define this method to receive it. For a complete description of the

ReceiveRequest

method, see "ReceiveRequest" (page 19-32) in Newton

Programmer's Reference.

The

ReceiveRequest

method takes one parameter, a frame containing a

cause

slot whose value is a symbol.