Documentation  |   Table of Contents   |  < Previous   |  Next >   |  Index

11    Notification Manager

Programming Basics

Exploring Palm OS®

This chapter provides reference documentation for the Notification Manager APIs. These APIs include both the functions that you use to register and unregister to receive a notification and the functions you use to broadcast a notification, plus the definitions of many of the notifications themselves.

The contents of this chapter are organized as follows:

Notification Manager Structures and Types
Notification Manager Constants
Notification Manager Notifications
Notification Manager Functions and Macros
Application-Defined Functions

The header file NotifyMgr.h declares the API that this chapter describes.

See Chapter 4, "Notifications," for an introduction to notifications and their use. For a complete list of all notifications broadcast by Palm OS, see "Notification Summary."

Notification Manager Structures and Types ^TOP^

SleepEventParamType Struct ^TOP^

Purpose

Notification-specific data that accompanies a sysNotifySleepRequestEvent notification. This structure indicates why the device is going to sleep and allows a handler to prevent the device from sleeping.

Declared In

NotifyMgr.h

Prototype

typedef struct SleepEventParamTag {
   uint16_t reason;
   uint16_t deferSleep;
} SleepEventParamType

Fields

reason
The reason the system is going to sleep. See "Reasons for Device Sleep" for the set of possible values for this field.
deferSleep
Initially set to 0. If a notification handler wants to defer sleep, then it should increment this value. When deferSleep is greater than 0, the system waits before going to sleep.

SysNotifyAppLaunchOrQuitType Struct ^TOP^

Purpose

Notification-specific data intended to accompany a sysNotifyAppLaunchingEvent notification. Because that notification is not sent in Palm OS Cobalt, however, this structure isn't used.

Declared In

NotifyMgr.h

Prototype

typedef struct SysNotifyAppLaunchOrQuitTag {
   uint32_t version;
   uint32_t dbID;
   uint16_t cardNo;
   uint16_t padding;
} SysNotifyAppLaunchOrQuitType

SysNotifyDBAddedType Typedef ^TOP^

Purpose

Notification-specific data that accompanies a sysNotifyDBAddedEvent notification. This structure identifies the newly-added database.

Declared In

NotifyMgr.h

Prototype

typedef SysNotifyDBCreatedType 
SysNotifyDBAddedType;

Comments

SysNotifyDBAddedType is equivalent to SysNotifyDBCreatedType. See that structure's documentation for details.

SysNotifyDBChangedType Struct ^TOP^

Purpose

Notification-specific data that accompanies a sysNotifyDBChangedEvent notification. This structure indicates what about the database has changed.

Declared In

NotifyMgr.h

Prototype

typedef struct SysNotifyDBChangedTag {
   DatabaseID dbID;
   char name[dmDBNameLength];
   uint32_t creator;
   uint32_t type;
   uint16_t attributes;
   uint16_t version;
   uint32_t crDate;
   uint32_t modDate;
   uint32_t bckUpDate;
   uint32_t modNum;
   MemHandle appInfoH;
   MemHandle sortInfoH;
   char displayName[dmDBNameLength];
   uint16_t encoding;
   uint16_t fields;
   char oldName[dmDBNameLength];
   uint32_t oldCreator;
   uint32_t oldType;
   uint16_t oldAttributes;
   uint16_t reserved;
} SysNotifyDBChangedType

Fields

dbID
Database ID.
name
New name of database.
creator
New database creator ID.
type
New database type.
attributes
New database attributes.
version
New database version.
crDate
New database creation date.
modDate
New database modification date.
bckUpDate
New database backup date.
modNum
New database modification number.
appInfoH
New database application info block.
sortInfoH
New database sort info block.
displayName
New database display name.
encoding
New database encoding.
fields
Flags that indicate what about the database changed, and thus which of the above fields are set. See "Database Changed Flags" for the set of flags that can be combined to make up this value.
oldName
Name of database prior to the call to DmSetDatabaseInfo.
oldCreator
Database creator ID prior to the call to DmSetDatabaseInfo.
oldType
Database type prior to the call to DmSetDatabaseInfo.
oldAttributes
Database attributes prior to the call to DmSetDatabaseInfo.
reserved
Reserved for future use.

SysNotifyDBCreatedType Struct ^TOP^

Purpose

Notification-specific data that accompanies a sysNotifyDBCreatedEvent notification. This structure identifies the newly-created database.

Declared In

NotifyMgr.h

Prototype

typedef struct SysNotifyDBCreatedTag {
   DatabaseID newDBID;
   char name[dmDBNameLength];
   uint32_t creator;
   uint32_t type;
   uint16_t attributes;
   uint16_t reserved;
} SysNotifyDBCreatedType

Fields

newDBID
Database ID of the newly-created database.
name
Database name.
creator
Database creator ID.
type
Database type.
attributes
Database attributes.
reserved
Reserved for future use.

SysNotifyDBDeletedType Struct ^TOP^

Purpose

Notification-specific data that accompanies a sysNotifyDBDeletedEvent notification. This structure identifies the newly-deleted database.

Declared In

NotifyMgr.h

Prototype

typedef struct SysNotifyDBDeletedTag {
   DatabaseID oldDBID;
   char name[dmDBNameLength];
   uint32_t creator;
   uint32_t type;
   uint16_t attributes;
   uint16_t reserved;
} SysNotifyDBDeletedType

Fields

oldDBID
The database ID of the deleted database. This ID is no longer valid.
name
The name of the deleted database.
creator
The creator ID of the deleted database.
type
The type of the deleted database.
attributes
The deleted database's attributes.
reserved
Reserved for future use.

Comments


WARNING! The ID in oldDBID is invalid by the time the notification is broadcast. If you try to pass it to a Data Manager function, the system will crash.

SysNotifyDBDirtyType Struct ^TOP^

Purpose

Notification-specific data that accompanies a sysNotifyDBDirtyEvent notification. This structure identifies the newly-deleted database.

Declared In

NotifyMgr.h

Prototype

typedef struct SysNotifyDBDirtyTag {
   DatabaseID dbID;
   char name[dmDBNameLength];
   uint32_t creator;
   uint32_t type;
   uint16_t attributes;
   uint16_t reserved;
} SysNotifyDBDirtyType

Fields

dbID
Database ID.
name
Database name.
creator
Database creator ID.
type
Database type.
attributes
Database attributes.
reserved
Reserved for future use.

SysNotifyDBInfoType Struct ^TOP^

Purpose

Notification-specific data that accompanies a sysNotifyDeleteProtectedEvent notification. This structure identifies the newly-deleted database.

Declared In

NotifyMgr.h

Prototype

typedef struct SysNotifyDBInfoTag {
   MemHandle dbID;
   uint16_t cardNo;
   uint16_t attributes;
   char dbName[dmDBNameLength];
   uint32_t creator;
   uint32_t type;
} SysNotifyDBInfoType

