Apple Newton Programmer’s Newton 2.0 (for Newton 2.0) User Manual

Page 497

C H A P T E R 1 1

Data Storage and Retrieval

Using Newton Data Storage Objects

11-65

▲

W A R N I N G

Any callback function registered by the

RegSoupChange

function must not call either of the

RegSoupChange

UnRegSoupChange

functions.

▲

The second argument to the

RegSoupChange

function can be any unique symbol

that identifies the callback to be registered. If your application registers only one
callback function, you can just use your application symbol as the callback
identifier (ID). A callback ID need only be unique within the registry that uses it.
For example, no two power registry callback functions can share the same callback
ID; on the other hand, your application’s power registry callback can use the same
ID as your application’s login screen callback. Thus, if your application only
registers one callback function with each of the various registries, all of your
callback functions can use your application symbol (with developer signature) as
their callback ID.

To generate unique identifiers for multiple callbacks within the same registry, you
can prefix an additional identifier to your application symbol. For example, the
symbol

'|myFn1:MyApp:MySig|

could be used to identify one of several

callback functions registered by the

MyApp:MySig

application.

Unregistering Your Application for Change Notification

When your application no longer needs to be notified of changes to a particular
soup, it needs to call the

UnRegSoupChange

function to unregister its callback

function for that soup.

// unregister my app’s Names soup callback

UnRegSoupChange(ROM_CardFileSoupName, '|myFn1:MyApp:MySig|);

Normally, you can unregister your soup change callbacks in the

viewQuitScript

method of your application’s base view.

Responding to Notifications

When a soup changes in some way, the system executes the callback functions
registered for that soup. Note that the system does not consider the soup to have
changed until an entry is written to the soup. Thus, changing a cached entry is not
considered a change to the soup until the

EntryChangeXmit

function writes the

cached entry back to the soup.

Note

The system-supplied Preferences application sends
soup change notifications only if your application
uses the

RegUserConfigChange

function to register

for such notifications.

◆