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

C H A P T E R 2 1
Routing Interface
Using Routing 21-13
Storing an Alias to the Target Object 21
When there is a single target object, if there is not enough storage space, or the
target object is larger than a specified size, you can specify that an alias to the
target object, rather than the target object itself, be stored in the
item.body slot.
This can be a soup entry alias or you can implement your own alias handling. You
enable the storing of an alias by setting the
storeAlias slot in the routing format
frame to true . Additionally, you can specify a maximum size limit for target
objects by setting the sizeLimit slot in the routing format frame. If any target
object is larger than the size specified in this slot, and storeAlias is also true ,
an alias to the target object is stored in the item.body slot. To store every target
as an alias, set sizeLimit to 0.
The default SetupItem method provided in the routing format protos reads the
storeAlias slot and performs the appropriate operations if this slot is true ;
otherwise, it assigns the actual target object to the item.body slot, as usual. If an
alias to the target object is stored in the item.body slot, the routing interface also
sets the item.needsResolve slot to true , to signal that the body slot contains
an alias that needs to be resolved.
When it’s time to send an item, the format ResolveBody method is used to resolve
an alias before the item is sent. The item won’t be sent until the alias is resolved
(
ResolveBody returns a non- nil value), since there’s no point in sending an alias.
If an alias to an item is stored, the item can still be viewed and operated upon in the
In/Out Box, just like any other item.
Note that there are some potential problems if an alias to the target object is stored.
If the target entry resides on a card store, and the card is removed before the item is
actually sent from the Out Box, the alias cannot be resolved and the send operation
on that item will fail. No matter where the original object resides, even if it is simply
deleted, the send operation on that item will fail. Therefore, whenever an alias is
stored, the user is warned by an alert slip explaining that the original item must be
available when the routed item is actually sent. You can set the routing format slot
showMessage to nil to prevent the warning message from being displayed.
Another problem with storing an alias is that the alias is just a pointer to the
original data. For example, say the user faxes a note and chooses to send it later,
and you store an alias to the note in the Out Box. Then the user opens the fax item
in the Out Box and changes the note. This actually changes the original note in the
Notes application, since the alias is a pointer to the original soup entry. Similarly, if
the user changed the original note before the fax was sent, then the fax text would
be changed without the user being aware of it.
Most target objects are soup entries, for which the routing format protos can handle
the operations of determining the object size, making an alias, and resolving the
alias when needed. However, in some cases, you may want to route objects that are
not soup entries. If you want to create custom aliases to such objects, you must