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

3    Notifications

Palm OS® Programmer's API Reference

Palm OS® 68K SDK

     

This chapter provides detailed information about the notifications declared in the header file NotifyMgr.h. Notifications are broadcast to inform applications, shared libraries, system extensions, or other code resources of certain system-level or application-level events.

Notifications are similar to application launch codes, but they differ from launch codes in the following ways:

  • The system broadcasts notifications only to interested parties. To register to receive a notification, use SysNotifyRegister().
  • Notifications can be sent to non-applications.

See the "Notification Manager" chapter in this book and the section "Notifications" of the Palm OS Programmer's Companion, vol. I for more information on receiving and handling notifications.

Table 3.1  Notification Constants

Constant

Description

cncNotifyProfileEvent

The connection profile used by the Connection Panel has changed.

kTelTelephonyNotification

A telephony event has occurred.

Socket Notification

A network socket change has occurred.

sysExternalConnectorAttachEvent

A device has been attached to an external connector.

sysExternalConnectorDetachEvent

A device has been detached from an external connector.

sysNotifyAntennaRaisedEvent

The antenna has been raised on a Palm VII series device.

sysNotifyAppLaunchingEvent

An application is about to be launched.

sysNotifyAppQuittingEvent

An application has just quit.

sysNotifyCardInsertedEvent

An expansion card has been inserted into the expansion slot.

sysNotifyCardRemovedEvent

An expansion card has been removed from the expansion slot.

sysNotifyDBCreatedEvent

A database has been created.

sysNotifyDBChangedEvent

Database info has been set on a database, such as with DmSetDatabaseInfo().

sysNotifyDBDeletedEvent

A database has been deleted.

sysNotifyDBDirtyEvent

A database has been opened for write or in some other way has been made modifiable.

sysNotifyDeleteProtectedEvent

The Launcher has attempted to delete a protected database.

sysNotifyDeviceUnlocked

The user has unlocked the device.

sysNotifyDisplayChangeEvent

The color table or bit depth has changed.

sysNotifyDisplayResizedEvent

The dynamic input area has opened or closed.

sysNotifyEarlyWakeupEvent

The system is starting to wake up.

sysNotifyEventDequeuedEvent

An event has been removed from the event queue with EvtGetEvent.

sysNotifyForgotPasswordEvent

The user has tapped the Lost Password button in the Security application.

sysNotifyGotUsersAttention

The Attention Manager has informed the user of an event.

sysNotifyGsiDrawIndicator

The system is about to draw the shift indicator.

sysNotifyHelperEvent

An application has requested that a particular service be performed.

sysNotifyIdleTimeEvent

The system is idle and is about to doze.

sysNotifyInputAreaDrawingEvent

The system is about to draw the dynamic input area.

sysNotifyInputAreaPendownEvent

The system is about to post a penDownEvent for the dynamic input area.

sysNotifyInsPtEnableEvent

The insertion point is being enabled or disabled.

sysNotifyIrDASniffEvent

Not used.

sysNotifyKeyboardDialogEvent

The keyboard dialog is about to be displayed.

sysNotifyLateWakeupEvent

The system has finished waking up.

sysNotifyLocaleChangedEvent

The system locale has changed.

sysNotifyMenuCmdBarOpenEvent

The system is about to display the menu command toolbar.

sysNotifyNetLibIFMediaEvent

The system has been connected to or disconnected from the network.

sysNotifyPhoneEvent

Reserved for future use.

sysNotifyPOSEMountEvent

System use only.

sysNotifyProcessPenStrokeEvent

The user has made a pen stroke on the silkscreen portion of the digitizer.

sysNotifyResetFinishedEvent

The system has finished a reset.

sysNotifyRetryEnqueueKey

The Attention Manager has failed to post a virtual character to the key queue.

sysNotifySelectDay

The system needs to request that the user pick a particular date in the calendar.

sysNotifySleepNotifyEvent

The system is about to go to sleep.

sysNotifySleepRequestEvent

The system has decided to go to sleep.

sysNotifySyncFinishEvent

A HotSync® operation has just completed.

sysNotifySyncStartEvent

A HotSync operation is about to begin.

sysNotifyTimeChangeEvent

The system time has just changed.

sysNotifyVirtualCharHandlingEvent

A virtual character is being handled.

sysNotifyVolumeMountedEvent

A file system has been mounted.

sysNotifyVolumeUnmountedEvent

A file system has been unmounted.

Notification Data Structures ^TOP^

SysNotifyParamType Typedef ^TOP^