Fields

dbID
Handle to the database to be deleted.
cardNo
The number of the card on which the database resides.
attributes
The database's attributes.
dbName
The name of the database to be deleted.
creator
The creator ID of the database to be deleted.
type
The type of the database to be deleted.

SysNotifyDisplayChangeDetailsType Struct ^TOP^

Purpose

Notification-specific data that accompanies a sysNotifyDisplayChangeEvent notification. This structure contains the old and new display depths.

Declared In

NotifyMgr.h

Prototype

typedef struct SysNotifyDisplayChangeDetailsTag {
   uint32_t oldDepth;
   uint32_t newDepth;
} SysNotifyDisplayChangeDetailsType

Fields

oldDepth
The old bit depth.
newDepth
The new bit depth.

SysNotifyLocaleChangedType Struct ^TOP^

Purpose

Notification-specific data that accompanies a sysNotifyLocaleChangedEvent notification. This structure contains the old and new locales.

Declared In

NotifyMgr.h

Prototype

typedef struct SysNotifyLocaleChangedTag {
   LmLocaleType oldLocale;
   LmLocaleType newLocale;
} SysNotifyLocaleChangedType

Fields

oldLocale
The old locale. See LmLocaleType.
newLocale
The new locale.

SysNotifyParamType Struct ^TOP^

Purpose

Contains all of the data associated with a notification. This structure is passed as the parameter block for the sysAppLaunchCmdNotify launch code or as a parameter to the notification callback function.

Declared In

NotifyMgr.h

Prototype

typedef struct SysNotifyParamType {
   uint32_t notifyType;
   uint32_t broadcaster;
   void *notifyDetailsP;
   void *userDataP;
   Boolean handled;
   uint8_t reserved2;
   uint16_t padding;
} SysNotifyParamType

Fields

notifyType
The type of event that occurred. See Chapter 4, "Notifications."
broadcaster
The creator ID of the application that broadcast the notification, or sysNotifyBroadcasterCode if the system broadcast the event.
notifyDetailsP
Pointer to data specific to this notification.
userDataP
Custom data that your notification handler requires. You create this data and pass it to SysNotifyRegister().
handled
Set this field to true if the notification has been handled; set to false otherwise. In some cases, handled is treated as a bit field that notification handlers can use to indicate that certain conditions are true.
reserved2
Reserved for future use.
padding
Padding bytes.

Comments

The SysNotifyParamType structure contains all of the data associated with a notification. This structure is passed as the parameter block for the sysAppLaunchCmdNotify launch code or as a parameter to the notification callback function. All notifications have some common data. Most notifications also have data specific to that notification. The specific data is pointed to by the notifyDetailsP field.

The common data for each notification is documented below the following structure declaration. Chapter 4, "Notifications," section gives details on the important data associated with each type of notification.

SysNotifyPenStrokeType Struct ^TOP^

Purpose

Notification-specific data that accompanies a sysNotifyProcessPenStrokeEvent notification. Because that notification is not sent in Palm OS Cobalt, however, this structure isn't used.

Declared In

NotifyMgr.h

Prototype

typedef struct SysNotifyPenStrokeTag {
   uint32_t version;
   PointType startPt;
   PointType endPt;
} SysNotifyPenStrokeType

SysNotifyVirtualCharHandlingType Struct ^TOP^

Purpose

Notification-specific data that accompanies a sysNotifyVirtualCharHandlingEvent notification. Because that notification is not sent in Palm OS Cobalt, however, this structure isn't used.

Declared In

NotifyMgr.h

Prototype

typedef struct SysNotifyVirtualCharHandlingTag {
   uint32_t version;
   struct _KeyDownEventType keyDown;
} SysNotifyVirtualCharHandlingType

Notification Manager Constants ^TOP^

Reasons for Device Sleep ^TOP^

Purpose

These constants are part of the notification-specific data that accompanies a sysNotifySleepRequestEvent notification, and indicate why the device is going to sleep.

Declared In

NotifyMgr.h

Constants

#define sysSleepAutoOff 1
The idle time limit has been reached.
#define sysSleepPowerButton 0
The user pressed the power off button.
#define sysSleepResumed 2
The sleep event was deferred by one of the notification handlers but has been resumed through the use of the resumeSleepChr.
#define sysSleepUnknown 3
Unknown reason.

Database Changed Flags ^TOP^

Purpose

Flags that accompany a sysNotifyDBChangedEvent and indicate what about the database changed. Each flag corresponds to one of the fields in the SysNotifyDBChangedType structure.

Declared In

NotifyMgr.h

Constants

#define DBChangedFieldSetAppInfo 0x80
New database application info block. AppInfoH contains a handle to the new application info block.
#define DBChangedFieldSetAttributes 0x200
New database attributes. attributes contains the new database attributes, while oldAttributes contains the database attributes as they were before the change.
#define DBChangedFieldSetBckUpDate 0x20
New database backup date. bckUpDate contains the new backup date.
#define DBChangedFieldSetCrDate 0x8
New database creation date. crDate contains the new creation date.
#define DBChangedFieldSetCreator 0x2
New database creator ID. creator contains the new creator ID, while oldCreator contains the creator ID as it was before the change.
#define DBChangedFieldSetDisplayName 0x800
New database display name. displayName contains the new display name.
#define DBChangedFieldSetEncoding 0x1000
New database encoding. encoding contains the new database encoding.
#define DBChangedFieldSetModDate 0x10
New database modification date. modDate contains the new modification date.
#define DBChangedFieldSetModNum 0x40
New database modification number. modNum contains the new modification number.
#define DBChangedFieldSetName 0x1
New name of database. name contains the new database name, while oldName contains the database name as it was before the change.
#define DBChangedFieldSetSortInfo 0x100
New database sort info block. sortInfoH contains a handle to the new sort info block.
#define DBChangedFieldSetType 0x4
New database type. type contains the new database type, while oldType contains the database type as it was before the change.
#define DBChangedFieldSetVersion 0x400
New database version. version contains the new database version.

Miscellaneous Notification Manager Constants ^TOP^

Purpose

Miscellaneous constants defined by the Notification Manager.

Declared In

NotifyMgr.h

Constants

#define sysNotifyBroadcasterCode sysFileCSystem
#define sysNotifyDefaultQueueSize 100
#define sysNotifyNoDatabaseH ((DatabaseID) 0xFFFFFFFF)
#define sysNotifyNormalPriority 0
Notification priority value used with SysNotifyRegister(). This value indicates "normal" priority.
#define sysNotifyVersionNum 1

Notification Manager Notifications ^TOP^

cncNotifyConnectionStateEvent ^TOP^

Purpose

Broadcast by the Connection Manager whenever a persistent profile is either connected or disconnected.

Declared In

NotifyMgr.h

Prototype

