Documentation  |   Table of Contents   |  < Previous   |  Next >   |  Index

24    Alarm Manager

Palm OS® Programmer's API Reference

Palm OS® 68K SDK

     

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 ^TOP^

AlmGetAlarm Function ^TOP^

Purpose

Return the date and time for the application's alarm, if one is set.

Declared In

AlarmMgr.h

Prototype

UInt32 AlmGetAlarm (
   UInt16cardNo,
   LocalIDdbID,
   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

AlmSetAlarm()

AlmGetProcAlarm Macro ^TOP^

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

AlmSetProcAlarm()

AlmSetAlarm Function ^TOP^

Purpose

Set or cancel an alarm for the given application.

Declared In

AlarmMgr.h

Prototype

Err AlmSetAlarm (
   UInt16cardNo,
   LocalIDdbID,
   UInt32ref,
   UInt32alarmSeconds,
   Booleanquiet
)

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

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 Macro ^TOP^

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:

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 ^TOP^

AlmAlarmProcPtr Function ^TOP^

Purpose

A procedure to be executed when an alarm is triggered.

Declared In

AlarmMgr.h

Prototype

void (
   *AlmAlarmProcPtr
) (
   UInt16almProcCmd,
   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

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 { 
UInt32ref; 
UInt32alarmSeconds; 
BooleanpurgeAlarm;
} 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()