Purpose

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. The Notification Reference section gives details on the important data associated with each type of notification.

Prototype

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

Fields

notifyType
The type of event that occurred. See Notification Reference.
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 to true if the notification has been handled; set to false 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.

Notification Reference ^TOP^

cncNotifyProfileEvent ^TOP^

The cncNotifyProfileEvent is broadcast whenever a connection profile has been created, modified, or deleted and after a request has been made to update the connection profile list.

The notifyDetailsP field informs the notification handler of the type of change that was made. Register for the cncNotifyProfileEvent if your application maintains its own list of connection profiles that it should keep current or if it should help the Connection Panel maintain its list.

cncNotifyProfileEvent Specific Data

notifyDetailsP points to a CncProfileNotifyDetailsType structure.

Prototype

typedef struct _CncProfileNotifyDetailsTag {
UInt16 version;
UInt32 profileID;
UInt16 deviceKind;
UInt16 request;
} CncProfileNotifyDetailsType;

Fields

version
The current version of this structure. Use the kCncProfileNotifyCurrentVersion constant to find out what the current version is.
profileID
The ID of the modified connection profile.
deviceKind
Device kind of the profile. This can be one of the following constants:
kCncDeviceKindSerial
Serial connection profile.
kCncDeviceKindModem
Modem profile.
kCncDeviceKindPhone
Phone profile.
kCncDeviceKindLocalNetwork
LAN profile.
request
The action that was performed. This can be one of the following constants:
kCncNotifyCreateRequest
The profile has been created.
kCncNotifyDeleteRequest
The profile is about to be deleted.
kCncNotifyModifyRequest
The profile has been modified.
kCncNotifyUpdateListRequest
A HotSync operation or system reset has just occurred. The notification handler should update the Connection Panel's list.
If a profile has been created or modified, the request field also contains a flag indicating how the current profile is to be set:
kCncBecomeCurrentModifier
The new profile should be made the current profile.
kCncNotifyAlertUserModifier
The user is prompted to set the current profile.

Compatibility

Implemented only if 4.0 New Feature Set is present.

kTelTelephonyNotification ^TOP^

The kTelTelephonyNotification is broadcast when the Palm OS receives an event from the phone, such as an incoming SMS message or an incoming phone call.

kTelTelephonyNotification Specific Data

notifyDetailsP points to a TelNotificationType structure.

Prototype

typedef struct _TelNotificationType {
UInt32 notificationData;
UInt32 notificationData2;
UInt32 timeStamp;
UInt16 notificationId;
UInt8 priority;
} TelNotificationType

Fields

notificationData
Data specific to the notificationId.
notificationData2
Data specific to a notificationId.
timeStamp
Time the event occurred, expressed as the number of seconds elapsed since 12:00 A.M. on January 1, 1904.
notificationId
One of the constants described in "Notification Identifiers" describing the type of event that occurred.
priority
One of the constants described in "Notification Priorities."

Socket Notification ^TOP^

A socket notification is broadcast when the state of a network socket changes—for example, a socket is closed or a socket receives TCP data. This notification differs from the others described in this chapter in a significant way: there is no single constant value that identifies socket notification. Instead, each application must have a unique value for purposes of receiving socket notifications. Your application must pass this unique constant as the notifyType parameter to SysNotifyRegister().

Socket notifications are used by Net Library to deliver socket notices. There is more to them than just the normal process of registering for a notification. For more details, see "Socket Notices" of Palm OS Programmer's Companion, vol. II, Communications.

The notifyDetailsP field informs the notification handler what socket underwent a change and the nature of that change.

Socket Notification Specific Data

notifyDetailsP points to a SysNotifyNetSocketType structure.

Prototype

typedef struct SysNotifyNetSocketType {
NetSocketRef socketRef;
UInt32 condition;
} SysNotifyNetSocketType;

Fields

socketRef
Integer representing the socket whose state change triggered the notification.
condition
A bitfield describing the socket condition(s) that triggered the notification. The Socket Notice Trigger Conditions are constants defined for the bits of this field.

Compatibility

Implemented only if 5.4 New Feature Set is present.

sysExternalConnectorAttachEvent ^TOP^

The sysExternalConnectorAttachEvent is broadcast when a USB cradle, RS-232 cradle or peripheral, a power cable, or a modem is attached to the universal connector. This notification is broadcast only on devices that have the universal connector.

sysExternalConnectorAttachEvent Specific Data

The notifyDetailsP field points to a UInt16 that identifies which type of device was attached.