#define cncNotifyConnectionStateEvent 'cncc'


Parameters

The notifyDetailsP field isn't a pointer but instead is a uint32_t that has one of two values: kCncConnectedState if a persistent profile has been connected, or kCncDisconnectedState if a persistent profile has been disconnected.

See Also

Chapter 4, "Notifications"

sysExternalConnectorAttachEvent ^TOP^

Purpose

Broadcast when a USB cradle, RS-232 cradle or peripheral, a power cable, or a modem is attached to the universal connector.

Declared In

NotifyMgr.h

Prototype

#define sysExternalConnectorAttachEvent 'ecna'


Parameters

The notifyDetailsP field points to a uint16_t that identifies which type of device was attached.

Compatibility

This notification is broadcast only on devices that have the universal connector.

See Also

sysExternalConnectorDetachEvent, Chapter 4, "Notifications"

sysExternalConnectorDetachEvent ^TOP^

Purpose

Broadcast when a USB cradle, a RS-232 cradle or peripheral, a power cable, or a modem is detached from the universal connector.

Declared In

NotifyMgr.h

Prototype

#define sysExternalConnectorDetachEvent 'ecnd'


Parameters

The notifyDetailsP field points to a uint16_t that identifies which type of device was detached.

Compatibility

This notification is broadcast only on devices that have the universal connector.

See Also

sysExternalConnectorAttachEvent, Chapter 4, "Notifications"

sysNotifyAltInputSystemDisabled ^TOP^

Purpose

Broadcast by an alternative input system (such as an external keyboard) driver when it becomes disabled.

Declared In

NotifyMgr.h

Prototype

#define sysNotifyAltInputSystemDisabled 'aisd'


Parameters

See Also

sysNotifyAltInputSystemEnabled, Chapter 4, "Notifications"

sysNotifyAltInputSystemEnabled ^TOP^

Purpose

Broadcast by an alternative input system (such as an external keyboard) driver when it becomes enabled.

Declared In

NotifyMgr.h

Prototype

#define sysNotifyAltInputSystemEnabled 'aise'


Parameters

See Also

sysNotifyAltInputSystemDisabled, Chapter 4, "Notifications"

sysNotifyAntennaRaisedEvent ^TOP^

Purpose

Broadcast by SysHandleEvent() when the antenna is raised on a device that is so equipped.

Declared In

NotifyMgr.h

Prototype

#define sysNotifyAntennaRaisedEvent 'tena'


Parameters

None.

Comments

Register for this notification if you want to handle the antenna key down event. To ensure that no other code handles the antenna key down event after yours, set the handled parameter of the SysNotifyParamType structure to true.

See Also

Chapter 4, "Notifications"

sysNotifyAppServicesEvent ^TOP^

Purpose

Declared In

NotifyMgr.h

Prototype

#define sysNotifyAppServicesEvent 'apsv'


Parameters

None.

Comments

See Also

Chapter 4, "Notifications"

sysNotifyCardInsertedEvent ^TOP^

Purpose

Broadcast when an Expansion Manager card is inserted into a slot. When a new card is inserted, the Expansion Manager attempts to mount the volume on that card and plays a sound (indicating success or failure) once the attempt is complete.

Declared In

NotifyMgr.h

Prototype

#define sysNotifyCardInsertedEvent 'crdi'


Parameters

notifyDetailsP points to a uint16_t containing the slot reference number.

Comments

Most applications will want to register for sysNotifyVolumeMountedEvent instead of this notification. Register for sysNotifyCardInsertedEvent if you need to know when a card is inserted or if you want to prevent the Expansion Manager from performing its default handling of the notification.

To prevent the Expansion Manager from mounting the volume, set the expHandledVolume bit in the handled field. To prevent the Expansion Manager from playing the sound, set the expHandledSound bit in the handled field. For example:

cmdPBP->handled |= expHandledSound;

See Also

sysNotifyCardRemovedEvent, sysNotifyVolumeMountedEvent, Chapter 4, "Notifications"

sysNotifyCardRemovedEvent ^TOP^

Purpose

Broadcast when an Expansion Manager card is removed from a slot. When a card is removed, the Expansion Manager responds to this notification by playing a goodbye sound and then attempting to unmount the volume.

Declared In

NotifyMgr.h

Prototype

#define sysNotifyCardRemovedEvent 'crdo'


Parameters

notifyDetailsP points to a uint16_t containing the slot reference number.

Comments

Most applications will want to register for sysNotifyVolumeUnmountedEvent instead of this notification. Register for sysNotifyCardRemovedEvent if you need to know when a card is removed or if you want to prevent the Expansion Manager from performing its default handling of the notification.

To prevent the Expansion Manager from unmounting the volume, set the expHandledVolume bit in the handled field. To prevent the Expansion Manager from playing the sound, set the expHandledSound bit in the handled field. For example:

cmdPBP->handled |= expHandledSound;

See Also

sysNotifyCardInsertedEvent, sysNotifyVolumeUnmountedEvent, Chapter 4, "Notifications"

sysNotifyDBAddedEvent ^TOP^

Purpose

Broadcast when a new database has been added to the device.

Declared In

NotifyMgr.h

Prototype

#define sysNotifyDBAddedEvent 'dbs+'


Parameters

notifyDetailsP points to a SysNotifyDBAddedType structure.

Compatibility

Palm OS Cobalt does not broadcast this notification.

See Also

sysNotifyDBChangedEvent, sysNotifyDBCreatedEvent, sysNotifyDBDeletedEvent, sysNotifySyncFinishEvent, Chapter 4, "Notifications"

sysNotifyDBChangedEvent ^TOP^

Purpose

The sysNotifyDBChangedEvent is broadcast sometime after database info is set with DmSetDatabaseInfo().

Declared In

NotifyMgr.h

Prototype

#define sysNotifyDBChangedEvent 'dbmn'


Parameters

notifyDetailsP points to a SysNotifyDBChangedType structure. The contents of fields in this structure indicates what about the database changed, and thus which of the other structure fields contain valid data.

Comments

Register for this notification if you keep an internal list of databases that needs to be updated when database info changes.


IMPORTANT: The sysNotifyDBxxxEvent notifications are deferred notifications. So, for instance, if your application creates a database, opens it for write, and then renames it, all before EvtGetEvent() is called, the three corresponding notifications will all go out together. A sysNotifyDBDirtyEvent handler would fail if it tried to open the database, since the database will already have been renamed. You must be aware of the ramifications of a deferred notification when writing your notification handler.

See Also

sysNotifyDBAddedEvent, sysNotifyDBCreatedEvent, sysNotifyDBDeletedEvent, sysNotifyDBDirtyEvent, sysNotifySyncFinishEvent, Chapter 4, "Notifications"

sysNotifyDBCreatedEvent ^TOP^

Purpose

Broadcast sometime after a database is created with DmCreateDatabase().

