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

43    Notification Manager

Palm OS® Programmer's API Reference

Palm OS® 68K SDK

     

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 ^TOP^

Miscellaneous Constants ^TOP^

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 ^TOP^

SysNotifyBroadcast Function ^TOP^

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 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 Function ^TOP^

Purpose

Enqueue a notification for later broadcast.

Declared In

NotifyMgr.h

Prototype

Err SysNotifyBroadcastDeferred(
   SysNotifyParamType*notify,
   Int16paramSize
)

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 ^TOP^

Purpose

Allows interrupt handlers to enqueue a notification for later broadcast.

Declared In

NotifyMgr.h

Prototype

Err SysNotifyBroadcastFromInterrupt(
   UInt32notifyType,
   UInt32broadcaster,
   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:

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. If Palm OS Cobalt Feature Set is present this function is unimplemented.


WARNING! Using this function on Palm OS Garnet may cause a system crash.

SysNotifyRegister Function ^TOP^

Purpose

Register to receive a notification.

Declared In

NotifyMgr.h

Prototype

Err SysNotifyRegister (
   UInt16cardNo,
   LocalIDdbID,
   UInt32notifyType,
   SysNotifyProcPtrcallbackP,
   Int8priority,
   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, 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 ^TOP^

Purpose

Cancel notification of the given event.

Declared In

NotifyMgr.h

Prototype

Err SysNotifyUnregister(
   UInt16cardNo,
   LocalIDdbID,
   UInt32notifyType,
   Int8priority
)

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 ^TOP^

SysNotifyProcPtr Function ^TOP^

Purpose

Handle a notification.

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

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.