Transport Interface

Using the Transport Interface

if dataDef then

begin
item.fromRef := dataDef:MakeNameRef(persona,

addressingClass);

// add other slots or extract routing info here
end;

item;

end;

During a receive operation, the transport itself must invoke the

NewFromItem

method to get a new In/Out Box item frame. This method copies most slots from
the received item to the new In/Out Box item frame. Additionally, it inserts the

destAppSymbol

slot value (if included) in the received frame into the

appSymbol

slot in the new frame.

Finally, the transport should call

ItemCompleted

to register the item in the In

Box (see the following section).

Completion and Logging

22

After your transport finishes processing an item (either sending or receiving, with
or without errors), you must send the transport the message

ItemCompleted

.

This method must be used when an item is altered in any way. It performs several
operations, including setting the state and error status of the item; sending the

ItemCompletionScript

callback message to the application; handling error

conditions; and saving, logging, or deleting the item, depending on the logging
preferences.

Send the

ItemCompleted

message only after your transport has completely

processed an item. If you send this message before you know that the item was
delivered successfully, for example, there's a possibility that the item will be lost.

If

ItemCompleted

was called as the result of an error, it calls

HandleError

to

translate the error code and notify the user. If you want to perform your own error
notification, you can override the

HandleError

method.

Note that the

ItemCompleted

method in

protoTransport

sends the

ItemCompletionScript

callback message to the application only if the item

contains a

completionScript

slot that is set to

true

. You must set this slot

if you want the callback message to be sent. For more information on

ItemCompletionScript

see Newton Programmer's Reference (page 18-33).

To perform logging,

ItemCompleted

sends your transport the message

MakeLogEntry

, passing a log entry to which you can add slots. The

protoTransport

object includes a default

MakeLogEntry

method, but you

should override this method to add transport-specific slots to the log entry.

The default method simply adds a

title

slot to the log entry. The

GetItemTitle

transport method is called to get the title.