Compatibility

Implemented only if 4.0 New Feature Set is present.

sysExternalConnectorDetachEvent ^TOP^

The sysExternalConnectorDetachEvent is broadcast when a USB cradle, a RS-232 cradle or peripheral, a power cable, or a modem is detached from the universal connector. This notification is only broadcast on devices that have the universal connector.

sysExternalConnectorDetachEvent Specific Data

The notifyDetailsP field points to a UInt16 that identifies which type of device was detached.

Compatibility

Implemented only if 4.0 New Feature Set is present.

sysNotifyAntennaRaisedEvent ^TOP^

The sysNotifyAntennaRaisedEvent is broadcast by SysHandleEvent() when the antenna is raised on a Palm VII series device.

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.

sysNotifyAntennaRaisedEvent Specific Data

None.

Compatibility

Implemented only if Notification Feature Set is present.

sysNotifyAppLaunchingEvent ^TOP^

The sysNotifyAppLaunchingEvent is broadcast before an application is launched with sysAppLaunchCmdNormalLaunch.

sysNotifyAppLaunchingEvent Specific Data

notifyDetailsP points to a SysNotifyAppLaunchOrQuitType structure.

Prototype

typedef struct SysNotifyAppLaunchOrQuitTag {
UInt32 version;
UInt32 dbID;
UInt16 cardNo; 
} SysNotifyAppLaunchOrQuitType;

Fields

version
The current version of this structure. The current version is 0.
dbID
The local ID of the application.
cardNo
The number of the card on which the application resides.

Compatibility

This notification is declared in the Palm OS 4.0 SDK Update 1. Versions 4.1 and earlier of Palm OS don't broadcast this notification. Palm OS Garnet releases do broadcast it. Later versions may or may not broadcast this notification.

sysNotifyAppQuittingEvent ^TOP^

The sysNotifyAppQuittingEvent is broadcast right after an application that was launched with sysAppLaunchCmdNormalLaunch quits.

sysNotifyAppLaunchingEvent Specific Data

notifyDetailsP points to a SysNotifyAppLaunchOrQuitType structure. See the description of sysNotifyAppLaunchingEvent for a description of this structure.

Compatibility

This notification is declared in the Palm OS 4.0 SDK Update 1. Versions 4.1 and earlier of Palm OS don't broadcast this notification. Palm OS Garnet releases do broadcast it. Later versions may or may not broadcast this notification.

sysNotifyCardInsertedEvent ^TOP^

The sysNotifyCardInsertedEvent is 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.

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; 

sysNotifyCardInsertedEvent Specific Data

notifyDetailsP points to a UInt16 containing the slot reference number.

Compatibility

Implemented only if 4.0 New Feature Set is present.

sysNotifyCardRemovedEvent ^TOP^

The sysNotifyCardRemovedEvent is 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.

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; 

sysNotifyCardRemovedEvent Specific Data

notifyDetailsP points to a UInt16 containing the slot reference number.

Compatibility

Implemented only if 4.0 New Feature Set is present.

sysNotifyDBCreatedEvent ^TOP^

The sysNotifyDBCreatedEvent is broadcast sometime after a database is created with DmCreateDatabase().

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...Event 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.

sysNotifyDBCreatedEvent Specific Data

notifyDetailsP points to a SysNotifyDBCreatedType structure.

Prototype

typedef struct SysNotifyDBCreatedTag {
Char dbName[dmDBNameLength];
UInt32 creator;
UInt32 type;
LocalID newDBID;
UInt16 cardNo;
Boolean resDB;
UInt8 padding;
} SysNotifyDBCreatedType;

Fields

dbName
Database name.
creator
Database creator ID.
type
Database type.
newDBID
Local ID of the newly-created database.
cardno
Card number upon which the database resides.
resDB
true if the database is a resource database, false otherwise.
padding
Structure padding byte.

Compatibility

Implemented only if 5.0 New Feature Set is present.

sysNotifyDBChangedEvent ^TOP^

The sysNotifyDBChangedEvent is broadcast sometime after database info is set with DmSetDatabaseInfo().

Register for this notification if you keep an internal list of databases that needs to be updated when database info changes.


IMPORTANT: The sysNotifyDB...Event 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.

sysNotifyDBChangeEvent Specific Data

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.

Prototype