Declared In

NotifyMgr.h

Prototype

#define sysNotifyDBCreatedEvent 'dbcr'


Parameters

notifyDetailsP points to a SysNotifyDBCreatedType structure.

Comments

Register for this notification if you keep an internal list of databases that needs to be updated when a new database is created.


IMPORTANT: The sysNotifyDBxxxEvent notifications are deferred notifications. So, for instance, if your application creates a database, opens it for write, and then renames it, all before EvtGetEvent() is called, the three corresponding notifications will all go out together. A sysNotifyDBDirtyEvent handler would fail if it tried to open the database, since the database will already have been renamed. You must be aware of the ramifications of a deferred notification when writing your notification handler.

See Also

sysNotifyDBAddedEvent, sysNotifyDBChangedEvent, sysNotifyDBDeletedEvent, sysNotifySyncFinishEvent, Chapter 4, "Notifications"

sysNotifyDBDeletedEvent ^TOP^

Purpose

Broadcast sometime after a database is removed from the device.

Declared In

NotifyMgr.h

Prototype

#define sysNotifyDBDeletedEvent 'dbs-'


Parameters

notifyDetailsP points to a SysNotifyDBDeletedType structure.

Comments

Register for this notification if you keep an internal list of databases that needs to be updated upon removal of a database. For example, the Attention Manager and Connection Manager register for this notification to maintain their internal lists of databases.


IMPORTANT: The sysNotifyDBxxxEvent notifications are deferred notifications. So, for instance, if your application creates a database, opens it for write, and then renames it, all before EvtGetEvent() is called, the three corresponding notifications will all go out together. A sysNotifyDBDirtyEvent handler would fail if it tried to open the database, since the database will already have been renamed. You must be aware of the ramifications of a deferred notification when writing your notification handler.

See Also

sysNotifyDBAddedEvent, sysNotifyDBChangedEvent, sysNotifyDBCreatedEvent, sysNotifyDeleteProtectedEvent, sysNotifySyncFinishEvent, Chapter 4, "Notifications"

sysNotifyDBDirtyEvent ^TOP^

Purpose

Broadcast sometime after a database is opened for write or in some other way has been made modifiable. Note that the database may not have actually been modified yet.

Declared In

NotifyMgr.h

Prototype

#define sysNotifyDBDirtyEvent 'dbdr'


Parameters

notifyDetailsP points to a SysNotifyDBDirtyType structure.

Comments

Register for this notification if you keep an internal list of databases that needs to be updated when a database becomes "dirty." For instance, upon reset the Launcher normally checks over such databases and updates its internal list.


IMPORTANT: The sysNotifyDBxxxEvent notifications are deferred notifications. So, for instance, if your application creates a database, opens it for write, and then renames it, all before EvtGetEvent() is called, the three corresponding notifications will all go out together. A sysNotifyDBDirtyEvent handler would fail if it tried to open the database, since the database will already have been renamed. You must be aware of the ramifications of a deferred notification when writing your notification handler.

See Also

sysNotifyDBChangedEvent, Chapter 4, "Notifications"

sysNotifyDeleteProtectedEvent ^TOP^

Purpose

Broadcast when the Launcher attempts to delete a database that has the protected flag set. The Launcher broadcasts the notification and then attempts to delete the database again. Any third party application that deletes databases should broadcast this notification as well.

Declared In

NotifyMgr.h

Prototype

#define sysNotifyDeleteProtectedEvent '-pdb'


Parameters

notifyDetailsP points to a SysNotifyDBInfoType structure.

Comments

Register for this notification if you have a protected database but you still want to allow users to delete your application or other code resource if they choose. A notification handler should check the information in the notifyDetailsP struct to see if its database is the one being deleted. If so, it should respond to this notification to perform any necessary cleanup and to clear the protected flag. In this way, when the Launcher attempts to delete the database again, it will succeed. Note that if an application has multiple protected databases, this notification may be sent out more than once.

See Also

sysNotifyDBDeletedEvent, sysNotifySecuritySettingEvent, Chapter 4, "Notifications"

sysNotifyDeviceUnlocked ^TOP^

Purpose

Broadcast by the Security application when the user unlocks the device. The notification is broadcast immediately after the device has finished unlocking.

Declared In

NotifyMgr.h

Prototype

#define sysNotifyDeviceUnlocked 'unlk'


Parameters

None.

Comments

If you display UI in response to the sysNotifyLateWakeupEvent notification, you should also register to receive the sysNotifyDeviceUnlocked notification. When a locked device receives the sysNotifyLateWakeupEvent, your UI should not be displayed if the device is waiting for the user to enter the password. The sysNotifyDeviceUnlocked notification is broadcast after the password is entered, which indicates that the user interface is ready.

See Also

sysNotifyForgotPasswordEvent, sysNotifySecuritySettingEvent, Chapter 4, "Notifications"

sysNotifyDisplayChangeEvent ^TOP^

Purpose

Broadcast whenever the display mode changes. Either the color table has been set to use a specific palette using the WinPalette() function or the bit depth has changed using the WinScreenMode() function.

Declared In

NotifyMgr.h

Prototype

#define sysNotifyDisplayChangeEvent 'scrd'


Parameters

notifyDetailsP points to a SysNotifyDisplayChangeDetailsType structure.

Comments

The notifyDetailsP field indicates how the bit depth changed. If the two values in the struct are equal, it means that the color palette has changed instead of the bit depth.

See Also

Chapter 4, "Notifications"

sysNotifyEarlyWakeupEvent ^TOP^

Purpose

Broadcast during SysHandleEvent() immediately after the system has finished sleeping.

Declared In

NotifyMgr.h

Prototype

#define sysNotifyEarlyWakeupEvent 'worm'


Parameters

None.

Comments

The screen may still be turned off, and the system may not fully wake up. It may simply handle an alarm or a battery charger event and go back to sleep. Most applications that need notification of a wakeup event will probably want to register for sysNotifyLateWakeupEvent instead.


IMPORTANT: This notification is not guaranteed to be broadcast. Thus, it is not suitable for applications where external hardware must be turned on when the system is powered on.

See Also

sysNotifyResetFinishedEvent, sysNotifySleepNotifyEvent, sysNotifySleepRequestEvent, Chapter 4, "Notifications"

sysNotifyForgotPasswordEvent ^TOP^

Purpose

Broadcast after the user taps the Lost Password button in the Security application. The notification is sent after the user has confirmed that all private records should be deleted but before the deletion actually occurs.

Declared In

NotifyMgr.h

Prototype

#define sysNotifyForgotPasswordEvent 'bozo'


Parameters

None.

See Also

sysNotifyDeviceUnlocked, sysNotifySecuritySettingEvent, Chapter 4, "Notifications"

sysNotifyHostFSInitDone ^TOP^

Purpose

Broadcast by the Host File System library when the library has been initialized.

