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

14    Alarm Manager

System Management

Exploring Palm OS®

This chapter provides reference material for the Alarm Manager. It is organized into the following sections:

Alarm Manager Structures and Types
Alarm Manager Constants
Alarm Manager Launch Codes
Alarm Manager Functions and Macros

The header file AlarmMgr.h declares the API that this chapter describes.

You often use the Alarm Manager in conjunction with the Attention Manager. For usage information on both, see Chapter 1, "Attentions and Alarms."

Alarm Manager Structures and Types ^TOP^

AlmProcCmdEnum Typedef ^TOP^

Purpose

Declared In

AlarmMgr.h

Prototype

typedef Enum16 AlmProcCmdEnum

SysAlarmTriggeredParamType Struct ^TOP^

Purpose

Contains parameters that accompany a sysAppLaunchCmdAlarmTriggered launch code.

Declared In

AlarmMgr.h

Prototype

typedef struct SysAlarmTriggeredParamType {
   uint32_t ref;
   uint32_t alarmSeconds;
   Boolean purgeAlarm;
   uint8_t padding;
   uint16_t padding1;
} SysAlarmTriggeredParamType

Fields

ref
The caller-defined value specified when the alarm was set with AlmSetAlarm().
alarmSeconds
The date/time specified when the alarm was set with AlmSetAlarm(). The value is given as the number of seconds since 1/1/1904.
purgeAlarm
In your launch code handler, set this field to true if the alarm should be removed from the alarm table. Use this as an optimization to prevent the application from receiving sysAppLaunchCmdDisplayAlarm if you don't wish to perform any other processing for this alarm. If you do want to receive the launch code, set this field to false.
padding
Padding bytes - not used.
padding1
Padding bytes - not used.

SysDisplayAlarmParamType Struct ^TOP^

Purpose

Contains parameters that accompany a sysAppLaunchCmdDisplayAlarm launch code.

Declared In

AlarmMgr.h

Prototype

typedef struct SysDisplayAlarmParamType {
   uint32_t ref;
   uint32_t alarmSeconds;
   Boolean soundAlarm;
   uint8_t padding;
   uint16_t padding1;
} SysDisplayAlarmParamType

Fields

ref
The caller-defined value specified when the alarm was set with AlmSetAlarm().
alarmSeconds
The date/time specified when the alarm was set with AlmSetAlarm(). The value is given as the number of seconds since 1/1/1904.
soundAlarm
true if the alarm should be sounded, false otherwise. This value is currently not used.
padding
Padding bytes - not used.
padding1
Padding bytes - not used.

Alarm Manager Constants ^TOP^

Alarm Manager Error Codes ^TOP^

Purpose

Error codes returned by the various Alarm Manager functions.

Declared In

AlarmMgr.h

Constants

#define almErrFull (almErrorClass | 2)
The alarm table is full.
#define almErrMemory (almErrorClass | 1)
There is insufficient memory to perform the requested operation.

AlmProcCmdEnumTag Enum ^TOP^

Purpose

Declared In

AlarmMgr.h

Constants

almProcCmdTriggered = 0
almProcCmdReschedule
almProcCmdCustom = 0x8000

Alarm Manager Launch Codes ^TOP^

sysAppLaunchCmdAlarmTriggered ^TOP^

Purpose

Indicates that the application should perform a quick action such as scheduling the next alarm or sounding the alarm.

Declared In

CmnLaunchCodes.h

Prototype

#define sysAppLaunchCmdAlarmTriggered 6


Parameters

The launch code's parameter block pointer references a SysAlarmTriggeredParamType structure.

Comments

This launch code is sent as close to the actual alarm time as possible.

Upon receiving this launch code, an application may perform any quick, non-blocking action. The action should be quick: multiple alarms may be pending at the same time for multiple applications, and one alarm display shouldn't block the system and prevent other applications from receiving their alarms in a timely fashion. More time-consuming actions should be performed upon receipt of a sysAppLaunchCmdDisplayAlarm launch code.

sysAppLaunchCmdDisplayAlarm ^TOP^

Purpose

Indicates that the application can perform full, possibly blocking, handling of the alarm.

Declared In

CmnLaunchCodes.h

Prototype

#define sysAppLaunchCmdDisplayAlarm 7


Parameters

The launch code's parameter block pointer references a SysDisplayAlarmParamType structure.

Comments

This is the application's opportunity to handle an alarm in a lengthy or blocking fashion. Alert dialogs are usually displayed when this launch code is received. This work should be done here, not when sysAppLaunchCmdAlarmTriggered is received.

Alarm Manager Functions and Macros ^TOP^

AlmEnableNotification Function ^TOP^

Purpose

Declared In

AlarmMgr.h

Prototype

void AlmEnableNotification (
   Boolean enable
)

Parameters

enable

Returns

AlmGetAlarm Function ^TOP^

Purpose

Return the date and time for the application's alarm, if one is set.

Declared In

AlarmMgr.h

Prototype

uint32_t AlmGetAlarm (
   DatabaseID dbID,
   uint32_t *refP
)

Parameters

dbID
Local ID of the application.
refP
The alarm's reference value is returned here. This value is passed to the application when the alarm is triggered.

Returns

The date and time the alarm will trigger, given in seconds since 1/1/1904; if no alarm is active for the application, 0 is returned for the alarm seconds and the reference value is undefined.

See Also

AlmSetAlarm()

AlmSetAlarm Function ^TOP^

Purpose

Set or cancel an alarm for the given application.

Declared In

AlarmMgr.h

Prototype

status_t AlmSetAlarm (
   DatabaseID dbID,
   uint32_t ref,
   uint32_t alarmSeconds,
   Boolean quiet
)

Parameters

dbID
Local ID of the application.
ref
Caller-defined value. This value is passed with the launch code that notifies the application that the alarm has been triggered.
alarmSeconds
Alarm date/time in seconds since 1/1/1904, or 0 to cancel the current alarm (if any).
quiet
Reserved for future use. This value is not currently used.

Returns

Returns errNone if the operation was completed successfully, or one of the following otherwise:

almErrMemory
Insufficient memory.
almErrFull
Alarm table is full.

Comments

This function sets an alarm for the specified application. An application can have only one alarm set at a time. If an alarm for this application has already been set, it is replaced with the new alarm.

The alarmSeconds parameter specifies the time at which the alarm will be triggered. As soon as possible after this time, the alarm manager sends the sysAppLaunchCmdAlarmTriggered launch code to the specified application. If there is another alarm that should be set for this application, you can set it in response to this launch code. Following the sysAppLaunchCmdAlarmTriggered launch code, the alarm manager sends a sysAppLaunchCmdDisplayAlarm launch code. This is where your application should do things such as display a modal dialog indicating that the event has occurred.

If your application needs access to any particular value to respond to the alarm, pass a pointer to that value in the ref parameter. The system will pass this pointer back to the application in the launch codes' parameter blocks.

See Also

AlmGetAlarm()