This chapter describes the Notification Manager API as declared in the header file NotifyMgr.h
. It discusses the following topics:
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.
Notification Functions
SysNotifyBroadcast Function
Purpose
Synchronously send a notification to all applications registered for it.
Declared In
NotifyMgr.h
Prototype
Err SysNotifyBroadcast( SysNotifyParamType *notify )
Parameters
-
↔
notify
- Identifies the notification to be broadcast. See
SysNotifyParamType
.
Returns
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 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 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 Function
Purpose
Enqueue a notification for later broadcast.
Declared In
NotifyMgr.h
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
.
Returns
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.
SysNotifyBroadcastFromInterrupt Function
Purpose
Allows interrupt handlers to enqueue a notification for later broadcast.
Declared In
NotifyMgr.h
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.
Returns
Returns one of the following error codes:
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. If Palm OS Cobalt Feature Set is present this function is unimplemented.
SysNotifyRegister Function
Purpose
Register to receive a notification.
Declared In
NotifyMgr.h
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 aPilotMain()
function (for example, if it is a shared library), 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, Palm™ 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.
Returns
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 Function
Purpose
Cancel notification of the given event.
Declared In
NotifyMgr.h
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()
.
Returns
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 Function
Purpose
Declared In
NotifyMgr.h
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
.
Returns
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.