/******************************************************************* Copyright © 1995 - 1998, 3Com Corporation or its subsidiaries ("3Com"). All rights reserved. This software may be copied and used solely for developing products for the Palm Computing platform and for archival and backup purposes. Except for the foregoing, no part of this software may be reproduced or transmitted in any form or by any means or used to make any derivative work (such as translation, transformation or adaptation) without express written consent from 3Com. 3Com reserves the right to revise this software and to make changes in content from time to time without obligation on the part of 3Com to provide notification of such revision or changes. 3COM MAKES NO REPRESENTATIONS OR WARRANTIES THAT THE SOFTWARE IS FREE OF ERRORS OR THAT THE SOFTWARE IS SUITABLE FOR YOUR USE. THE SOFTWARE IS PROVIDED ON AN "AS IS" BASIS. 3COM MAKES NO WARRANTIES, TERMS OR CONDITIONS, EXPRESS OR IMPLIED, EITHER IN FACT OR BY OPERATION OF LAW, STATUTORY OR OTHERWISE, INCLUDING WARRANTIES, TERMS, OR CONDITIONS OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND SATISFACTORY QUALITY. TO THE FULL EXTENT ALLOWED BY LAW, 3COM ALSO EXCLUDES FOR ITSELF AND ITS SUPPLIERS ANY LIABILITY, WHETHER BASED IN CONTRACT OR TORT (INCLUDING NEGLIGENCE), FOR DIRECT, INCIDENTAL, CONSEQUENTIAL, INDIRECT, SPECIAL, OR PUNITIVE DAMAGES OF ANY KIND, OR FOR LOSS OF REVENUE OR PROFITS, LOSS OF BUSINESS, LOSS OF INFORMATION OR DATA, OR OTHER FINANCIAL LOSS ARISING OUT OF OR IN CONNECTION WITH THIS SOFTWARE, EVEN IF 3COM HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. 3Com, HotSync, Palm Computing, and Graffiti are registered trademarks, and Palm III and Palm OS are trademarks of 3Com Corporation or its subsidiaries. IF THIS SOFTWARE IS PROVIDED ON A COMPACT DISK, THE OTHER SOFTWARE AND DOCUMENTATION ON THE COMPACT DISK ARE SUBJECT TO THE LICENSE AGREEMENT ACCOMPANYING THE COMPACT DISK. *------------------------------------------------------------------- * FileName: * AlarmMgr.h * * Description: * Include file for Alarm Manager * * History: * 4/11/95 VMK - Created by Vitaly Kruglikov * *******************************************************************/ #ifndef __ALARM_MGR_H__ #define __ALARM_MGR_H__ // Include elementary types #include #include /************************************************************ * Alarm Manager result codes * (almErrorClass is defined in SystemMgr.h) *************************************************************/ #define almErrMemory (almErrorClass | 1) // ran out of memory #define almErrFull (almErrorClass | 2) // alarm table is full /******************************************************************** * Alarm Manager Structures ********************************************************************/ // Structure passed with the sysAppLaunchCmdAlarmTriggered action code: // // This is a notification that an alarm set by the creator has // gone off. The action code handler should not do anything time- // consuming here. The intended use is to set the next alarm and/or // to perform some quick maintenance task. Particularly, this action code // handler is not allowed to display any UI(dialogs, etc.) -- this would delay // notification for alarms set by others. This action code may be ignored. typedef struct SysAlarmTriggeredParamType { DWord ref; // --> alarm reference value passed by caller; ULong alarmSeconds; // --> alarm date/time in seconds since 1/1/1904; Boolean purgeAlarm; // <-- if set to true on return, this alarm // will be removed from the alarm table and the // display notification will NOT be generated for it } SysAlarmTriggeredParamType; // Structure passed with the sysAppLaunchCmdDisplayAlarm action code: // // This is a notification to display an alarm. This action code // will be called sometime after the app receives a sysAppLaunchCmdAlarmTriggered // notification(perhaps after a significant delay). It is possible that this // notification will not be sent at all in the event the alarm table becomes full and // the alarm table entry is used to hold a new alarm (this does NOT apply to the // sysAppLaunchCmdAlarmTriggered notification). This action code may be ignored. typedef struct SysDisplayAlarmParamType { DWord ref; // alarm reference value passed by caller; ULong alarmSeconds; // alarm date/time in seconds since 1/1/1904; Boolean soundAlarm; // non-zero if alarm needs to be sounded; } SysDisplayAlarmParamType; /******************************************************************** * Alarm Manager Routines * These are define as external calls only under emulation mode or * under native mode from the module that actually installs the trap * vectors ********************************************************************/ #ifdef __cplusplus extern "C" { #endif //------------------------------------------------------------------- // Initialization //------------------------------------------------------------------- // // ISSUES: // 1. Is the Alarms Database always on Card 0 ? // // A: We will store alarm info on the dynamic heap. Upon reset and // time change, apps will be notified via action code and will re- // submit their alarms. // // 2. Should a semaphore be used by the Alarm Manager ? // // A: No. Present implementation does not require it. May add one // in the future to ensure data integrity between tasks. // // 3. Pilot will need to go back to sleep even if the alarms dialog box is // not closed after some interval. // // A: This will happen in GetNextEvent. // // 4. We will need to sound the alarm for all newly triggered alarms // even while another alarm dialog box is on-screen. // // A: Yes. We will keep a flag in our globals to indicate when the // alarm manager is displaying an alarm. This way we do not hog // stack and dynamic heap memory with additional alarm boxes. // // 5. Should the alarm dialog box be system-modal ? // // A: Yes -- by swallowing the "QUIT" (and/or others) message in the alarm dialog's // event loop. // // AlmInit() // // Initializes the Alarm Manager. // // Create the Alarm Globals. // Err AlmInit(void) SYS_TRAP(sysTrapAlmInit); //------------------------------------------------------------------- // API //------------------------------------------------------------------- // AlmSetAlarm() // // Sets an alarm for the given application. If an alarm for that // application had been previously set, it will be replaced. Passing // a zero for alarmSeconds cancels the current alarm for the application. // Err AlmSetAlarm(UInt cardNo, LocalID dbID, DWord ref, ULong alarmSeconds, Boolean quiet) SYS_TRAP(sysTrapAlmSetAlarm); // AlmGetAlarm() // // Gets the alarm seconds for a given app. // Zero is returned if there is no alarm setting for the app. ULong AlmGetAlarm(UInt cardNo, LocalID dbID, DWordPtr refP) SYS_TRAP(sysTrapAlmGetAlarm); // AlmEnableNotification // // Enables/disables Alarm Manager's notification mechanism. For example, // the HotSync application disables Alarm notifications during the sync // to ensure that apps do not try to access their data database until // the DesktopLink server had a chance to notify the apps whose databases // were modified during the session. This also prevents the alarm dialogs from // blocking the HotSync UI. A call to disable MUST always // precede the call to enable. // void AlmEnableNotification(Boolean enable) SYS_TRAP(sysTrapAlmEnableNotification); // AlmDisplayAlarm() // // Displays any alarms that have gone off. // // This function is called by the Event Manager executing on some app's // thread. This permits us to access resources and execute system calls // which would not be possible at interrupt time. // void AlmDisplayAlarm(Boolean okToDisplay) SYS_TRAP(sysTrapAlmDisplayAlarm); // AlmCancelAll() // // Cancels all alarms managed by the Alarm Manager. This // function is presently called by the Time Manager to cancel all alarms // when the user changes date/time. // void AlmCancelAll(void) SYS_TRAP(sysTrapAlmCancelAll); // AlmAlarmCallback() // // This function is called at interrupt time by the Time Manager when // an alarm goes off. // void AlmAlarmCallback(void) SYS_TRAP(sysTrapAlmAlarmCallback); #ifdef __cplusplus } #endif #endif // __ALARM_MGR_H__