< Home < Developers < Development Support < Documentation

## 40 Notification Manager

Table of Contents | < Previous | Next > | Index

| Title - Palm OS® Programmer's API Reference Part II: System Management 40 Notification Manager Notification Constants Miscellaneous Constants Notification Functions SysNotifyBroadcast SysNotifyBroadcastDeferred SysNotifyBroadcastFromInterrupt SysNotifyRegister SysNotifyUnregister Application-Defined Functions SysNotifyProcPtr |  |  |  | This chapter describes the Notification Manager API as declared in the header file NotifyMgr.h. It discusses the following topics: Notification Constants Notification Functions Application-Defined Functions The chapter "Notifications" in this book lists the possible notifications and describes the data sent with each. Also see the section "Notifications" in the "Application Startup and Stop" chapter of the Palm OS Programmer's Companion, vol. I for a description of how to use notifications. ## Notification Constants ## Miscellaneous Constants This following miscellaneous constants are used in the Notification Manager. For other notification constants, see the "Notifications" chapter in this book. #####
Constant | Value | Description
--- | --- | ---
sysNotifyBroadcasterCode | 'psys' | The value passed as the creator ID of the broadcaster for notifications broadcast by the system.
sysNotifyDefaultQueueSize | 30 | The maximum number of nested broadcasts allowed.
sysNotifyNoDatabaseID | 0xFFFFFFFF | The database local ID used by the system when it registers for notifications.
sysNotifyNormalPriority | 0 | Typical priority value used when registering for notifications.
sysNotifyVersionNum | 1 | Current Notification Manager version. This number is stored in the system feature sysFtrNumNotifyMgrVersion.
## Notification Functions ## SysNotifyBroadcast #### Purpose Synchronously send a notification to all applications registered for it. #### Prototype Err SysNotifyBroadcast (SysNotifyParamType *notify) #### Parameters #####
<-> notify | Identifies the notification to be broadcast. See SysNotifyParamType.
#### Result Returns one of the following error codes: #####
errNone | No error.
#####
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 code that might be called from a background task (such as a trap patch) with the memory semaphore reserved. Use SysNotifyBroadcastDeferred instead. #### Compatibility Implemented only if Notification Feature Set is present. ## SysNotifyBroadcastDeferred #### Purpose Enqueue a notification for later broadcast. #### Prototype Err SysNotifyBroadcastDeferred (SysNotifyParamType *notify, Int16 paramSize) #### Parameters #####
<-> notify | The notification to enqueue. See SysNotifyParamType.
#####
-> paramSize | Size of the data pointed to by the field notify->notifyDetailsP.
#### Result Returns one of the following error codes: #####
errNone | No error.
#####
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.) #### Compatibility Implemented only if Notification Feature Set is present. ## New SysNotifyBroadcastFromInterrupt #### Purpose Allows interrupt handlers to enqueue a notification for later broadcast. #### Prototype Err SysNotifyBroadcastFromInterrupt (UInt32 notifyType, UInt32 broadcaster, void *notifyDetailsP) #### Parameters #####
-> notifyType | The type of event that occurred. See the chapter Notifications for a complete list of the notifications that Palm OS® broadcasts.
#####
-> broadcaster | The creator ID of the device or application that broadcast the notification.
#####
-> notifyDetailsP | Pointer to data specific to this notification. See the Notifications chapter for the specific instances where this parameter is used.
#### Result Returns one of the following error codes: #####
errNone | No error.
#####
sysNotifyErrQueueFull | The queue has reached its maximum number of entries.
#### Comments Like SysNotifyBroadcastDeferred, this function enqueues a notification to be broadcast at the top of the event loop (specifically, the next time EvtGetEvent is called). It differs from SysNotifyBroadcastDeferred in that it is interrupt-safe and intended to be called from interrupt handlers. This function is intended to be used by device drivers and other low-level software to generate a notification about a hardware change. For example, the Expansion Manager uses SysNotifyBroadcastFromInterrupt to broadcast sysNotifyCardInsertedEvent and sysNotifyCardRemovedEvent when a card is inserted into or removed from the expansion slot. SysNotifyBroadcastFromInterrupt is not intended to be used by general third party applications. Patching SysNotifyBroadcastFromInterrupt will cause the system to hang. #### Compatibility Implemented only if 4.0 New Feature Set is present. ## SysNotifyRegister #### Purpose Register to receive a notification. #### Prototype Err SysNotifyRegister (UInt16 cardNo, LocalID dbID, UInt32 notifyType, SysNotifyProcPtr callbackP, Int8 priority, void *userDataP) #### 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 the chapter Notifications.
#####
-> callbackP | Set to NULL to receive the notification as an application launch code. If your code does not have a PilotMain function (for example, if it is a shared library), 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, PalmTM 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.
#####
-> userDataP | Caller-defined data to pass to the notification handler.
#### Result Returns one of the following error codes: #####
errNone | No error.
#####
sysErrParamErr | The database ID is NULL.
#####
sysNotifyErrDuplicateEntry | This application is already registered to receive this notification.
#### Comments Call this function when your code should receive a notification that a specific event has occurred or is about to occur. See the Notifications chapter 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 you're writing an application, you should 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. If your code is not in an application, for example, it is a shared library or a separately loaded code resource, then receiving a launch code is not possible. In this case, 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 SysNotifyRegister, 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 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. 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 the "Notifications" chapter to learn which notifications are broadcast during SysHandleEvent. #### Compatibility Implemented only if Notification Feature Set is present. ## SysNotifyUnregister #### Purpose Cancel notification of the given event. #### Prototype Err SysNotifyUnregister(UInt16 cardNo, LocalID dbID, UInt32 notifyType, Int8 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 Notifications.
#####
-> priority | The priority value you passed as part of SysNotifyRegister.
#### Result Returns one of the following error codes: #####
errNone | No error.
#####
sysNotifyErrEntryNotFound | The application wasn't registered to receive this notification.
#### 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 Implemented only if Notification Feature Set is present. ## Application-Defined Functions ## SysNotifyProcPtr #### Purpose Handle a notification. #### Prototype Err (*SysNotifyProcPtr) (SysNotifyParamType *notifyParamsP) #### Parameters #####
-> notifyParamsP | Pointer to a structure that contains the notification event that occurred and any other information about it. See SysNotifyParamType.
#### Result Always return 0. #### Comments You pass this function as a parameter to SysNotifyRegister 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. |