36 Notification Manager

This chapter provides information about the notification manager by discussing these topics:

• Notification Data Structures
  
  
• Notification Constants
  
  
• Notification Functions
  
  
• Application-Defined Functions
  

The header file NotifyMgr.h declares the API that this chapter describes. For more information on the notification manager, see the section "Notifications" in the "Palm System Features" chapter of the Palm OS Programmer's Companion.

Notification Data Structures

SleepEventParamType

The SleepEventParamType struct is used in notifications of type sysNotifySleepRequestEvent to indicate why the system is going to sleep and whether sleep should be deferred.

typedef struct {

    UInt16 reason;
    UInt16 deferSleep;
} SleepEventParamType;

Field Descriptions

SysNotifyDisplayChangeDetailsType

The SysNotifyDisplayChangeDetailsType struct is used in notifications of type sysNotifyDisplayChangeEvent to indicate 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.

typedef struct {

    UInt32 oldDepth;
    UInt32 newDepth;
} SysNotifyDisplayChangeDetailsType;

Field Descriptions

SysNotifyParamType

The SysNotifyParamType struct defines a notification event. This struct is sent along with the sysAppLaunchCmdNotify launch code or is passed as a parameter to the notification callback function.

typedef struct SysNotifyParamType {

    UInt32 notifyType;
    UInt32 broadcaster;
    void * notifyDetailsP;
    void * userDataP;
    Boolean handled;
    UInt8 reserved2;
} SysNotifyParamType;

Field Descriptions

Notification Constants

Notification Manager Event Constants

The constants in the table below identify events for which the system posts notifications. In general, notifications regarding the creation of information are broadcast after the information has been created. Notifications regarding the deletion of information are broadcast before the information is deleted.

Several notifications are broadcast at various stages when the system goes to sleep and when the system wakes up. These notifications are 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.

Constant	Description
sysNotifyAntennaRaisedEvent	Sent during SysHandleEvent when the antenna is raised on a Palm VII™ series device. Notification handlers may set the handled parameter to true to indicate that the antenna key down event has been handled.
sysNotifyDisplayChangeEvent	Sent just after the color table has been set to use a specific palette or just after WinScreenMode has changed the bit depth. For this notification, the notifyDetailsP parameter is a pointer to a SysNotifyDisplayChangeDetailsType struct.
sysNotifyEarlyWakeupEvent	Sent during SysHandleEvent immediately after the system has finished sleeping. The screen may still be turned off, and the system may quickly go back to sleep after handling a procedure alarm or charger event.
sysNotifyForgotPasswordEvent	Sent if 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.
sysNotifyLateWakeupEvent	Sent during SysHandleEvent immediately after the device has finished waking up. This is sent at the late stage of wakeup, after the screen has been turned on.
sysNotifyMenuCmdBarOpenEvent	Sent during MenuHandleEvent when it is about to display the menu shortcut command bar. This notification allows system extensions (such as "hacks" installed with the HackMaster program) to add their own buttons to the menu command bar. The handler should do so by calling MenuCmdBarAddButton. It also allows suppression of the command toolbar by setting handled 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, immediately before the command toolbar is displayed.
sysNotifyResetFinishedEvent	Sent immediately after the system has finished a reset.
sysNotifySleepNotifyEvent	Sent during SysHandleEvent immediately before the system is put to sleep. After the broadcast is complete, the system is put to sleep.
sysNotifySleepRequestEvent	Sent during SysHandleEvent processing when the system has decided to go to sleep. For this notification, the notifyDetailsP parameter is a pointer to a SleepEventParamType struct. If the deferSleep field is greater than 0, the system does not go to sleep. If you defer sleep, you must post a keyDownEvent with a resumeSleepChr to the event queue so that the system eventually goes to sleep. You must also set the command key bit in the keyDownEvent to signal that resumeSleepChr is a virtual character. 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.
sysNotifySyncFinishEvent	Sent immediately after a HotSync® operation is complete.
sysNotifySyncStartEvent	Sent immediately before a HotSync operation is begun.
sysNotifyTimeChangeEvent	Sent just after the system time has been changed using TimSetSeconds.

Miscellaneous Constants

Notification Functions

SysNotifyBroadcast

Purpose

Synchronously send a notification to all applications registered for the given event type.

Prototype

Err SysNotifyBroadcast (SysNotifyParamType *notify)

Parameters

<-> notify

Information about the notification to broadcast.

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 interested parties. The broadcast is performed synchronously, meaning that the system broadcasts the notification immediately and waits for each interested party 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 parameter is used when copying the notifyDetailsP portion of the notify structure.)

Compatibility

Implemented only if Notification 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 event that the application wants to receive notifications about. See Notification Manager Event Constants.

-> callbackP

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, specify a value between -15 and +15. 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 Notification Manager Event Constants for a list of the events about which you can receive 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 in 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 may overflow the stack by displaying a user interface at this stage. See Notification Manager Event Constants 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 event to unregister for. See Notification Manager Event Constants.

-> 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 these notifications.

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.

---