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
SleepEventParamType Struct
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
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
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
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
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
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
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
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
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
SysNotifyLocaleChangedType Struct
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
SysNotifyParamType Struct
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 tofalse
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
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
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
Reasons for Device Sleep
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
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, whileoldAttributes
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, whileoldCreator
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, whileoldName
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, whileoldType
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
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
cncNotifyConnectionStateEvent
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
sysExternalConnectorAttachEvent
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
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
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
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
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
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
sysNotifyAppServicesEvent
Purpose
Declared In
NotifyMgr.h
Prototype
#define sysNotifyAppServicesEvent 'apsv'
Parameters
Comments
See Also
sysNotifyCardInsertedEvent
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
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
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
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
sysNotifyDB
xxxEvent 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
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
sysNotifyDB
xxxEvent 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
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
sysNotifyDB
xxxEvent 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
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
sysNotifyDB
xxxEvent 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
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
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
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
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
sysNotifyEarlyWakeupEvent
Purpose
Broadcast during SysHandleEvent()
immediately after the system has finished sleeping.
Declared In
NotifyMgr.h
Prototype
#define sysNotifyEarlyWakeupEvent 'worm'
Parameters
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
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
See Also
sysNotifyDeviceUnlocked
, sysNotifySecuritySettingEvent
, Chapter 4, "Notifications"
sysNotifyHostFSInitDone
Purpose
Broadcast by the Host File System library when the library has been initialized.
Declared In
NotifyMgr.h
Prototype
#define sysNotifyHostFSInitDone 'hfid'
Parameters
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
sysNotifyLateWakeupEvent
Purpose
Broadcast during SysHandleEvent()
immediately after the device has finished waking up.
Declared In
NotifyMgr.h
Prototype
#define sysNotifyLateWakeupEvent 'lazy'
Parameters
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
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
Purpose
Broadcast during MenuHandleEvent()
when it is about to display the menu shortcut command bar.
Declared In
NotifyMgr.h
Prototype
#define sysNotifyMenuCmdBarOpenEvent 'cbar'
Parameters
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
sysNotifyPhoneEvent
Purpose
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
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
sysNotifyResetFinishedEvent
Purpose
Broadcast immediately after the system has finished a reset.
Declared In
NotifyMgr.h
Prototype
#define sysNotifyResetFinishedEvent 'rstf'
Parameters
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
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
sysNotifySecuritySettingEvent
Purpose
Broadcast after the security level is successfully changed with a call to SecSvcsSetDeviceSetting()
.
Declared In
NotifyMgr.h
Prototype
#define sysNotifySecuritySettingEvent 'ssch'
Parameters
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
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
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
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
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
See Also
sysNotifyDBAddedEvent
, sysNotifyDBChangedEvent
, sysNotifyDBDeletedEvent
, sysNotifyResetFinishedEvent
, sysNotifySyncStartEvent
, Chapter 4, "Notifications"
sysNotifySyncStartEvent
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
See Also
sysNotifySyncFinishEvent
, Chapter 4, "Notifications"
sysNotifyTimeChangeEvent
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
See Also
sysNotifyLocaleChangedEvent
, Chapter 4, "Notifications"
sysNotifyVolumeMountedEvent
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
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
Purpose
These notifications, although declared in NotifyMgr.h
, are not used in Palm OS Cobalt.
Declared In
NotifyMgr.h
Constants
Notification Manager Functions and Macros
SysNotifyBroadcast Function
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 isNULL
. -
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
SysNotifyBroadcastDeferred Function
Purpose
Enqueue a notification for later broadcast.
Declared In
NotifyMgr.h
Prototype
status_t SysNotifyBroadcastDeferred ( SysNotifyParamType*notify
, uint32_tparamSize
)
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 Function
Purpose
Register to receive a notification.
Declared In
NotifyMgr.h
Prototype
status_t SysNotifyRegister ( DatabaseIDdatabase
, uint32_tnotifyType
, SysNotifyProcPtrcallback
, int32_tpriority
, void*userData
, uint32_tuserDataSize
)
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; useSysNotifyRegisterBackground()
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
Purpose
Register to receive a notification in the background thread.
Declared In
NotifyMgr.h
Prototype
status_t SysNotifyRegisterBackground ( DatabaseIDdatabase
, uint32_tnotifyType
, int32_tpriority
, void *userData
, uint32_tuserDataSize
)
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
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_tcardNo
, LocalIDdbID
, uint32_tnotifyType
, SysNotifyProcPtrcallback
, int8_tpriority
, 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. SeeSysNotifyProcPtr()
. -
→ 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
Purpose
Cancel notification of the given event.
Declared In
NotifyMgr.h
Prototype
status_t SysNotifyUnregister ( DatabaseIDdatabase
, uint32_tnotifyType
, int32_tpriority
)
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
SysNotifyUnregisterV40 Function
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_tcardNo
, LocalIDdbID
, uint32_tnotifyType
, int8_tpriority
)
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
Application-Defined Functions
SysNotifyProcPtr Function
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.