< Home < Developers < Development Support < Documentation

## 24 Alarm Manager

Table of Contents | < Previous | Next > | Index

| Title - Palm OS® Programmer's API Reference Part II: System Management 24 Alarm Manager Alarm Manager Functions AlmGetAlarm AlmGetProcAlarm AlmSetAlarm AlmSetProcAlarm Application-Defined Functions AlmAlarmProcPtr |  |  |  | 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 #####
0 | No error.
#####
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: #####
0 | No error.
#####
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 |