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

C H A P T E R 2 2
Transport Interface
22-10 Using the Transport Interface
Some transports may ignore the ReceiveRequest message, since they receive
data continuously. Others may use this message as a trigger to initiate a connection.
You can choose to comply with or ignore any request to receive, depending on the
communication resources available and their status. If you choose to comply, the
ReceiveRequest method should establish a connection and begin receiving by
whatever means the transport uses to communicate. For example, many transports
use the Endpoint interface to establish and operate a connection. After receiving the
item, you should call the transport method
NewFromItem to copy it into a
standard item frame used by the In/Out Box. Finally, you must call
ItemCompleted to write the item to the In Box.
If your transport creates virtual binary objects, you must use the method
GetDefaultOwnerStore to determine on which store to create them.
Note
The body slot within every received item must have a class slot
to identify its data class. Data objects received from other Newton
devices always have a
class slot. For data received from other
systems, your transport must assign a meaningful class to the
item.body object. ◆
Deferring Reception of the Item Data 22
Some transports might want to download just part of an item initially, such as its
title, then download the actual item data when a user requests it. For example, upon
connection an e-mail transport might download just the titles of messages or other
data objects. When the user attempts to view one of these items in the In Box, the
transport then downloads the body of the item from the remote host.
This feature is accomplished by the use of the cause slot in the parameter passed
to the ReceiveRequest method, and by the use of a remote slot in the item frame.
If a transport initially downloads just a part of each item, such as its title, it must
insert a slot called
remote , whose value is true in the item frame of those items.
This slot serves as a flag to tell the In/Out Box that the body of the item is stored
remotely and has not yet been downloaded.
When the user attempts to view one of these items in the In Box, the In Box sees
the
remote slot, and sends the transport the ReceiveRequest message with the
'remote cause. This alerts the transport to download the body of the item from
the remote host. If the user selected multiple remote items for downloading, you
must use the
ItemRequest method to retrieve subsequent requested items and
download them. Keep calling ItemRequest until it returns nil , which signals
that there are no more items to retrieve.