typedef struct SysNotifyDBChangedTag {
Char dbName[dmDBNameLength];
LocalID dbID;
UInt32 creator;
UInt32 type;
UInt32 crDate;
UInt32 modDate;
UInt32 bckUpDate;
UInt32 modNum;
LocalID appInfoID;
LocalID sortInfoID;
UInt16 attributes;
UInt16 cardNo;
UInt16 version;
UInt16 fields;
Char oldName[dmDBNameLength];
UInt32 oldCreator;
UInt32 oldType;
UInt16 oldAttributes;
UInt16 padding;
} SysNotifyDBChangedType;

Fields

dbName
New name of database.
dbID
Database ID.
creator
New database creator ID.
type
New database type.
crDate
New database creation date.
modDate
New database modification date.
bckUpDate
New database backup date.
modNum
New database modification number.
appInfoID
New database application info block.
sortInfoID
New database sort info block.
attributes
New database attributes.
cardNo
Card number upon which the dabatase resides.
version
New database version.
fields
Flags that indicate what about the database changed, and thus which of the above fields are set. The constants that define the fields bits are:
DBChangedFieldSetName = 0x1
DBChangedFieldSetCreator = 0x2
DBChangedFieldSetType = 0x4
DBChangedFieldSetCrDate = 0x8
DBChangedFieldSetModDate = 0x10
DBChangedFieldSetBckUpDate = 0x20
DBChangedFieldSetModNum = 0x40
DBChangedFieldSetAppInfo = 0x80
DBChangedFieldSetSortInfo = 0x100
DBChangedFieldSetAttributes = 0x200
DBChangedFieldSetVersion = 0x400
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.
padding
Structure padding bytes.

Compatibility

Implemented only if 5.0 New Feature Set is present.

sysNotifyDBDeletedEvent ^TOP^

The sysNotifyDBDeletedEvent is broadcast sometime after a database is removed from the device.

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...Event 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.

sysNotifyDBDeletedEvent Specific Data

notifyDetailsP points to a SysNotifyDBDeletedType structure.

Prototype

typedef struct SysNotifyDBDeletedTag {
LocalID oldDBID;
UInt16 cardNo;
UInt16 attributes;
Char dbName[dmDBNameLength];
UInt32 creator;
UInt32 type;
} SysNotifyDBDeletedType;

Fields

oldDBID
The local ID of the deleted database. This ID is no longer valid.

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.
cardNo
The number of the card on which the database resided.
attributes
The deleted database's attributes.
dbName
The name of the deleted database.
creator
The creator ID of the deleted database.
type
The type of the deleted database.

Compatibility

Implemented only if 4.0 New Feature Set is present.

sysNotifyDBDirtyEvent ^TOP^

The sysNotifyDBDirtyEvent is 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.

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...Event 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.

sysNotifyDBDirtyEvent Specific Data

notifyDetailsP points to a SysNotifyDBDirtyType structure.

Prototype

typedef struct SysNotifyDBDirtyTag {
Char dbName[dmDBNameLength];
UInt32 creator;
UInt32 type;
} SysNotifyDBDirtyType;

Fields

dbName
Database name.
creator
Database creator ID.
type
Database type.

Compatibility

Implemented only if 5.0 New Feature Set is present.

sysNotifyDeleteProtectedEvent ^TOP^

The sysNotifyDeleteProtectedEvent is 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.

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.

sysNotifyDeleteProtectedEvent Specific Data

notifyDetailsP points to a SysNotifyDBInfoType structure.

Prototype

typedef struct SysNotifyDBInfoTag {
LocalID dbID;
UInt16 cardNo;
UInt16 attributes;
Char dbName[dmDBNameLength];
UInt32 creator;
UInt32 type;
} SysNotifyDBInfoType;

Fields

dbID
The local ID of 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.

Compatibility

Implemented only if 4.0 New Feature Set is present.

sysNotifyDeviceUnlocked ^TOP^

The sysNotifyDeviceUnlocked notification is broadcast by the Security application when the user unlocks the device. The notification is broadcast immediately after the device has finished unlocking.

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.

sysNotifyDeviceUnlocked Specific Data

None.

Compatibility

Implemented only if 4.0 New Feature Set is present.

sysNotifyDisplayChangeEvent ^TOP^

The sysNotifyDisplayChangeEvent is broadcast whenever the display mode changes. That is, 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.

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.

sysNotifyDisplayChangeEvent Specific Data

notifyDetailsP points to a SysNotifyDisplayChangeDetailsType structure.

Prototype

typedef struct {
UInt32 oldDepth;
UInt32 newDepth;
} SysNotifyDisplayChangeDetailsType;

Fields