Declared In

NotifyMgr.h

Prototype

#define sysNotifyHostFSInitDone 'hfid'


Parameters

None.

Comments

This notification allows the AutoMounter to mount volumes on POSE slots.Applications should not register for this notification; it is intended for system use only.

See Also

Chapter 4, "Notifications"

sysNotifyLateWakeupEvent ^TOP^

Purpose

Broadcast during SysHandleEvent() immediately after the device has finished waking up.

Declared In

NotifyMgr.h

Prototype

#define sysNotifyLateWakeupEvent 'lazy'


Parameters

None.

Comments

This notification is sent at the late stage of wakeup, after the screen has been turned on. When this notification is broadcast, the system is guaranteed to fully wake up. Register for this notification if you need to perform startup tasks each time the system wakes up.


IMPORTANT: This notification is not guaranteed to be broadcast. Thus, it is unsuitable for applications where external hardware must be powered on when the device wakes up.

When the device receives this notification, it may be locked and waiting for the user to enter the password. If this is the case, you must wait for the user to unlock the device before you display a user interface. Therefore, if you intend to display a user interface when the device wakes up, you should make sure the device is not locked. If the device is locked, you should register for sysNotifyDeviceUnlocked notification and display your user interface when it is received.

Example

The following code excerpt show how you might respond to this notification:


case sysNotifyLateWakeupEvent:  
  if ((Boolean)  
      PrefGetPreference(prefDeviceLocked)) { 
    SysNotifyRegister(myCardNo, myDbID,  
      sysNotifyDeviceUnlocked, NULL,  
      sysNotifyNormalPriority, NULL); 
  } else { 
    HandleDeviceWakeup(); 
  } 
case sysNotifyDeviceUnlocked:  
  HandleDeviceWakeup(); 

See Also

sysNotifyEarlyWakeupEvent, sysNotifyResetFinishedEvent, sysNotifySleepNotifyEvent, sysNotifySleepRequestEvent, Chapter 4, "Notifications"

sysNotifyLocaleChangedEvent ^TOP^

Purpose

Broadcast immediately after the system locale has changed. Currently, the user has the opportunity to change the locale only when the device first starts up and after a hard reset.

Declared In

NotifyMgr.h

Prototype

#define sysNotifyLocaleChangedEvent 'locc'


Parameters

notifyDetailsP points to a SysNotifyLocaleChangedType structure.

Comments

RAM-based applications and other code resources should obtain locale information by passing the prefLocale constant to PrefGetPreference(). They should not register for this notification. This notification is used by the built-in applications, which respond to it by rebuilding their default databases to use the newly selected language and character set.

See Also

sysNotifyTimeChangeEvent, Chapter 4, "Notifications"

sysNotifyMenuCmdBarOpenEvent ^TOP^

Purpose

Broadcast during MenuHandleEvent() when it is about to display the menu shortcut command bar.

Declared In

NotifyMgr.h

Prototype

#define sysNotifyMenuCmdBarOpenEvent 'cbar'


Parameters

None.

Comments

Register for this notification if you are writing a system extension (such as a "hack" installed with the HackMaster program) that needs to add a button to the menu command bar or to suppress the menu command bar. To add a button, call MenuCmdBarAddButton(). To suppress the command toolbar, set the handled field to true.

Applications that need to add their own buttons to the menu command bar should do so in response to a menuCmdBarOpenEvent. They should not register for this notification because an application should only add buttons if it is already the active application. The notification is sent after the event has been received, immediately before the command toolbar is displayed.

See Also

Chapter 4, "Notifications"

sysNotifyPhoneEvent ^TOP^

Purpose

Reserved for future use.

Declared In

NotifyMgr.h

Prototype

#define sysNotifyPhoneEvent 'fone'


Parameters

Compatibility

This notification is not broadcast in Palm OS Cobalt.

See Also

telNotifyEnterCodeEvent, telNotifyErrorEvent,Chapter 4, "Notifications"

sysNotifyPOSEMountEvent ^TOP^

Purpose

Broadcast by the Host File System to communicate with itself.

Declared In

NotifyMgr.h

Prototype

#define sysNotifyPOSEMountEvent 'pose'


Parameters

notifyDetailsP points to a uint32_t that contains the POSE slot number in its lower 16 bits and the HostFSCustomControl() function selector in its upper 16 bits.

Compatibility

This notification is not broadcast in Palm OS Cobalt.

See Also

Chapter 4, "Notifications"

sysNotifyResetFinishedEvent ^TOP^

Purpose

Broadcast immediately after the system has finished a reset.

Declared In

NotifyMgr.h

Prototype

#define sysNotifyResetFinishedEvent 'rstf'


Parameters

None.

Comments

Because the notification registry is cleared upon a reset, only internal system components use this notification. Applications that need to be informed of a system reset can respond to the sysAppLaunchCmdSystemReset launch code.

See Also

sysNotifyEarlyWakeupEvent, sysNotifyLateWakeupEvent, sysNotifySyncFinishEvent, Chapter 4, "Notifications"

sysNotifyRetryEnqueueKey ^TOP^

Purpose

Broadcast at the top of the event loop if the Attention Manager has attempted to post a virtual character to the key queue and failed because the queue is full. The notification signals that the Attention Manager is going to retry enqueuing the virtual character until it is successful.

Declared In

NotifyMgr.h

Prototype

#define sysNotifyRetryEnqueueKey 'retk'


Parameters

notifyDetailsP points to a wchar_t containing the virtual character to be enqueued.

Comments

Most applications do not need to register for this notification. It is used only by the Attention Manager to schedule retries of enqueuing the virtual character. When enqueueing a virtual character fails, the Attention Manager retries at the top of the event loop. It uses this notification to schedule retries so that they occur even if the user switches applications.

See Also

Chapter 4, "Notifications"

sysNotifySecuritySettingEvent ^TOP^

Purpose

Broadcast after the security level is successfully changed with a call to SecSvcsSetDeviceSetting().

Declared In

NotifyMgr.h

Prototype

#define sysNotifySecuritySettingEvent 'ssch'


Parameters

None.

Comments

This notification is not broadcast if the level isn't changed, either because the user doesn't have permission to change the level or the level value supplied to SecSvcsSetDeviceSetting() is invalid.

See Also

sysNotifyDeleteProtectedEvent, sysNotifyDeviceUnlocked, sysNotifyForgotPasswordEvent, Chapter 4, "Notifications"

sysNotifySleepNotifyEvent ^TOP^

Purpose

Broadcast during SysHandleEvent() immediately before the system is put to sleep. After the broadcast is complete, the system is put to sleep.

Declared In

NotifyMgr.h

Prototype

#define sysNotifySleepNotifyEvent 'slp!'


Parameters

None.

Comments

