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

C H A P T E R 2 2
Transport Interface
22-16 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.