1.1 --- a/epoc32/include/schinfo.h Tue Nov 24 13:55:44 2009 +0000
1.2 +++ b/epoc32/include/schinfo.h Tue Mar 16 16:12:26 2010 +0000
1.3 @@ -1,1 +1,540 @@
1.4 -schinfo.h
1.5 +// Copyright (c) 2004-2009 Nokia Corporation and/or its subsidiary(-ies).
1.6 +// All rights reserved.
1.7 +// This component and the accompanying materials are made available
1.8 +// 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.9 +// which accompanies this distribution, and is available
1.10 +// at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".
1.11 +//
1.12 +// Initial Contributors:
1.13 +// Nokia Corporation - initial contribution.
1.14 +//
1.15 +// Contributors:
1.16 +//
1.17 +// Description:
1.18 +// Various T-classes for client input to scheduler, scheduler output to client
1.19 +// These classes comprise part of the interface (the rest is defined in RScheduler)
1.20 +//
1.21 +//
1.22 +
1.23 +#if !defined (__SCHINFO_H__)
1.24 +#define __SCHINFO_H__
1.25 +
1.26 +#if !defined (__SCHTIME_H__)
1.27 +#include <schtime.h>
1.28 +#endif
1.29 +
1.30 +#if !defined(__E32BASE_H__)
1.31 +#include <e32base.h>
1.32 +#endif
1.33 +
1.34 +#include <s32strm.h>
1.35 +
1.36 +/**
1.37 +Contains detailed information for a single task.
1.38 +
1.39 +A schedule can have any number of tasks. An object of this type is passed
1.40 +to RScheduler::ScheduleTask(). Objects of this type are also returned by functions
1.41 +within RScheduler that retrieve information about tasks.
1.42 +
1.43 +@see RScheduler::ScheduleTask()
1.44 +@see RScheduler::GetScheduleL()
1.45 +@see RScheduler::GetTaskInfoL()
1.46 +@publishedAll
1.47 +@released
1.48 +*/
1.49 +class TTaskInfo
1.50 + {
1.51 +public:
1.52 + //ctors
1.53 + IMPORT_C TTaskInfo (TInt aTaskId, TName& aName, TInt aPriority, TInt aRepeat);
1.54 + IMPORT_C TTaskInfo();//
1.55 + //assignment
1.56 + IMPORT_C TTaskInfo& operator=(const TTaskInfo& aTaskInfo);
1.57 + IMPORT_C void ExternalizeL(RWriteStream& aStream) const;
1.58 + IMPORT_C void InternalizeL(RReadStream& aStream);
1.59 + //needs a copy ctor
1.60 + //TTaskInfo (TTaskInfo& aTaskInfo);
1.61 +
1.62 + //data
1.63 + /** Specifies how often the task is to be repeated.
1.64 +
1.65 + This is defined by the client.
1.66 +
1.67 + A value of 1 means once, a value of 2 means twice etc.
1.68 +
1.69 + Note that zero is interpreted to mean once, and a negative value is interpreted
1.70 + to mean that the task will be repeated until it is explicitly deleted. */
1.71 + TInt iRepeat;
1.72 +
1.73 + /** The unique Id for the task.
1.74 +
1.75 + This is generated by the Task Scheduler. Clients should use the generated
1.76 + Id to refer to the task in future transactions. */
1.77 + TInt iTaskId;
1.78 +
1.79 + /** The name of the task.
1.80 +
1.81 + This is defined by the client.
1.82 +
1.83 + @see TName */
1.84 + TName iName;
1.85 +
1.86 + /** The priority of the task.
1.87 +
1.88 + This is defined by the client.
1.89 +
1.90 + Determines the order in which a client's tasks are executed. Where a client
1.91 + has two tasks with different priorities, the task with the higher priority
1.92 + will be executed first. */
1.93 + TInt iPriority;
1.94 + };
1.95 +
1.96 +/**
1.97 +Defines a filter to be used when listing tasks scheduled in a call to RScheduler::GetTaskRefsL().
1.98 +
1.99 +@see RScheduler::GetTaskRefsL()
1.100 +@publishedAll
1.101 +@released
1.102 +*/
1.103 +enum TTaskFilter
1.104 + {
1.105 + /** Indicates that all tasks are to be selected. */
1.106 + EAllTasks,
1.107 + /** Indicates those tasks associated with the executing program with which the
1.108 + calling client is associated, are to be selected. */
1.109 + EMyTasks
1.110 + };
1.111 +
1.112 +
1.113 +/**
1.114 +Defines a filter to be used when listing schedules in a call to RScheduler::GetScheduleRefsL(),
1.115 +and when listing tasks in a call to RScheduler::GetTaskRefsL().
1.116 +
1.117 +@see RScheduler::GetScheduleRefsL()
1.118 +@see RScheduler::GetTaskRefsL()
1.119 +@publishedAll
1.120 +@released
1.121 +*/
1.122 +enum TScheduleFilter
1.123 + {
1.124 + /** Indicates that all schedules are to be selected. */
1.125 + EAllSchedules,
1.126 + /** Indicates that only pending schedules are to be selected.
1.127 +
1.128 + Note that pending schedules are those that are enabled and have tasks associated
1.129 + with them. */
1.130 + EPendingSchedules
1.131 + };
1.132 +
1.133 +/**
1.134 +Defines the type of interval used by a schedule entry.
1.135 +
1.136 +@see TScheduleEntryInfo
1.137 +@publishedAll
1.138 +@released
1.139 +*/
1.140 +enum TIntervalType
1.141 + {
1.142 + /** The interval is based on hours. */
1.143 + EHourly,
1.144 + /** The interval is based on days. */
1.145 + EDaily,
1.146 + /** The interval is based on months. */
1.147 + EMonthly,
1.148 + /** The interval is based on years. */
1.149 + EYearly
1.150 + };
1.151 +
1.152 +/**
1.153 +Defines the types of schedules supported by the task scheduler API
1.154 +@internalAll
1.155 +*/
1.156 +enum TScheduleType
1.157 + {
1.158 + /** Indicates a time based schedule. */
1.159 + ETimeSchedule,
1.160 + /** Indicates a conditon based schedule. */
1.161 + EConditionSchedule
1.162 + };
1.163 +
1.164 +
1.165 +/**
1.166 +Defines a condition which a Publish and Subscribe Uid must satisfy.
1.167 +
1.168 +A condition encapsulates three pieces of information:
1.169 +
1.170 +the UID identifying the P&S variable against which a test is to be made.
1.171 +
1.172 +the value against which that P&S variable is to be tested.
1.173 +
1.174 +the type of test to be made.
1.175 +
1.176 +@see RScheduler::CreatePersistentSchedule
1.177 +@see RScheduler::EditSchedule
1.178 +@see RScheduler::ScheduleTask
1.179 +@see RScheduler::GetScheduleL
1.180 +@see RProperty
1.181 +
1.182 +@internalAll
1.183 +*/
1.184 +class TTaskSchedulerCondition
1.185 + {
1.186 +public:
1.187 + /**
1.188 + An enumeration defining the type of test to be made against
1.189 + a Publish and Subscribe property.
1.190 + */
1.191 + enum TConditionType
1.192 + {
1.193 + /** Tests that a value is equal to a state variable value. */
1.194 + EEquals,
1.195 + /** Tests that a value is unequal to a state variable value. */
1.196 + ENotEquals,
1.197 + /** Tests that a value is greater than a state variable value. */
1.198 + EGreaterThan,
1.199 + /** Tests that a value is less than a state variable value. */
1.200 + ELessThan
1.201 + };
1.202 + inline TTaskSchedulerCondition();
1.203 + inline TTaskSchedulerCondition(TUid aCategory,
1.204 + TUint aKey,
1.205 + TInt aState,
1.206 + TConditionType aType);
1.207 +public:
1.208 + /** P&S category.*/
1.209 + TUid iCategory;
1.210 + /** P&S key.*/
1.211 + TUint iKey;
1.212 + /** Integer state of corresponding P&S variable to be tested against*/
1.213 + TInt iState;
1.214 + /** type of test to be performed */
1.215 + TConditionType iType;
1.216 + };
1.217 +
1.218 +
1.219 +/**
1.220 +Constructs the object with default values.
1.221 +
1.222 +The UID identifying the P&S category against which a test is to be made
1.223 +is set to KNullUid. The sub key is set to zero.
1.224 +
1.225 +The value against which that P&S variable is to be tested is set to zero.
1.226 +
1.227 +The type of test to be made is set to EEquals.
1.228 +*/
1.229 +inline TTaskSchedulerCondition::TTaskSchedulerCondition()
1.230 +: iCategory(KNullUid),
1.231 + iKey(0),
1.232 + iState(0),
1.233 + iType(EEquals)
1.234 + {
1.235 + }
1.236 +
1.237 +/**
1.238 +Constructs the object with the specified values.
1.239 +
1.240 +Note that the RProperty variable identified by the aCategory/aKey pair
1.241 +must be of integer type for this to be a valid task scheduler condition.
1.242 +
1.243 +@param aCategory The publish and subscribe category to be tested.
1.244 +@param aKey The publish and suscribe sub-key to be tested.
1.245 +@param aState The value against which the P&S variable identified by the
1.246 +specified UID is to be tested.
1.247 +@param aType The type of test to be made.
1.248 +
1.249 +@see RProperty
1.250 +*/
1.251 +inline TTaskSchedulerCondition::TTaskSchedulerCondition(TUid aCategory,
1.252 + TUint aKey,
1.253 + TInt aState,
1.254 + TConditionType aType)
1.255 +: iCategory(aCategory),
1.256 + iKey(aKey),
1.257 + iState(aState),
1.258 + iType(aType)
1.259 + {
1.260 + }
1.261 +
1.262 +/**
1.263 +Defines, and uniquely identifies a schedule.
1.264 +
1.265 +@see RScheduler::CreatePersistentSchedule()
1.266 +@see RScheduler::ScheduleTask()
1.267 +@see RScheduler::GetScheduleRefsL()
1.268 +@see RScheduler::GetTaskRefsL()
1.269 +@see RScheduler::GetTaskInfoL()
1.270 +@publishedAll
1.271 +@released
1.272 +*/
1.273 +class TSchedulerItemRef
1.274 + {
1.275 +public:
1.276 + /** The unique Id for the schedule.
1.277 +
1.278 + This is generated by the Task Scheduler when the schedule is created. Clients
1.279 + should use this Id to refer to the schedule in future transactions. */
1.280 + TInt iHandle;
1.281 +
1.282 + /** The name of the schedule.
1.283 +
1.284 + This is defined by the client. */
1.285 + TName iName;
1.286 + };
1.287 +
1.288 +/**
1.289 +Contains detailed information for a single schedule entry.
1.290 +
1.291 +A schedule can have any number of schedule entries. A client passes one or
1.292 +more of these objects, contained within an array, to the RScheduler functions
1.293 +that create or amend a schedule.
1.294 +
1.295 +@see RScheduler::CreatePersistentSchedule()
1.296 +@see RScheduler::EditSchedule()
1.297 +@see RScheduler::ScheduleTask()
1.298 +@see RScheduler::GetScheduleL()
1.299 +@publishedAll
1.300 +@deprecated and replaced by TScheduleEntryInfo2
1.301 +*/
1.302 +class TScheduleEntryInfo
1.303 + {
1.304 +public:
1.305 + void ExternalizeL(RWriteStream& aStream) const;
1.306 + void InternalizeL(RReadStream& aStream);
1.307 +
1.308 + /** Defines the type of time-frame relative to which execution of tasks is timed;
1.309 + for example, EHourly implies relative to the current hour, EDaily implies
1.310 + relative to the current day.
1.311 +
1.312 + @see TIntervalType */
1.313 + TIntervalType iIntervalType;
1.314 +
1.315 + /** The first time that the entry will cause execution of tasks. */
1.316 + TTime iStartTime;
1.317 +
1.318 + /** The interval between execution of tasks.
1.319 +
1.320 + The way that this value is interpreted depends on the value of iIntervalType.
1.321 + For example, if the interval is 2 and iIntervalType has a value of EMonthly,
1.322 + then the interval is 2 months.
1.323 +
1.324 + The interval must have a minimum value of 1.
1.325 +
1.326 + @see TIntervalType
1.327 + @see iIntervalType */
1.328 + TInt iInterval;
1.329 +
1.330 + /** The period for which the entry is valid.
1.331 +
1.332 + After the validity period has expired, tasks associated with the entry will
1.333 + not be eligible for execution.
1.334 +
1.335 + @see TTimeIntervalMinutes */
1.336 + TTimeIntervalMinutes iValidityPeriod;
1.337 + };
1.338 +
1.339 +
1.340 +
1.341 +/**
1.342 +Contains detailed information for a single schedule entry.
1.343 +
1.344 +A schedule can have any number of schedule entries. A client passes one or
1.345 +more of these objects, contained within an array, to the RScheduler functions
1.346 +that create or amend a schedule.
1.347 +
1.348 +@see RScheduler::CreatePersistentSchedule()
1.349 +@see RScheduler::EditSchedule()
1.350 +@see RScheduler::ScheduleTask()
1.351 +@see RScheduler::GetScheduleL()
1.352 +@publishedAll
1.353 +@released
1.354 +*/
1.355 +class TScheduleEntryInfo2
1.356 + {
1.357 +public:
1.358 + //constructors
1.359 + IMPORT_C TScheduleEntryInfo2();
1.360 + IMPORT_C TScheduleEntryInfo2(const TScheduleEntryInfo2& aEntryInfo);
1.361 + IMPORT_C TScheduleEntryInfo2(const TTsTime& aStartTime, TIntervalType aIntervalType, TInt aInterval, TTimeIntervalMinutes aValidityPeriod);
1.362 +
1.363 + //utility Get and Set methods
1.364 + IMPORT_C TIntervalType IntervalType() const;
1.365 + IMPORT_C void SetIntervalType(TIntervalType aIntervalType);
1.366 +
1.367 + IMPORT_C const TTsTime& StartTime() const;
1.368 + IMPORT_C void SetStartTime(const TTsTime& aStartTime);
1.369 +
1.370 + IMPORT_C TInt Interval() const;
1.371 + IMPORT_C void SetInterval(TInt aInterval);
1.372 +
1.373 + IMPORT_C TTimeIntervalMinutes ValidityPeriod() const;
1.374 + IMPORT_C void SetValidityPeriod(TTimeIntervalMinutes aValidityPeriod);
1.375 +
1.376 + //assignment operator
1.377 + IMPORT_C TScheduleEntryInfo2& operator=(const TScheduleEntryInfo2& aEntryInfo);
1.378 +
1.379 +
1.380 +public:
1.381 + // APIs for use within the Task Scheduler server
1.382 + TScheduleEntryInfo2(const TScheduleEntryInfo& aEntryInfo);
1.383 + void ProcessOffsetEvent();
1.384 +
1.385 + void ExternalizeL(RWriteStream& aStream) const;
1.386 + void InternalizeL(RReadStream& aStream);
1.387 +
1.388 +private:
1.389 + /** The interval between execution of tasks.
1.390 + The way that this value is interpreted depends on the value of iIntervalType.
1.391 + For example, if the interval is 2 and iIntervalType has a value of EMonthly,
1.392 + then the interval is 2 months.
1.393 + The interval must have a minimum value of 1.
1.394 + */
1.395 + TInt iInterval;
1.396 +
1.397 + /** Defines the type of interval between the execution of tasks.
1.398 + May be EHourly, EDaily, EMonthly or EYearly.
1.399 + */
1.400 + TIntervalType iIntervalType;
1.401 +
1.402 + /** The first time that the entry will cause execution of tasks. */
1.403 + TTsTime iStartTime;
1.404 +
1.405 + /** The period for which the entry is valid.
1.406 + After the validity period has expired, tasks associated with the entry will
1.407 + not be eligible for execution.
1.408 + */
1.409 + TTimeIntervalMinutes iValidityPeriod;
1.410 +
1.411 + /** For future use
1.412 + */
1.413 + TAny* iReserved;
1.414 +
1.415 + // Declare the test accessor as a friend
1.416 + friend class TScheduleEntryInfo2_StateAccessor;
1.417 + };
1.418 +
1.419 +
1.420 +/**
1.421 +Defines the state of a schedule.
1.422 +
1.423 +An object of this type is passed to, and populated by, a call to RScheduler::GetScheduleL().
1.424 +
1.425 +@see RScheduler::GetScheduleL()
1.426 +@publishedAll
1.427 +@released
1.428 +*/
1.429 +class TScheduleState2
1.430 + {
1.431 +public:
1.432 +
1.433 + //constructors
1.434 + IMPORT_C TScheduleState2();
1.435 + IMPORT_C TScheduleState2(const TScheduleState2& aScheduleState);
1.436 + IMPORT_C TScheduleState2(const TName& aName, const TTsTime& aDueTime, TBool aPersists, TBool aEnabled);
1.437 +
1.438 + //get, set methods
1.439 + IMPORT_C const TName& Name() const;
1.440 + IMPORT_C void SetName(const TName& aName);
1.441 +
1.442 + IMPORT_C const TTsTime& DueTime() const;
1.443 + IMPORT_C void SetDueTime(const TTsTime& aDueTime);
1.444 +
1.445 + IMPORT_C TBool Persists() const;
1.446 + IMPORT_C void SetPersists(TBool aPersists);
1.447 +
1.448 + IMPORT_C TBool Enabled() const;
1.449 + IMPORT_C void SetEnabled(TBool aEnabled);
1.450 +
1.451 + IMPORT_C TScheduleState2& operator=(const TScheduleState2& aScheduleState);
1.452 +
1.453 +private:
1.454 + /** The name of the schedule. */
1.455 + TName iName;
1.456 +
1.457 + /** The time when the schedule is next due.
1.458 + This only has meaning if the schedule is pending, i.e. it is enabled and has
1.459 + tasks associated with it. */
1.460 + TTsTime iDueTime;
1.461 +
1.462 + /** Flags used to indicate:
1.463 + 1. Whether the schedule is enabled or not. (bit 0)
1.464 + 2. Whether the schedule is persistent or not. (bit 1)
1.465 + If a schedule is persistent, its lifetime is not limited to the lifetime of
1.466 + the tasks associated with it .
1.467 + If a schedule is transient, it is created together with a new scheduled task,
1.468 + and is destroyed when the task is destroyed.
1.469 +
1.470 + Bits 2-31 reserved for future use
1.471 + */
1.472 + TUint32 iFlags;
1.473 +
1.474 + /** For future use
1.475 + */
1.476 + TAny* iReserved;
1.477 +
1.478 + // Declare the test accessor as a friend
1.479 + friend class TScheduleState2_StateAccessor;
1.480 + };
1.481 +
1.482 +/**
1.483 +Defines the state of a schedule.
1.484 +
1.485 +An object of this type is passed to, and populated by, a call to RScheduler::GetScheduleL().
1.486 +
1.487 +@see RScheduler::GetScheduleL()
1.488 +@publishedAll
1.489 +@deprecated and replaced by TScheduleState2.
1.490 +*/
1.491 +class TScheduleState
1.492 + {
1.493 +public:
1.494 + //constructor for use with the deprecated APIs
1.495 + TScheduleState(const TScheduleState2& aScheduleState2);
1.496 + TScheduleState()
1.497 + {
1.498 + }
1.499 +
1.500 + /** The name of the schedule. */
1.501 + TName iName;
1.502 +
1.503 + /** The time when the schedule is next due.
1.504 +
1.505 + This only has meaning if the schedule is pending, i.e. it is enabled and has
1.506 + tasks associated with it. */
1.507 + TTime iDueTime;
1.508 +
1.509 + /** Indicates whether the schedule is persistent or not.
1.510 +
1.511 + If a schedule is persistent, its lifetime is not limited to the lifetime of
1.512 + the tasks associated with it .
1.513 +
1.514 + If a schedule is transient, it is created together with a new scheduled task,
1.515 + and is destroyed when the task is destroyed. */
1.516 + TBool iPersists;
1.517 +
1.518 + /** Indicates whether the schedule is enabled or not. */
1.519 + TBool iEnabled;
1.520 + };
1.521 +
1.522 +/**
1.523 +@internalComponent
1.524 +*/
1.525 +class TScheduleInfo // Move to cschcode.h when appropriate
1.526 + {
1.527 +public:
1.528 + TScheduleState2 iState;
1.529 + TInt iEntryCount;
1.530 + TInt iTaskCount;
1.531 + };
1.532 +
1.533 +/**
1.534 +@internalAll
1.535 +@deprecated replaced with TScheduleSettings2
1.536 +*/
1.537 +class TScheduleSettings // Move to cschcode.h when appropriate
1.538 + {
1.539 +public:
1.540 + TBool iPersists;
1.541 + TInt iEntryCount;
1.542 + };
1.543 +
1.544 +#endif