1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/epoc32/include/mw/asshddefs.h Wed Mar 31 12:27:01 2010 +0100
1.3 @@ -0,0 +1,414 @@
1.4 +// Copyright (c) 1999-2009 Nokia Corporation and/or its subsidiary(-ies).
1.5 +// All rights reserved.
1.6 +// This component and the accompanying materials are made available
1.7 +// under the terms of the License "Symbian Foundation License v1.0" to Symbian Foundation members and "Symbian Foundation End User License Agreement v1.0" to non-members
1.8 +// which accompanies this distribution, and is available
1.9 +// at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".
1.10 +//
1.11 +// Initial Contributors:
1.12 +// Nokia Corporation - initial contribution.
1.13 +//
1.14 +// Contributors:
1.15 +//
1.16 +// Description:
1.17 +//
1.18 +
1.19 +#ifndef __ASSHDDEFS_H__
1.20 +#define __ASSHDDEFS_H__
1.21 +
1.22 +/** @file
1.23 +@publishedAll
1.24 +@released */
1.25 +
1.26 +// System includes
1.27 +#include <e32std.h>
1.28 +#include <babitflags.h>
1.29 +
1.30 +// Constants
1.31 +
1.32 +/** Maximum length of an alarm message. The message is usually displayed by the
1.33 +alarm UI. */
1.34 +const TInt KMaxAlarmMessageLength = 0x80;
1.35 +/** Maximum length of the filename of the sound played when an alarm expires. */
1.36 +const TInt KMaxAlarmSoundNameLength = KMaxFileName;
1.37 +
1.38 +// Type definitions
1.39 +/** A unique identifier allocated to each new alarm by the alarm server, so that
1.40 +the client can identify them. By default, KNullAlarmId. */
1.41 +typedef TInt TAlarmId;
1.42 +/** A unique identifier that can optionally be used by clients to group
1.43 +alarms into categories, for instance alarms associated with a particular application
1.44 +or application engine. The alarm server ignores the category. It is relevant
1.45 +to the client alone. */
1.46 +typedef TUid TAlarmCategory;
1.47 +//
1.48 +/** Flags that define an alarm's characteristics.
1.49 +
1.50 +@see TAlarmCharacteristics */
1.51 +typedef TBitFlags8 TAlarmCharacteristicsFlags;
1.52 +//
1.53 +
1.54 +/** A type to identify what kind of alarms should be deleted when using the API
1.55 +RASCliSession::AlarmDeleteByCategory()
1.56 +@see TTDeleteTypeEnum */
1.57 +typedef TInt TDeleteType;
1.58 +
1.59 +/** Stores the text message associated with an alarm. */
1.60 +typedef TBuf<KMaxAlarmMessageLength> TAlarmMessage;
1.61 +/** Stores the name of a sound file which is played when an alarm activates. */
1.62 +typedef TBuf<KMaxAlarmSoundNameLength> TAlarmSoundName;
1.63 +//
1.64 +/** Defines a null alarm identifier. */
1.65 +const TAlarmId KNullAlarmId = 0;
1.66 +//
1.67 +/** Defines the length in seconds of an alarm sound offset. */
1.68 +const TInt KDefaultSoundPlayOffsetInSeconds = 0;
1.69 +/** Defines the length in seconds of an alarm sound duration. */
1.70 +const TInt KDefaultSoundPlayDurationInSeconds = 30;
1.71 +
1.72 +// Constants
1.73 +/** A category that can be assigned to identify clock alarms to the client. The
1.74 +server does not distinguish between alarm types. */
1.75 +const TAlarmCategory KASCliCategoryClock = { 0x101F5030 };
1.76 +
1.77 +/** Defines whether an alarm is enabled or disabled:
1.78 +
1.79 +An enabled alarm activates at a specified time.
1.80 +
1.81 +A disabled alarm remains in the alarm server queue but is not active.
1.82 +
1.83 +You can get or set an alarm's status using the RASCliSession class. */
1.84 +enum TAlarmStatus
1.85 + {
1.86 + /** The alarm is currently enabled. */
1.87 + EAlarmStatusEnabled = 0,
1.88 +
1.89 + /** The alarm is currently disabled, and will not expire. */
1.90 + EAlarmStatusDisabled,
1.91 + };
1.92 +
1.93 +/** Represents an alarm's state. Alarms can have only one state. */
1.94 +enum TAlarmState
1.95 + {
1.96 + /** The alarm state is not currently known by the alarm server. */
1.97 + EAlarmStateInPreparation = -1,
1.98 +
1.99 + /** The alarm is waiting for its expiry time to be reached. */
1.100 + EAlarmStateQueued = 0,
1.101 +
1.102 + /** The alarm is snoozed. When the snooze period is over, the alarm expires again. */
1.103 + EAlarmStateSnoozed,
1.104 +
1.105 + /** The alarm is waiting to be notified.
1.106 +
1.107 + This state occurs when an alarm expires while another is being notified. When
1.108 + this happens, the alarm being notified changes state to EAlarmStateWaitingToNotify.
1.109 + This means that if it is set to be the next alarm to be notified, notification
1.110 + will happen after the newly expired alarm has been notified and dismissed. */
1.111 + EAlarmStateWaitingToNotify,
1.112 +
1.113 + /** The alarm is currently notifying. */
1.114 + EAlarmStateNotifying,
1.115 +
1.116 + /** The alarm has already notified and has been dismissed. Any alarm which remains
1.117 + in this state is dead. */
1.118 + EAlarmStateNotified
1.119 + };
1.120 +
1.121 +/** Defines an alarm session type as timed or untimed. This property is ignored by
1.122 +the alarm server, and is for use by the client only. */
1.123 +enum TAlarmDayOrTimed
1.124 + {
1.125 + /** Timed alarm type (default). This alarm belongs to a timed event. This is an event
1.126 + with a defined start and finish time. The alarm notification
1.127 + time is specified as an offset from the event's start time, so that when the
1.128 + event time changes, so does the alarm time. */
1.129 + EASShdAlarmTypeTimed = 0,
1.130 +
1.131 + /** Day alarm type. This alarm belongs to untimed events; these do not have
1.132 + a defined start and finish time, but have an activation time. */
1.133 + EASShdAlarmTypeDay
1.134 + };
1.135 +
1.136 +/** Defines the sound state of the global alarm server . */
1.137 +enum TAlarmGlobalSoundState
1.138 + {
1.139 + /** When an alarm expires, the alarm sound is played. */
1.140 + EAlarmGlobalSoundStateOn = 0,
1.141 +
1.142 + /** When an alarm expires, no sound plays. */
1.143 + EAlarmGlobalSoundStateOff
1.144 + };
1.145 +
1.146 +/** Defines how an alarm is to be repeated. */
1.147 +enum TAlarmRepeatDefinition
1.148 + {
1.149 + /** The alarm expires only once, and is then deleted from the alarm server. By
1.150 + default, all alarms behave this way.
1.151 +
1.152 + Standard repeat-once alarms are date relative, that is, they occur on a fixed
1.153 + date and point in time.
1.154 +
1.155 + If the user changes the system date or time so that the new time is in the
1.156 + future, and the new time is after the previously calculated expiry time:
1.157 +
1.158 + By less than 12 hours, the alarm expires immediately.
1.159 +
1.160 + By more than 12 horus, the alarm is silently discarded.
1.161 +
1.162 + If the user changes the system date or time so that the new time is before
1.163 + the next calculated expiry time, the alarm type continues to be a
1.164 + "Repeat once" alarm*/
1.165 + EAlarmRepeatDefintionRepeatOnce = 0,
1.166 +
1.167 + /** When initially scheduling the alarm, the date is always within the
1.168 + next 24 hours. For example:
1.169 +
1.170 + The current time is 15:00, and the alarm time specified is 14:00. The
1.171 + alarm expires tomorrow at 14:00.
1.172 +
1.173 + The current time is 15:00, and the alarm time specified is 16:00. The
1.174 + alarm expires today at 16:00.
1.175 +
1.176 + If the alarm is missed, i.e. because the alarm server is inactive, then
1.177 + the alarm changes its type from "Repeat in the next 24 Hours" to "Repeat once".
1.178 +
1.179 + If the user changes the system date or time so that the new time is in the
1.180 + future, and the new time is after the previously calculated expiry time:
1.181 +
1.182 + By less than 12 hours, the alarm expires immediately.
1.183 +
1.184 + By more than 12 horus, the alarm is silently discarded.
1.185 +
1.186 + If the user changes the system date or time so that the new time is
1.187 + before the next calculated expiry time:
1.188 +
1.189 + By less than 12 hours, no change in alarm type, and the alarm
1.190 + remains queued.
1.191 +
1.192 + By greater than 12 hours, the alarm changes its type from
1.193 + "Repeat in the next 24 Hours" to "Repeat once". Subsequent changes in system
1.194 + time result in the behaviour described by the EAlarmRepeatDefintionRepeatOnce
1.195 + characteristic. */
1.196 + EAlarmRepeatDefintionRepeatNext24Hours,
1.197 +
1.198 + /** The alarm repeats every day at the same time. If the user changes the system
1.199 + date or time, this alarm behaves in the same way as a "Repeat once" alarm,
1.200 + except that the alarm is not deleted, but rescheduled for the next available
1.201 + time.
1.202 +
1.203 + If the user changes the system date or time to a point in the past, there
1.204 + are no phantom alarm expiries. */
1.205 + EAlarmRepeatDefintionRepeatDaily,
1.206 +
1.207 + /** The alarm repeats every work day at the same time. If the user changes the
1.208 + system date or time, this alarm behaves in the same way as a "Repeat once"
1.209 + alarm, except that the alarm is not deleted, but rescheduled for the next
1.210 + available time.
1.211 +
1.212 + If the user changes the system date or time to a point in the past, there
1.213 + are no phantom alarm expiries. */
1.214 + EAlarmRepeatDefintionRepeatWorkday,
1.215 +
1.216 + /** The alarm repeats every week, on the same day at the same time. If the user
1.217 + changes the system date or time, this alarm behaves in the same way as a "Repeat
1.218 + once" alarm, except that the alarm is not deleted, but rescheduled for the
1.219 + next available time.
1.220 +
1.221 + If the user changes the system date or time to a point in the past, there
1.222 + are no phantom alarm expiries. */
1.223 + EAlarmRepeatDefintionRepeatWeekly,
1.224 +
1.225 + /** The alarm repeats every specified day at the same time. If the user
1.226 + changes the system date or time, this alarm behaves in the same way as a
1.227 + "repeat once" alarm, except that the alarm is not deleted, but rescheduled
1.228 + for the next available time.
1.229 +
1.230 + If the user changes the system date or time to a point in the past, there
1.231 + are no phantom alarm expiries.*/
1.232 + EAlarmRepeatDefinitionRepeatDailyOnGivenDays
1.233 + };
1.234 +
1.235 +/** Defines various alarm characteristics. */
1.236 +enum TAlarmCharacteristics
1.237 + {
1.238 + /** Sets an alarm to be session-only. This alarm only exists as long as a session
1.239 + is maintained with the alarm server. Session alarms are removed from the alarm
1.240 + queue when the originating session disconnects from the server. By default,
1.241 + all alarms are persistent and remain so, even after the initiating session
1.242 + has disconnected. */
1.243 + EAlarmCharacteristicsSessionSpecific = 0,
1.244 +
1.245 + /** Do not display a screen. By default, all alarms result in a suitable screen
1.246 + being displayed, depending on the device. Use this flag to disable this default
1.247 + behaviour. */
1.248 + EAlarmCharacteristicsDoNotNotifyAlarmAlertServer = 1,
1.249 +
1.250 + /** Sets an alarm to be floating - floating alarms expire at the current local time,
1.251 + regardless of the current locale or DST rules.*/
1.252 + EAlarmCharacteristicsIsFixed = 2,
1.253 +
1.254 + /** Do not notify if its due time is in the past.*/
1.255 + EAlarmCharacteristicsDeQueueIfDueTimeInPast = 3,
1.256 + //
1.257 + EAlarmCharacteristicsLast
1.258 + };
1.259 +
1.260 +/** This enumeration defines the events that can be reported by the alarm server.
1.261 +
1.262 +These events are channelled to the client using the RASCliSession::NotifyChange()
1.263 +method.
1.264 +
1.265 +@see TAlarmState */
1.266 +enum TAlarmChangeEvent
1.267 + {
1.268 + /** An alarm has changed state.
1.269 +
1.270 + @see TAlarmState */
1.271 + EAlarmChangeEventState = 1,
1.272 +
1.273 + /** An alarm has changed status.
1.274 +
1.275 + @see TAlarmStatus */
1.276 + EAlarmChangeEventStatus = 2,
1.277 +
1.278 + /** An alarm has changed characteristics.
1.279 +
1.280 + @see TAlarmCharacteristics */
1.281 + EAlarmChangeEventCharacteristics = 3,
1.282 +
1.283 + /** An alarm has been deleted from the queue of alarms. */
1.284 + EAlarmChangeEventAlarmDeletion = 4,
1.285 +
1.286 + /** An alarm has been added to the queue of alarms. */
1.287 + EAlarmChangeEventAlarmAddition = 5,
1.288 +
1.289 + /** An alarm has expired. */
1.290 + EAlarmChangeEventTimerExpired = 6,
1.291 +
1.292 + /** The sound for an alarm has just started playing. */
1.293 + EAlarmChangeEventSoundPlaying = 7,
1.294 +
1.295 + /** The sound for an alarm has just stopped playing. */
1.296 + EAlarmChangeEventSoundStopped = 8,
1.297 +
1.298 + /** The sound intervals associated with sound timing have changed. */
1.299 + EAlarmChangeEventPlayIntervalsChanged = 9,
1.300 +
1.301 + /** The global sound state (on/off) has changed. */
1.302 + EAlarmChangeEventGlobalSoundStateChanged = 10,
1.303 +
1.304 + /** The next alarm at the head of the alarm queue has changed. */
1.305 + EAlarmChangeEventHeadQueueItemChanged = 11,
1.306 +
1.307 + /** The system date or time has changed, or the days defined as workdays have changed. */
1.308 + EAlarmChangeEventSystemDateTimeChanged = 12,
1.309 +
1.310 + /** The alarm alert server has been instructed to show the 'alarm expired' display. */
1.311 + EAlarmChangeEventAlarmUIVisible = 13,
1.312 +
1.313 + /** The alarm alert server has been instructed to hide the 'alarm expired' display. */
1.314 + EAlarmChangeEventAlarmUIInvisible = 14,
1.315 +
1.316 + /** Alarm sounds have been temporarily silenced, the current alarm has been paused
1.317 + or re-enabled. */
1.318 + EAlarmChangeEventSoundSilence = 15,
1.319 +
1.320 + /** The data associated with an alarm has changed. */
1.321 + EAlarmChangeEventAlarmData = 16,
1.322 +
1.323 + /** A restore from backup of the alarm server has started. Alarms cannot be added/deleted
1.324 + until this has finished. */
1.325 + EAlarmChangeEventRestoreStarted = 17,
1.326 +
1.327 + /** A restore from backup of the alarm server has failed. Alarms can be added/deleted again. */
1.328 + EAlarmChangeEventRestoreFailed = 18,
1.329 +
1.330 + /** A restore from backup of the alarm server has completed. The alarm queue has changed. */
1.331 + EAlarmChangeEventRestoreCompleted = 19,
1.332 +
1.333 + /** Last change event (anchor). This is always at the end of the list. */
1.334 + EAlarmChangeEventLast,
1.335 +
1.336 + /** An undefined alarm event has occurred. */
1.337 + EAlarmChangeEventUndefined = 0
1.338 + };
1.339 +
1.340 +/** Identifies server-initiated panics relating to the client session. */
1.341 +enum TAlarmServerInitiatedClientPanic
1.342 + {
1.343 + /** This panic occurs when the client requests a copy of any data attached to an
1.344 + alarm, but does not supply enough buffer space to contain the data. */
1.345 + EAlarmServerInitiatedClientPanicInsufficientRoomForAlarmData = 0,
1.346 +
1.347 + /** This panic usually occurs when a client method tries to write to a descriptor
1.348 + (sometimes asynchronously), and the client-supplied descriptor is not valid. */
1.349 + EAlarmServerInitiatedClientPanicBadDescriptor = 1,
1.350 +
1.351 + /** This panic occurs when a client already has an outstanding notification request,
1.352 + but attempts to request another. */
1.353 + EAlarmServerInitiatedClientPanicChangeNotificationAlreadyOutstanding = 2,
1.354 +
1.355 + /** This panic occurs when a client tries to perform an invalid operation. */
1.356 + EAlarmServerInitiatedClientPanicInvalidOperation = 3,
1.357 +
1.358 + /** This panic occurs when a request to add an alarm contains a null alarm identiifer.
1.359 + In the case of alarms with notifications, the client should pre-allocate the
1.360 + alarm identifier before requesting the notification. */
1.361 + EAlarmServerInitiatedClientPanicBadPreAllocatedAlarmId = 4
1.362 +
1.363 + };
1.364 +
1.365 +/** Identifies what kind of alarms the client wants to delete. */
1.366 +enum TDeleteTypeEnum
1.367 + {
1.368 + /** All type of alarms. */
1.369 + EAllAlarms = 0,
1.370 + /** Alarms future of the current time */
1.371 + EFuture = 1,
1.372 + /** Alarms in the past of the current time but notifying, or waiting to notify, or snoozed by, the user */
1.373 + EActive = 2,
1.374 + /** alarms that has been dismissed by the user */
1.375 + EExpired = 4
1.376 + };
1.377 +
1.378 +/**
1.379 +This enumeration indicates which days of the week an alarm with a repeat
1.380 +definition of EAlarmRepeatDefinitionRepeatDailyOnGivenDays activates on. Days
1.381 +are combined using the bitwise OR operator.
1.382 +
1.383 +@prototype
1.384 +*/
1.385 +enum TAlarmDays
1.386 + {
1.387 + /** Alarm is active on Monday. */
1.388 + EAlarmDayMonday = 0x01,
1.389 + /** Alarm is active on Tuesday. */
1.390 + EAlarmDayTuesday = 0x02,
1.391 + /** Alarm is active on Wednesday. */
1.392 + EAlarmDayWednesday = 0x04,
1.393 + /** Alarm is active on Thursday. */
1.394 + EAlarmDayThursday = 0x08,
1.395 + /** Alarm is active on Friday. */
1.396 + EAlarmDayFriday = 0x10,
1.397 + /** Alarm is active on Saturday. */
1.398 + EAlarmDaySaturday = 0x20,
1.399 + /** Alarm is active on Sunday. */
1.400 + EAlarmDaySunday = 0x40
1.401 + };
1.402 +
1.403 +/** Identifies the type of alarm which was missed. A UTC offset change will only
1.404 +affect floating alarms whereas a system time change may affect either floating
1.405 +or fixed alarms.
1.406 +@see TASShdAlarmedInstanceParams
1.407 +@see CASSrvAlarmQueue::MEnvChangeHandleEvent
1.408 +*/
1.409 +enum TASShdAlarmTimeType
1.410 + {
1.411 + /** Floating time alarm. */
1.412 + EFloating,
1.413 + /** Floating or fixed time alarm. */
1.414 + EFloatingOrFixed
1.415 + };
1.416 +
1.417 +#endif