oldDepth
The old bit depth.
newDepth
The new bit depth.

Compatibility

Implemented only if Notification Feature Set is present.

sysNotifyDisplayResizedEvent ^TOP^

The sysNotifyDisplayResizedEvent notification is broadcast by PINSetInputAreaState after the dynamic input area or control bar has been opened or closed. Normally, the user opens and closes the dynamic input area and control bar, but applications may also do so, though this is not encouraged.

Applications may respond to the notification by redrawing the active form in the available space.

sysNotifyDisplayResizedEvent Specific Data

notifyDetailsP points to a SysNotifyDisplayResizedDetailsType structure.

Prototype

typedef struct SysNotifyDisplayResizedDetailsTag{
RectangleType newBounds;
} SysNotifyDisplayResizedDetailsType;

Fields

newBounds
The new bounds of the application area after the input area or control bar has been opened or closed. The application should draw the current form within these bounds.

Compatibility

Implemented only if the Pen Input Manager Feature Set is present.

sysNotifyEarlyWakeupEvent ^TOP^

The sysNotifyEarlyWakeupEvent is broadcast during SysHandleEvent() immediately after the system has finished sleeping. 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.

sysNotifyEarlyWakeupEvent Specific Data

None.

Compatibility

Implemented only if Notification Feature Set is present.

sysNotifyEventDequeuedEvent ^TOP^

The sysNotifyEventDequeuedEvent is broadcast for each event removed from the event queue with EvtGetEvent.


WARNING! Be very careful about registering for this notification; it can result in significantly degraded system performance.

sysNotifyEventDequeuedEvent Specific Data

notifyDetailsP points to the dequeued event's EventType structure.


IMPORTANT: For speed, the event structure that notifyDetailsP points to uses system-native endianness. This means that you might need to byte-swap the structure's contents, depending on the endianness of the underlying operating system.

Compatibility

This notification is declared in the Palm OS 4.0 SDK Update 1. Versions 4.1 and earlier of Palm OS don't broadcast this notification. Palm OS Garnet release do broadcast it. Later versions may or may not broadcast this notification.

sysNotifyForgotPasswordEvent ^TOP^

The sysNotifyForgotPasswordEvent is 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.

sysNotifyForgotPasswordEvent Specific Data

None.

Compatibility

Implemented only if Notification Feature Set is present.

sysNotifyGotUsersAttention ^TOP^

The sysNotifyGotUsersAttention notification is broadcast when the Attention Manager has finished displaying or sounding its attention indicators (blinking, playing sounds, vibrating, and so on).

System extensions or shared libraries should register for this notification if they want to perform some extra effect or if they simply want to be informed of when the user's attention was received.

sysNotifyGotUsersAttention Specific Data

notifyDetailsP points to an AttnNotifyDetailsType structure.

Prototype

typedef struct {
AttnFlagsType flags;
} AttnNotifyDetailsType;

Fields

flags
The attention indicators that were used to get the user's attention. See AttnFlagsType.

Compatibility

Implemented only if 4.0 New Feature Set is present.

sysNotifyGsiDrawIndicator ^TOP^

The sysNotifyGsiDrawIndicator notification is broadcast just before the system is about to draw the shift indicator. If you handle this notification, then the system assumes that the shift indicator has been drawn, so it skips its own drawing code.

If you need to find out where to draw the shift indicator, you can loop through the form objects until you find one of type frmGraffitiStateObj, and then get its position. Draw the shift indicator with a width of kMaxGsiWidth (9) and kMaxGsiHeight (10), as defined in GraffitiShift.h. Note that you must clear and draw every pixel in this 9 by 10 rectangle if you handle the notification.

sysNotifyGsiDrawIndicator Specific Data

None.

Compatibility

Implemented only if 5.3SC New Feature Set is present.


NOTE: Future Palm OS versions might not support this notification.

sysNotifyHelperEvent ^TOP^

The sysNotifyHelperEvent is broadcast by applications to request a service from another application. For example, the Address Book application broadcasts this notification to request that the Dial application dial a phone number. For the sysNotifyHelperEvent, the notification client (that is, the application or shared library that registers for the notification) is called a helper.

The application that broadcasts this notification specifies one of the action codes listed in Table 39.1 in Chapter 39, "Helper API." These action codes request all helper applications to enumerate (list the services they perform), validate (ensure that the service will succeed), and execute (perform the action). The helper responds to the notification by returning the required data in the appropriate portion of the notifyDetailsP structure and by setting the handled field to true or false to indicate the success or failure of the action.