Register for this notification if you have a small amount of cleanup that needs to be performed before the system goes to sleep. It is recommended that you not perform any sort of prolonged activity, such as displaying an alert panel that requests confirmation, in response to a sleep notification. If you do, the alert might be displayed long enough to trigger another auto-off event, which could be detrimental to other handlers of this notification.

If your code is in the middle of a lengthy computation and needs to defer sleep, it should register for the sysNotifySleepRequestEvent notification instead.


IMPORTANT: This notification is not guaranteed to be broadcast. For example, if the system goes to sleep because the user removes the batteries, sleep notifications are not sent. Thus, these notifications are unsuitable for applications where external hardware must be shut off to conserve power before the system goes to sleep.

See Also

sysNotifyEarlyWakeupEvent, sysNotifyLateWakeupEvent, Chapter 4, "Notifications"

sysNotifySleepRequestEvent ^TOP^

Purpose

Broadcast during SysHandleEvent() processing when the system has decided to go to sleep.

Declared In

NotifyMgr.h

Prototype

#define sysNotifySleepRequestEvent 'slpq'


Parameters

notifyDetailsP points to a SleepEventParamType structure.

Comments

Register for this notification if you need to delay the system from going to sleep while your code performs a lengthy operation, such as disconnecting from the network. The system checks the deferSleep value when each notification handler returns. If it is nonzero, it cancels the sleep event.

After you defer sleep, your code is free to finish what it was doing. When it is finished, you must allow the system to continue with the sleep event. To do so, create a keyDownEvent with the resumeSleepChr and the command key bit set (to signal that the character is virtual) and add it to the event queue. When the system receives this event, it will again broadcast the sysNotifySleepRequestEvent to all clients. If deferSleep is 0 after all clients return, then the system knows it is safe to go to sleep, and it broadcasts the sysNotifySleepNotifyEvent to all of its clients.

Note that you may receive this notification several times before the system goes to sleep because notification handlers can delay the system sleep and resume it later.


IMPORTANT: This notification is not guaranteed to be broadcast. For example, if the system goes to sleep because the user removes the batteries, sleep notifications are not sent. Thus, these notifications are unsuitable for applications where external hardware must be shut off to conserve power before the system goes to sleep.

See Also

sysNotifyEarlyWakeupEvent, sysNotifyLateWakeupEvent, sysNotifySleepNotifyEvent, Chapter 4, "Notifications"

sysNotifySyncFinishEvent ^TOP^

Purpose

Broadcast immediately after a HotSync operation has completed. Register for this notification if you need to perform post-processing after HotSync operations.

Declared In

NotifyMgr.h

Prototype

#define sysNotifySyncFinishEvent 'sync'


Parameters

None.

See Also

sysNotifyDBAddedEvent, sysNotifyDBChangedEvent, sysNotifyDBDeletedEvent, sysNotifyResetFinishedEvent, sysNotifySyncStartEvent, Chapter 4, "Notifications"

sysNotifySyncStartEvent ^TOP^

Purpose

Broadcast immediately before a HotSync operation is begun. Register for this notification if you need to perform preprocessing before a HotSync operation.

Declared In

NotifyMgr.h

Prototype

#define sysNotifySyncStartEvent 'hots'


Parameters

None.

See Also

sysNotifySyncFinishEvent, Chapter 4, "Notifications"

sysNotifyTimeChangeEvent ^TOP^

Purpose

Broadcast just after the system time has been changed using TimSetSeconds(). Register for this notification if you need to know when the time has changed.

Declared In

NotifyMgr.h

Prototype

#define sysNotifyTimeChangeEvent 'time'


Parameters

None.

See Also

sysNotifyLocaleChangedEvent, Chapter 4, "Notifications"

sysNotifyVolumeMountedEvent ^TOP^

Purpose

Broadcast when a Virtual File System Manager volume is mounted.

Declared In

NotifyMgr.h

Prototype

#define sysNotifyVolumeMountedEvent 'volm'


Parameters

notifyDetailsP points to a VFSSlotMountParamType or VFSPOSEMountParamType structure.

Comments

When a volume is mounted, the VFS Manager activates the start.prc application on the newly mounted volume and switches applications to the Launcher or to the start.prc application on that volume if it has a user interface.

Register for this notification if you need to know when a volume is mounted or if you want to prevent the default behavior of the VFS Manager.

To prevent the VFS Manager from activating the start.prc application, set the vfsHandledStartPrc bit in the handled field. To prevent the VFS Manager from switching applications, set the vfsHandledUIAppSwitch bit.

See Also

sysNotifyCardInsertedEvent, sysNotifyVolumeUnmountedEvent, Chapter 4, "Notifications"

sysNotifyVolumeUnmountedEvent ^TOP^

Purpose

Broadcast when a Virtual File System Manager volume is unmounted. Register for this notification if you need to know when a volume is unmounted.

Declared In

NotifyMgr.h

Prototype

#define sysNotifyVolumeUnmountedEvent 'volu'


Parameters

notifyDetailsP contains the volume reference number.

See Also

sysNotifyCardRemovedEvent, sysNotifyVolumeMountedEvent, Chapter 4, "Notifications"

Deprecated Notifications ^TOP^

Purpose

These notifications, although declared in NotifyMgr.h, are not used in Palm OS Cobalt.

Declared In

NotifyMgr.h

Constants

sysNotifyGotUsersAttention

Notification Manager Functions and Macros ^TOP^

SysNotifyBroadcast Function ^TOP^

Purpose

Synchronously send a notification to all applications registered for it.

Declared In

NotifyMgr.h

Prototype

status_t SysNotifyBroadcast (
   SysNotifyParamType *notify
)

Parameters

notify
Identifies the notification to be broadcast. See SysNotifyParamType.

Returns

Returns errNone if the operation completed successfully, or one of the following otherwise:

sysNotifyErrBroadcastBusy
The broadcast stack limit has already been reached.
sysErrParamErr
The background thread is broadcasting the notification and the notify parameter is NULL.
sysNotifyErrNoStackSpace
There is not enough space on the stack for the notification.

Comments

When you call this function, the notification you specify is broadcast to all applications, shared libraries, and other code resources that have registered to receive that notification. The broadcast is performed synchronously, meaning that the system broadcasts the notification immediately and waits for each notification client to perform its notification handler and return before the SysNotifyBroadcast call returns. This notification occurs in priority order.

The system allows nested notifications. That is, the recipient of a notification might broadcast a new notification, whose recipient might broadcast another new notification and so on. The constant sysNotifyDefaultQueueSize specifies how many levels of nested notification are allowed. If you reach this limit, the error sysNotifyErrBroadcastBusy is returned and your notification is not broadcast. To avoid reaching the limit, use SysNotifyBroadcastDeferred() instead of SysNotifyBroadcast() in your notification handlers. This ensures that the notification will not be broadcast until the top of the event loop.


