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
AlmProcCmdEnum Typedef
Purpose
Declared In
AlarmMgr.h
Prototype
typedef Enum16 AlmProcCmdEnum
SysAlarmTriggeredParamType Struct
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 receivingsysAppLaunchCmdDisplayAlarm
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 tofalse
. -
padding
- Padding bytes - not used.
-
padding1
- Padding bytes - not used.
SysDisplayAlarmParamType Struct
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
Alarm Manager Error Codes
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
Purpose
Declared In
AlarmMgr.h
Constants
Alarm Manager Launch Codes
sysAppLaunchCmdAlarmTriggered
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
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
AlmEnableNotification Function
Purpose
Declared In
AlarmMgr.h
Prototype
void AlmEnableNotification (
Boolean enable
)
Parameters
Returns
AlmGetAlarm Function
Purpose
Return the date and time for the application's alarm, if one is set.
Declared In
AlarmMgr.h
Prototype
uint32_t AlmGetAlarm ( DatabaseIDdbID
, 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 Function
Purpose
Set or cancel an alarm for the given application.
Declared In
AlarmMgr.h
Prototype
status_t AlmSetAlarm ( DatabaseIDdbID
, uint32_tref
, uint32_talarmSeconds
, Booleanquiet
)
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:
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.