For more information on this notification, see the section "Helper Notifications" in the Palm OS Programmer's Companion, vol. I.

sysNotifyHelperEvent Specific Data

notifyDetailsP points to a HelperNotifyEventType structure.

Compatibility

Implemented only if 4.0 New Feature Set is present.

sysNotifyIdleTimeEvent ^TOP^

The sysNotifyIdleTimeEvent is broadcast when the system is idle and is about to doze.

Compatibility

This notification is declared in the Palm OS 4.0 SDK Update 1. Versions 4.1 and earlier of Palm OS don't broadcast this notification. Palm OS Garnet releases do broadcast it. Later versions may or may not broadcast this notification.

sysNotifyInputAreaDrawingEvent ^TOP^

The sysNotifyInputAreaDrawingEvent notification is broadcast just before the system is about to redraw the dynamic input area (on a device supporting a dynamic input area). If you handle this notification, then the system assumes that the requested portion of the input area has been redrawn and skips its own drawing code.

sysNotifyInputAreaDrawingEvent Specific Data

notifyDetailsP points to a SysNotifyInputAreaDrawingDetailsType structure, which is in little-endian format.

Prototype

typedef struct SysNotifyInputAreaDrawingDetailsTag 
{
RectangleType updateBounds;
const BitmapType *bitmapP;
Boolean selected;
Boolean fullRedraw;
UInt16 padding;
} SysNotifyInputAreaDrawingDetailsType;

Fields

updateBounds
If the fullRedraw field is false, then this is the area to redraw, in native coordinates, relative to the input area window.
bitmapP
A pointer to the bitmap that is about to be drawn by the system.
selected
true if the area being redrawn is a button that the user is in the process of tapping and should therefore be drawn in its selected state.
fullRedraw
true if the entire input area should be redrawn, or false if only a portion is to be redrawn. If true, then the updateBounds field can be ignored.
padding
Padding; unused.

Compatibility

Implemented only if 5.3SC New Feature Set is present.


NOTE: Future Palm OS versions might not support this notification.

sysNotifyInputAreaPendownEvent ^TOP^

The sysNotifyInputAreaPendownEvent notification is broadcast just before the system is about to handle a penDownEvent for the dynamic input area (on a device supporting a dynamic input area). If you handle this notification, then the system assumes that the event has been handled and skips its own event handling code.

sysNotifyInputAreaPendownEvent Specific Data

notifyDetailsP points to a SysNotifyInputAreaPendownDetailType structure, which is in little-endian format.

Prototype

typedef struct SysNotifyInputAreaPendownDetailTag 
{
PointType where;
} SysNotifyInputAreaPendownDetailType;

Fields

where
The point where the pen first went down, in native coordinates, relative to the input area window.

Compatibility

Implemented only if 5.3SC New Feature Set is present.


NOTE: Future Palm OS versions might not support this notification.

sysNotifyInsPtEnableEvent ^TOP^

The sysNotifyInsPtEnableEvent is broadcast at the start of InsPtEnable.

sysNotifyInsPtEnableEvent Specific Data

notifyDetailsP points to a Boolean: the enableIt parameter passed to InsPtEnable.

Compatibility

This notification is declared in the Palm OS 4.0 SDK Update 1. Versions 4.1 and earlier of Palm OS don't broadcast this notification. Palm OS Garnet releases do broadcast it. Later versions may or may not broadcast this notification.

sysNotifyKeyboardDialogEvent ^TOP^

The sysNotifyKeyboardDialogEvent is broadcast whenever the system keyboard is displayed. It is intended to enable the replacement of SysKeyboardDialog function's user interface.

sysNotifyKeyboardDialogEvent Specific Data

notifyDetailsP points to the KeyboardType enum that indicates the mode in which the keyboard should be opened: alphabetic, numeric, or international.

Compatibility

This notification is declared in the Palm OS 4.0 SDK Update 1. Versions 4.1 and earlier of Palm OS don't broadcast this notification. Palm OS Garnet releases do broadcast it. Later versions may or may not broadcast this notification.

sysNotifyLateWakeupEvent ^TOP^

The sysNotifyLateWakeupEvent is broadcast during SysHandleEvent() immediately after the device has finished waking up. 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. For example:


case sysNotifyLateWakeupEvent:  
if ((Boolean)  
PrefGetPreference(prefDeviceLocked)) { 
SysNotifyRegister(myCardNo, myDbID,  
sysNotifyDeviceUnlocked, NULL,  
sysNotifyNormalPriority, NULL); 
} else { 
HandleDeviceWakeup(); 
} 
case sysNotifyDeviceUnlocked:  
HandleDeviceWakeup(); 

