Description of Methods and Functions

Soup Change Notification


RegSoupChange(soupName, uniqueSymbol, callbackFunc)


You call this function to register your application for notification of changes to soups.

soupname
The name of the soup that triggers notification.

uniqueSymbol
The parameter (normally your application symbol) that is used as a unique key so more than one function can be registered for a given soup.

callbackFunc
A function that will be called whenever a change is made to the soup.


Note:Soup change notification is done by a number of functions and methods which modify soups and whose names end in Xmit. Whenever such a function is called, any callback function registered for the soup that is changed is called automatically.



callbackFunc(soupName, changeSymbol, changeType, changeData)


The callback function you pass to RegSoupChange should take four parameters:

soupName
This is the soup that has changed (it is possible to register the same function for more than one soup).

changeSymbol
This is the symbol passed to the Xmit routine (normally the application symbol of the application that made the change).

changeType
This specifies what kind of change was made.

changeData
This contains more specific information about the change.

TABLE 9.1 shows the possible values of changeType.


Note:The quirky, but inventive, Newton engineer responsible for the 'whatThe symbol is also the creator of the equally memorable: 'holdYourHorses return result for functions that wish to postpone the power-down process, and the SuckPackageFromEndpoint method which creates a package from a bytestream. Can you imagine Newton programming if this engineer were given absolute naming control over the entire OS? Interesting thought, isn't it.



UnRegSoupChange(soupName, uniqueSymbol)


This function unregisters an application for soup change notification. The soupName and uniqueSymbol parameters have the same meaning as for RegSoupChange.

Values passed as changeType parameter to RegSoupChange callback function.
changeTypeexplanation
'entryAddedAn entry has been added to the soup with AddXmit, AddToDefaultStoreXmit, or AddToStoreXmit.
'entryRemovedAn entry has been removed from the soup with EntryRemoveFromSoupXmit.
'entryChangedAn entry in the soup has been modified with EntryChangeXmit or EntryUndoChangesXmit.
'entryMovedAn entry in the soup has been moved from one store to another store with EntryMoveXmit.
'entryReplacedAn entry has been replaced with EntryReplaceXmit.
'soupInfoChangedThe soup information in a soup has been changed with SetInfoXmit or SetAllInfoXmit.
'soupEntersA member soup has entered the union soup because of a new store.
'soupLeavesA member soup has left the union soup because a store has been removed.
'soupCreatedA soup has been created explicitly with CreateSoupXmit or automatically by AddToDefaultStoreXmit or AddToStoreXmit.
'soupDeletedA soup has been deleted from a store with RemoveFromStoreXmit.
'soupTagsChangedThe tag symbols have changed because of RemoveTagsXmit or ModifyTagsXmit.
'soupIndexAddedAn index has been removed from the soup with AddIndexXmit.
'soupIndexRemovedAn index has been removed from the soup with RemoveIndexXmit.
'whatThePassed when the 1.x OS function BroadcastSoupChange is called. Something in the soup has changed, but no further information is available.


An online version of Programming for the Newton using Macintosh, 2nd ed. ©1996, 1994, Julie McKeehan and Neil Rhodes.

Last modified: 1 DEC 1996