Routing Interface

Using Routing

If your application does not have a

lastFormats

slot, or if a matching format

is not found (the format was unregistered), the first format found becomes the
current format.

It is your responsibility to save the

lastFormats

frame to a soup if you want to

maintain it, since this information is cleared on a system reset or if your application
is uninstalled.

Supplying the Target Object

21

Next, the Routing interface sends the

SetupItem

message to the current format.

This message informs the format that it is selected and an item is being routed. The

SetupItem

method is passed two parameters: a partially initialized item frame,

and a target information frame, as returned by

GetTargetInfo

. The item frame

is obtained from the transport method

NewItem

, which creates a new Out Box

item frame containing some default slots and values. This is the frame that is to be
stored in the Out Box. It must be filled in with the data object being sent.

The target information frame contains two important slots,

target

and

targetView

, which define the data object to be routed and the view that contains

it, respectively. The

SetupItem

method must set the

body

slot of the item frame

to the value contained in the

target

slot of the target information frame. This fills

in the item frame with the actual data to be sent.

You are not required to provide a

SetupItem

method in routing formats since this

method is defined in the routing format protos. The

SetupItem

method defined in

the protos simply assigns the

target

slot in the target information frame to the

body

slot of the item frame. You can override this method if you want to perform

additional operations and still call the inherited

SetupItem

method. Note that

there's a potential problem with not copying the target object. If the object is
viewable and editable and the user edits the object in the Out Box, that potentially
changes the original object stored by the application, since there are potentially not
two separate objects, but two pointers to the same object.

If you want to modify the

body

slot of the item in some way, you should supply

your own

SetupItem

method instead of calling the inherited version. Then

in your own

SetupItem

method, clone the

target

slot of the target information

frame into the

body

slot of the item frame.

When sending data to another Newton device (for example, by beaming) it's a
good idea to ensure that the sent object contains a

version

slot (inside the

item.body

frame) that holds the current version of your application. This will help

to reduce compatibility problems in future versions of your application. If the data
format changes, your application can easily identify older and newer data formats.