WARNING! Do not call SysNotifyBroadcast() from outside of the main UI thread. Use SysNotifyBroadcastDeferred() instead.

WARNING! This function is not secure. it dispatches the notifications all in the local process by loading the PRCs being executed. Secure applications should always use SysNotifyBroadcastDeferred().

See Also

SysNotifyRegister()

SysNotifyBroadcastDeferred Function ^TOP^

Purpose

Enqueue a notification for later broadcast.

Declared In

NotifyMgr.h

Prototype

status_t SysNotifyBroadcastDeferred (
   SysNotifyParamType *notify,
   uint32_t paramSize
)

Parameters

notify
The notification to enqueue. See SysNotifyParamType.
paramSize
Size of the data pointed to by the field
notify->notifyDetailsP.

Returns

Returns errNone if the operation completed successfully, or one of the following otherwise:

memErrNotEnoughSpace
There is not enough memory to allocate a new notification entry in the queue.
sysErrParamErr
paramSize is a negative number.
sysNotifyErrQueueFull
The queue has reached its maximum number of entries.

Comments

This function is similar to SysNotifyBroadcast() except that the broadcast does not take place until the top of the event loop (specifically, the next time EvtGetEvent() is called). The system copies the notify structure to a new memory chunk, which is disposed of upon completion of the broadcast. (The paramSize value is used when copying the notifyDetailsP portion of the notify structure.)

See Also

SysNotifyRegister()

SysNotifyRegister Function ^TOP^

Purpose

Register to receive a notification.

Declared In

NotifyMgr.h

Prototype

status_t SysNotifyRegister (
   DatabaseID database,
   uint32_t notifyType,
   SysNotifyProcPtr callback,
   int32_t priority,
   void *userData,
   uint32_t userDataSize
)

Parameters

database
ID of the database containing the application or code resource that is to receive the notification.
notifyType
The notification that the application wants to receive. See Chapter 4, "Notifications."
callback
Set to NULL to receive the notification as an application launch code. Note that you can only request a call with a callback from the main UI thread; use SysNotifyRegisterBackground() to register to receive a notification in the background thread.
priority
The priority with which the application should receive the event. Most applications and other code resources should always use sysNotifyNormalPriority. In rare circumstances, you may need to ensure that your code is notified toward the beginning or toward the end of the notification sequence. If so, be sure to leave some space so that your code won't collide with the system's handling of notifications or with another application's handling of notifications. In general, PalmSource recommends using a value whose least significant bits are 0 (such as 32, 64, 96, and so on). The smaller the priority, the earlier your code is notified.
userData
Caller-defined data to pass to the notification handler.
userDataSize
Size, in bytes, of the data block pointed to by userData.

Returns

Returns errNone if the operation completed successfully, or one of the following otherwise:

sysErrParamErr
The specified database ID is NULL.
sysNotifyErrDuplicateEntry
This application is already registered to receive this notification.
sysNotifyErrNoServer
The notification server could not be contacted.

Comments

Call this function when your code should receive a notification that a specific event has occurred or is about to occur. See Chapter 4, "Notifications," for a list of the possible notifications. Once you register for a notification, you remain registered to receive it until a system reset occurs or until you explicitly unregister using SysNotifyUnregister().

Pass NULL for the callbackP parameter so that the system will notify your application by sending it the sysAppLaunchCmdNotify launch code. This launch code's parameter block points to a SysNotifyParamType structure containing details about the notification.

The notification handler may perform any processing necessary. As with most launch codes, it's not possible to access global variables. If the handler needs access to any particular value to respond to the notification, pass a pointer to that value in the userDataP parameter. The system passes this pointer back to your code in the launch code's parameter block.

The notification handler may unregister for this notification or register for other notifications. It may also broadcast another notifications; however, it's recommended that you use SysNotifyBroadcastDeferred() to do this so as not to overflow the broadcast stack.

You may display a user interface in your notification handler; however, you should be careful when you do so. Many of the notifications are broadcast during SysHandleEvent(), which means your application event loop might not have progressed to the point where it is possible for you to display a user interface, or you might overflow the stack by displaying a user interface at this stage. See Chapter 4, "Notifications," to learn which notifications are broadcast during SysHandleEvent().

See Also

SysNotifyBroadcast(), SysNotifyBroadcastDeferred(), SysNotifyRegisterBackground(), SysNotifyUnregister()

SysNotifyRegisterBackground Function ^TOP^

Purpose

Register to receive a notification in the background thread.

Declared In

NotifyMgr.h

Prototype

status_t SysNotifyRegisterBackground (
   DatabaseID database,
   uint32_t notifyType,
   int32_t priority,
   void *userData,
   uint32_t userDataSize
)

Parameters

database
ID of the database containing the application or code resource that is to receive the notification.
notifyType
The notification that the application wants to receive. See Chapter 4, "Notifications."
priority
The priority with which the application should receive the event. Most applications and other code resources should always use sysNotifyNormalPriority. In rare circumstances, you may need to ensure that your code is notified toward the beginning or toward the end of the notification sequence. If so, be sure to leave some space so that your code won't collide with the system's handling of notifications or with another application's handling of notifications. In general, PalmSource recommends using a value whose least significant bits are 0 (such as 32, 64, 96, and so on). The smaller the priority, the earlier your code is notified.
userData
Caller-defined data to pass to the notification handler.
userDataSize
The size, in bytes, of the data block pointed to by userData.

Returns

Comments

This function allows you to register for a notification to be received in the background thread. When the notification occurs, the Notification Manager loads the PRC indicated by database into the background process and performs the sublaunch there.


NOTE: Background notifications happen completely independently of the main applications, so these notifications are often received out-of-order with the notifications delivered to the main UI thread.

See Also

SysNotifyBroadcast(), SysNotifyBroadcastDeferred(), SysNotifyRegister(), SysNotifyUnregister()

SysNotifyRegisterV40 Function ^TOP^

Purpose

Register to receive a notification.


NOTE: This function is provided for compatibility purposes only; applications should use SysNotifyRegister() instead.

Declared In

NotifyMgr.h

Prototype

status_t SysNotifyRegisterV40 (
   uint16_t cardNo,
   LocalID dbID,
   uint32_t notifyType,
   SysNotifyProcPtr callback,
   int8_t priority,
   void *userData
)

Parameters

cardNo
Number of the storage card on which the application or code resource resides.
dbID
Local ID of the application or code resource.
notifyType
The notification that the application wants to receive. See Chapter 4, "Notifications."
callback
Set to NULL to receive the notification as an application launch code, or pass a pointer to a function that should be called when the notification is broadcast. See SysNotifyProcPtr().
priority
The priority with which the application should receive the event. Most applications and other code resources should always use sysNotifyNormalPriority. In rare circumstances, you may need to ensure that your code is notified toward the beginning or toward the end of the notification sequence. If so, be sure to leave some space so that your code won't collide with the system's handling of notifications or with another application's handling of notifications. In general, PalmSource recommends using a value whose least significant bits are 0 (such as 32, 64, 96, and so on). The smaller the priority, the earlier your code is notified.
userData
Caller-defined data to pass to the notification handler.

