This chapter provides reference material for the alarm manager:
The alarm manager API is declared in the header file AlarmMgr.h
.
For more information on the Alarm Manager, see the section "Alarms" in the Palm OS Programmer's Companion, vol. I.
Alarm Manager Functions
AlmGetAlarm Function
Purpose
Return the date and time for the application's alarm, if one is set.
Declared In
AlarmMgr.h
Prototype
UInt32 AlmGetAlarm ( UInt16 cardNo, LocalID dbID, UInt32 *refP )
Parameters
-
→
cardNo
- Number of the storage card on which the application resides.
-
→
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
AlmGetProcAlarm Macro
Purpose
Returns the date and time that a procedure alarm will trigger. Also returns the caller-defined alarm reference value.
Declared In
AlarmMgr.h
Prototype
#define AlmGetProcAlarm ( procP, refP )
Parameters
-
→
procP
- Pointer to a function that will be called when alarm is triggered. See
AlmAlarmProcPtr()
. -
←
refP
- A
UInt32
pointer to a location where the alarm's reference value is returned. This value is passed to the procedure 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 procedure, 0 is returned for the alarm seconds and the reference value is undefined.
Compatibility
Implemented only if 3.2 New Feature Set is present.
See Also
AlmSetAlarm Function
Purpose
Set or cancel an alarm for the given application.
Declared In
AlarmMgr.h
Prototype
Err AlmSetAlarm ( UInt16 cardNo, LocalID dbID, UInt32 ref, UInt32 alarmSeconds, Boolean quiet )
Parameters
-
→
cardNo
- Number of the storage card on which the application resides.
-
→
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 upgrade. This value is not currently used.
Returns
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. Read more about these launch codes in Chapter 1, "Application Launch Codes."
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
AlmSetProcAlarm Macro
Purpose
Sets or cancels a procedure alarm.
Declared In
AlarmMgr.h
Prototype
#define AlmSetProcAlarm ( procP, ref, alarmSeconds )
Parameters
-
→
procP
- Pointer to a function that should be called when alarm is triggered. See
AlmAlarmProcPtr()
. -
→
ref
- A caller-defined
UInt32
value. This value is passed with the launch code that notifies the application that the alarm has been triggered. -
→
alarmSeconds
- A
UInt32
indicating the alarm date/time in seconds since 1/1/1904, or 0 to cancel the current alarm (if any).
Returns
Returns one of the following error codes:
Comments
This macro is similar to the AlmSetAlarm()
function, but it specifies a procedure to be called at the specified date and time rather than an application to be launched. With this macro, you can set alarms that are independent of any application. For example, a shared library can set procedure alarms that call a procedure implemented in the library.
Procedure alarms also differ from regular system alarms in that if they trigger when the device is in sleep mode, the LCD does not light up. Thus, you can use procedure alarms to perform a scheduled task in a manner that is entirely hidden from the user.
IMPORTANT: Because the
procP
pointer is used to directly call the procedure, the pointer must remain valid from the time AlmSetProcAlarm
is called to the time the alarm is triggered. If the procedure is in a shared library, you must keep the library open. If the procedure is in a separately loaded code resource, the resource must remain locked until the alarm is triggered. When you close a library or unlock a resource, you must remove any pending alarms. If you don't, the system will crash when the alarm is triggered.
Compatibility
Implemented only if 3.2 New Feature Set is present.
See Also
Application-Defined Functions
AlmAlarmProcPtr Function
Purpose
A procedure to be executed when an alarm is triggered.
Declared In
AlarmMgr.h
Prototype
void ( *AlmAlarmProcPtr ) ( UInt16 almProcCmd, SysAlarmTriggeredParamType *paramP )
Parameters
-
→
almProcCmd
- One of the
AlmProcCmdEnum
constants. These are commands that your function must handle. Possible values are: -
almProcCmdTriggered
- The alarm's date and time has passed and the alarm has been triggered. The function should perform its main task in response to this command.
-
almProcCmdReschedule
- A system time change occurred, so the function must reschedule the alarm.
-
→
paramP
- Pointer to a
SysAlarmTriggeredParamType
structure. See below.
Returns
Comments
AlmAlarmProcPtr
procedures are called when an alarm set by AlmSetProcAlarm()
is triggered. Your implementation should check the value of almProcCmd
and respond accordingly.
The paramP
parameter is a pointer to a SysAlarmTriggeredParamType
structure. This structure is defined as:
typedef struct SysAlarmTriggeredParamType { UInt32 ref; UInt32 alarmSeconds; Boolean purgeAlarm; } SysAlarmTriggeredParamType;
ref
and alarmSeconds
are both values specified in AlmSetProcAlarm()
when the alarm is set. The purgeAlarm
field specifies if the alarm will be removed from the alarm table when the function returns so that the sysAppLaunchCmdDisplayAlarm
launch code is not triggered. This should be true
for all procedure alarms; the alarm manager set it to true
for you after your function returns.
If necessary, you can define new values for the almProcCmd
parameter to call the procedure for something other than a triggered alarm or a system time change. The value you use must be greater than the constant almProcCmdCustom
as defined in AlarmMgr.h
.
Compatibility
Implemented only if 3.2 New Feature Set is present.