Note that the sysNotifyDeviceUnlocked notification is only broadcast on Palm OS 4.0 and higher.

sysNotifyLateWakeupEvent Specific Data

None.

Compatibility

Implemented only if Notification Feature Set is present.

sysNotifyLocaleChangedEvent ^TOP^

The sysNotifyLocaleChangedEvent is 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.

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.

sysNotifyLocaleChangedEvent Specific Data

notifyDetailsP points to a SysNotifyLocaleChangedType structure.

Prototype

typedef struct SysNotifyLocaleChangedTag {
LmLocaleType oldLocale;
LmLocaleType newLocale;
} SysNotifyLocaleChangedType;

Fields

oldLocale
The old locale. See LmLocaleType.
newLocale
The new locale.

Compatibility

Implemented only if 4.0 New Feature Set is present.

sysNotifyMenuCmdBarOpenEvent ^TOP^

The sysNotifyMenuCmdBarOpenEvent is broadcast during MenuHandleEvent() when it is about to display the menu shortcut command bar.

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.

sysNotifyMenuCmdBarOpenEvent

None.

Compatibility

Implemented only if Notification Feature Set is present.

sysNotifyNetLibIFMediaEvent ^TOP^

The sysNotifyNetLibIFMediaEvent is broadcast at the top of the event loop whenever the network interface makes the network connection active or inactive. The Network Panel uses this notification to decide whether the Connect button should be active.

Register for this notification if you need to know when the network connection is currently active.

sysNotifyNetLibIFMediaEvent Specific Data

notifyDetailsP contains a SysNotifyNetLibIFMediaType structure.

Prototype

typedef struct SysNotifyNetLibIFMediaTag {
NetLibIFMediaEventNotificationTypeEnum eType;
UInt32 ifCreator;
UInt16 ifInstance;
} SysNotifyNetLibIFMediaType;

Fields

eType
One of the following values:
netIFMediaUp
The network connection is active. This is usually sent after the network interface has displayed UI indicating that a connection attempt is in progress.
netIFMediaDown
The network connection is inactive. This is usually sent after the network interface has brought the connection down because an inactivity timeout value was reached.
ifCreator
Creator ID of the network interface
ifInstance
Instance number of the network interface.

Compatibility

Implemented only if 4.0 New Feature Set is present.

sysNotifyProcessPenStrokeEvent ^TOP^

The sysNotifyProcessPenStrokeEvent is broadcast to enable custom recognition of strokes made on the silkscreen portion of the digitizer.

sysNotifyProcessPenStrokeEvent Specific Data

notifyDetailsP points to a SysNotifyPenStrokeType structure.

Prototype

typedef struct SysNotifyPenStrokeTag {
UInt32 version;
PointType startPt;
PointType endPt;
} SysNotifyPenStrokeType;

Fields

version
The current version of this structure. The current version is 0.
startPt
Start point of stroke.
endPt
End point of stroke.

Compatibility

This notification is declared in the Palm OS 4.0 SDK Update 1. Versions 4.1 and earlier of Palm OS don't broadcast this notification. Palm OS Garnet releases do broadcast it. Later versions may or may not broadcast this notification.

sysNotifyResetFinishedEvent ^TOP^

The sysNotifyResetFinishedEvent is broadcast immediately after the system has finished a reset.

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.

sysNotifyResetFinishedEvent Specific Data

None.

Compatibility

Implemented only if Notification Feature Set is present.

sysNotifyRetryEnqueueKey ^TOP^

The sysNotifyRetryEnqueueKey notification is 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.

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.

sysNotifyRetryEnqueueKey Specific Data

notifyDetailsP points to a WChar containing the virtual character to be enqueued.

Compatibility

Implemented only if 4.0 New Feature Set is present.

sysNotifySelectDay ^TOP^

The sysNotifySelectDay notification is broadcast when the SelectDay() function (as defined in SelDay.h) is called. If you handle this notification, then the system assumes that an appropriate user interface has been presented to the user and (if dayChanged is true) uses daySelectorP for the requested date. This allows you to develop a locale-specific date selection user interface (beyond that already supported by the SelectDay() function).

notifyDetailsP points to a SysNotifySelectDayDetailsType structure, which is in little-endian format.

Prototype

