This chapter provides reference material for the alarm manager:
Alarm Manager Functions
Application-Defined Functions
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

Purpose
Return the date and time for the application's alarm, if one is set.
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. |
Result
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
AlmGetProcAlarm

Purpose
Macro that returns the date and time that a procedure alarm will trigger. Also returns the caller-defined alarm reference value.
Prototype
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. |
Result
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
AlmSetProcAlarm
AlmSetAlarm

Purpose
Set or cancel an alarm for the given application.
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. |
Result
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. 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
AlmGetAlarm
AlmSetProcAlarm

Purpose
Macro that sets or cancels a procedure alarm.
Prototype
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). |
Result
Returns one of the following error codes:
almErrMemory | Insufficient memory. |
almErrFull | Alarm table is full. |
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
AlmGetProcAlarm
Application-Defined Functions

AlmAlarmProcPtr

Purpose
A procedure to be executed when an alarm is triggered.
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. |
Result
Returns nothing.
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.
See Also
AlmGetProcAlarm
|