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
The connection profile used by the Connection Panel has changed. |
|
An expansion card has been inserted into the expansion slot. |
|
Database info has been set on a database, such as with |
|
A database has been opened for write or in some other way has been made modifiable. |
|
An event has been removed from the event queue with |
|
The user has tapped the Lost Password button in the Security application. |
|
An application has requested that a particular service be performed. |
|
The system is about to post a |
|
The system has been connected to or disconnected from the network. |
|
The user has made a pen stroke on the silkscreen portion of the digitizer. |
|
The Attention Manager has failed to post a virtual character to the key queue. |
|
The system needs to request that the user pick a particular date in the calendar. |
|
Notification Data Structures
SysNotifyParamType Typedef
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 tofalse
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
cncNotifyProfileEvent
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
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
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
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
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
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
Compatibility
Implemented only if Notification Feature Set is present.
sysNotifyAppLaunchingEvent
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
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
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
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
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
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
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
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
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
Compatibility
Implemented only if 5.0 New Feature Set is present.
sysNotifyDeleteProtectedEvent
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
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
Compatibility
Implemented only if 4.0 New Feature Set is present.
sysNotifyDisplayChangeEvent
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
Compatibility
Implemented only if Notification Feature Set is present.
sysNotifyDisplayResizedEvent
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
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
Compatibility
Implemented only if Notification Feature Set is present.
sysNotifyEventDequeuedEvent
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
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
Compatibility
Implemented only if Notification Feature Set is present.
sysNotifyGotUsersAttention
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
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
Compatibility
Implemented only if 5.3SC New Feature Set is present.
sysNotifyHelperEvent
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
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
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 isfalse
, 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, orfalse
if only a portion is to be redrawn. Iftrue
, then theupdateBounds
field can be ignored. -
padding
- Padding; unused.
Compatibility
Implemented only if 5.3SC New Feature Set is present.
sysNotifyInputAreaPendownEvent
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.
sysNotifyInsPtEnableEvent
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
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
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
Compatibility
Implemented only if Notification Feature Set is present.
sysNotifyLocaleChangedEvent
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
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
Compatibility
Implemented only if Notification Feature Set is present.
sysNotifyNetLibIFMediaEvent
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
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
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
Compatibility
Implemented only if Notification Feature Set is present.
sysNotifyRetryEnqueueKey
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
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, orfalse
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.
sysNotifySleepNotifyEvent
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
Compatibility
Implemented only if Notification Feature Set is present.
sysNotifySleepRequestEvent
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
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
Compatibility
Implemented only if Notification Feature Set is present.
sysNotifySyncStartEvent
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
Compatibility
Implemented only if Notification Feature Set is present.
sysNotifyTimeChangeEvent
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
Compatibility
Implemented only if Notification Feature Set is present.
sysNotifyVirtualCharHandlingEvent
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
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
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.