typedef struct SysNotifySelectDayDetailsTag {
DaySelectorType *daySelectorP;
const Char *titleP;
Boolean dayChanged;
UInt8 padding[3];
} SysNotifySelectDayDetailsType;

Fields

daySelectorP
A pointer to a DaySelectorType structure that on input specifies the date to select when the user interface first appears, and on output specifies the date selected by the user.
titleP
A pointer to a text string that may be displayed as the title of the user interface to inform the user what the date they select will be used for.
dayChanged
true if the user selected a different date in the user interface, or false if they canceled the user interface or didn't change the initially selected date.
padding
Padding; unused.

Compatibility

Implemented only if 5.3SC New Feature Set is present.


NOTE: Future Palm OS versions might not support this notification.

sysNotifySleepNotifyEvent ^TOP^

The sysNotifySleepNotifyEvent is broadcast during SysHandleEvent() immediately before the system is put to sleep. After the broadcast is complete, the system is put to sleep.

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

sysNotifySleepNotifyEvent Specific Data

None.

Compatibility

Implemented only if Notification Feature Set is present.

sysNotifySleepRequestEvent ^TOP^

The sysNotifySleepRequestEvent is broadcast during SysHandleEvent() processing when the system has decided to go to sleep.

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.

sysNotifySleepRequestEvent Specific Data

notifyDetailsP points to a SleepEventParamType structure.

Prototype

typedef struct {
UInt16 reason;
UInt16 deferSleep;
} SleepEventParamType;

Fields

reason
The reason the system is going to sleep. The possible values are:
sysSleepAutoOff
The idle time limit has been reached.
sysSleepPowerButton
The user pressed the power off button.
sysSleepResumed
The sleep event was deferred by one of the notification handlers but has been resumed through the use of the resumeSleepChr.
sysSleepUnknown
Unknown reason.
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.

Compatibility

Implemented only if Notification Feature Set is present.

sysNotifySyncFinishEvent ^TOP^

The sysNotifySyncFinishEvent is broadcast immediately after a HotSync operation has completed. Register for this notification if you need to perform post-processing after HotSync operations.

sysNotifySyncFinishEvent Specific Data

None.

Compatibility

Implemented only if Notification Feature Set is present.

sysNotifySyncStartEvent ^TOP^

The sysNotifySyncStartEvent is broadcast immediately before a HotSync operation is begun. Register for this notification if you need to perform preprocessing before a HotSync operation.

sysNotifySyncStartEvent Specific Data

None.

Compatibility

Implemented only if Notification Feature Set is present.

sysNotifyTimeChangeEvent ^TOP^

The sysNotifyTimeChangeEvent notification is 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.

sysNotifyTimeChangeEvent Specific Data

None.

Compatibility

Implemented only if Notification Feature Set is present.

sysNotifyVirtualCharHandlingEvent ^TOP^

The sysNotifyVirtualCharHandlingEvent is broadcast to enable custom handling of virtual characters. Set the handled field in the SysNotifyParamType structure to true to prevent the virtual character from being passed on to the rest of the system.

sysNotifyVirtualCharHandlingEvent Specific Data

notifyDetailsP points to a SysNotifyVirtualCharHandlingType structure.

Prototype

typedef struct SysNotifyVirtualCharHandlingTag{
UInt32 version;
struct _KeyDownEventType keyDown;
} SysNotifyVirtualCharHandlingType;

Fields

version
The current version of this structure. The current version is 0.
keyDown
The virtual character. See the description of the keyDownEvent in "Event Reference" for a complete description of this structure and its contents.

Compatibility

This notification is declared in the Palm OS 4.0 SDK Update 1. Versions 4.1 and earlier of Palm OS don't broadcast this notification. Palm OS Garnet releases do broadcast it. Later versions may or may not broadcast this notification.

sysNotifyVolumeMountedEvent ^TOP^

The sysNotifyVolumeMountedEvent is broadcast when a Virtual File System Manager volume is mounted. 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.

sysNotifyVolumeMountedEvent Specific Data

notifyDetailsP points to a VFSSlotMountParamType or VFSPOSEMountParamType structure.

Compatibility

Implemented only if 4.0 New Feature Set is present.

sysNotifyVolumeUnmountedEvent ^TOP^

The sysNotifyVolumeUnmountedEvent is broadcast when a Virtual File System Manager volume is unmounted. Register for this notification if you need to know when a volume is unmounted.

sysNotifyVolumeUnmountedEvent Specific Data

notifyDetailsP contains the volume reference number.

Compatibility

Implemented only if 4.0 New Feature Set is present.