23 Alarm Manager

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.

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