Returns

Returns errNone if the operation completed successfully, or one of the following otherwise:

memErrCardNotPresent
The cardNo parameter is non-zero.
sysErrParamErr
The specified database ID is NULL.
sysNotifyErrDuplicateEntry
This application is already registered to receive this notification.
sysNotifyErrNoServer
The notification server could not be contacted.

Comments

Call this function when your code should receive a notification that a specific event has occurred or is about to occur. See Chapter 4, "Notifications," for a list of the possible notifications. Once you register for a notification, you remain registered to receive it until a system reset occurs or until you explicitly unregister using SysNotifyUnregister().

If your code is running in the main UI thread, you can register a function to be called when the notification is broadcast. In your call to SysNotifyRegisterV40() pass a pointer to a callback function in callbackP. This callback should follow the prototype shown in SysNotifyProcPtr(). Note that you should always supply a card number and database ID to SysNotifyRegisterV40(), even if you specify a callback function.


IMPORTANT: Because the callbackP pointer is used to directly call the function, the pointer must remain valid from the time SysNotifyRegister() is called to the time the notification is broadcast. If the function is in a shared library, you must keep the library open. If the function is in a separately-loaded code resource, the resource must remain loaded in the applicatoin process while registered for the notification. When you close a library or unlock a resource, you must first unregister for any notifications. If you don't, the system will crash when the notification is broadcast.

If the code registering for notification isn't in the main UI thread, or if you don't have a function that can be called directly, pass NULL as the callbackP parameter. In this case, the system notifies your application by sending it the sysAppLaunchCmdNotify launch code. This launch code's parameter block points to a SysNotifyParamType structure containing details about the notification.

Whether the notification handler is responding to sysAppLaunchCmdNotify or uses the callback function, the notification handler may perform any processing necessary. As with most launch codes, it's not possible to access global variables. If the handler needs access to any particular value to respond to the notification, pass a pointer to that value in the userDataP parameter. The system passes this pointer back to your application or callback function in the launch code's parameter block.

The notification handler may unregister for this notification or register for other notifications. It may also broadcast another notifications; however, it's recommended that you use SysNotifyBroadcastDeferred() to do this so as not to overflow the broadcast stack.

You may display a user interface in your notification handler; however, you should be careful when you do so. Many of the notifications are broadcast during SysHandleEvent(), which means your application event loop might not have progressed to the point where it is possible for you to display a user interface, or you might overflow the stack by displaying a user interface at this stage. See Chapter 4, "Notifications," to learn which notifications are broadcast during SysHandleEvent().

Compatibility

This function is provided for compatibility purposes only; applications should use SysNotifyRegister()—which omits the obsolete cardNo parameter, identifies the database containing the application or code resource using a DatabaseID, and adds the userDataSize parameter—instead.

See Also

SysNotifyBroadcast(), SysNotifyBroadcastDeferred(), SysNotifyRegister(), SysNotifyUnregisterV40()

SysNotifyUnregister Function ^TOP^

Purpose

Cancel notification of the given event.

Declared In

NotifyMgr.h

Prototype

status_t SysNotifyUnregister (
   DatabaseID database,
   uint32_t notifyType,
   int32_t priority
)

Parameters

database
Database ID of the database containing the application or code resource that is receiving the notification.
notifyType
The notification for which to unregister. See Chapter 4, "Notifications.".
priority
The priority value you passed when calling SysNotifyRegister().

Returns

Returns errNone if the operation completed successfully, or one of the following otherwise:

sysNotifyErrEntryNotFound
The application wasn't registered to receive this notification.
sysNotifyErrNoServer
The notification server could not be contacted.

Comments

Use this function to remove your code from the list of those that receive notifications about a particular event. This function is particularly necessary if you use a notification callback; when the resource containing the callback is unloaded, it must unregister for all of its notifications, or the system will crash when the notification is broadcast.

See Also

SysNotifyRegister()

SysNotifyUnregisterV40 Function ^TOP^

Purpose

Cancel notification of the given event.


NOTE: This function is provided for compatibility purposes only; applications should use SysNotifyUnregister() instead.

Declared In

NotifyMgr.h

Prototype

status_t SysNotifyUnregisterV40 (
   uint16_t cardNo,
   LocalID dbID,
   uint32_t notifyType,
   int8_t priority
)

Parameters

cardNo
Number of the storage card on which the application or code resource resides.
dbID
Local ID of the application or code resource.
notifyType
The notification for which to unregister. See Chapter 4, "Notifications."
priority
The priority value you passed when calling SysNotifyRegisterV40().

Returns

Returns errNone if the operation completed successfully, or one of the following otherwise:

memErrCardNotPresent
The cardNo parameter is non-zero.
sysNotifyErrEntryNotFound
The application wasn't registered to receive this notification.
sysNotifyErrNoServer
The notification server could not be contacted.

Comments

Use this function to remove your code from the list of those that receive notifications about a particular event. This function is particularly necessary if you are writing a shared library or a separately loaded code resource that receives notifications. When the resource is unloaded, it must unregister for all of its notifications, or the system will crash when the notification is broadcast.

Compatibility

This function is provided for compatibility purposes only; applications should use SysNotifyUnregister()—which omits the obsolete cardNo parameter and identifies the database containing the application or code resource using a DatabaseID—instead.

See Also

SysNotifyRegisterV40()

Application-Defined Functions ^TOP^

SysNotifyProcPtr Function ^TOP^

Purpose

Notification-handling callback function prototype.

Declared In

NotifyMgr.h

Prototype

status_t (
   *SysNotifyProcPtr
) (
   SysNotifyParamType *notifyParamsP
)

Parameters

notifyParamsP
Pointer to a structure that contains the notification event that occurred and any other information about it. See SysNotifyParamType.

Returns

Your notification handler should always return errNone.

Comments


NOTE: Applications should register to receive each notification as a launch code; the use of a callback function in Palm OS Cobalt is discouraged.

You pass this function as a parameter to SysNotifyRegister() or SysNotifyRegisterV40() when registering code that does not have a PilotMain() for a notification. See the description of SysNotifyRegister() for advice on writing a notification handler.


IMPORTANT: Because the callbackP pointer is used to directly call the function, the pointer must remain valid from the time SysNotifyRegister() is called to the time the notification is broadcast. If the function is in a shared library, you must keep the library open. If the function is in a separately loaded code resource, the resource must remain locked while registered for the notification. When you close a library or unlock a resource, you must first unregister for any notifications. If you don't, the system will crash when the notification is broadcast. Because of this, applications should generally register to receive a notification using a callback function; instead, register to receive it as a launch code.