1 schinfo.h

     1 // Copyright (c) 2004-2009 Nokia Corporation and/or its subsidiary(-ies).

     2 // All rights reserved.

     3 // This component and the accompanying materials are made available

     4 // 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

     5 // which accompanies this distribution, and is available

     6 // at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".

     7 //

     8 // Initial Contributors:

     9 // Nokia Corporation - initial contribution.

    10 //

    11 // Contributors:

    12 //

    13 // Description:

    14 // Various T-classes for client input to scheduler, scheduler output to client	

    15 // These classes comprise part of the interface (the rest is defined in RScheduler)

    16 // 

    17 //

    18 

    19 #if !defined (__SCHINFO_H__)

    20 #define __SCHINFO_H__

    21 

    22 #if !defined (__SCHTIME_H__)

    23 #include <schtime.h>

    24 #endif

    25 

    26 #if !defined(__E32BASE_H__)

    27 #include <e32base.h>

    28 #endif

    29 

    30 #include <s32strm.h>

    31 

    32 /** 

    33 Contains detailed information for a single task.

    34 

    35 A schedule can have any number of tasks. An object of this type is passed 

    36 to RScheduler::ScheduleTask(). Objects of this type are also returned by functions 

    37 within RScheduler that retrieve information about tasks.

    38 

    39 @see RScheduler::ScheduleTask()

    40 @see RScheduler::GetScheduleL()

    41 @see RScheduler::GetTaskInfoL() 

    42 @publishedAll

    43 @released

    44 */

    45 class TTaskInfo

    46 	{

    47 public:

    48 	//ctors

    49 	IMPORT_C TTaskInfo (TInt aTaskId, TName& aName, TInt aPriority, TInt aRepeat);

    50 	IMPORT_C TTaskInfo();//

    51 	//assignment

    52 	IMPORT_C TTaskInfo& operator=(const TTaskInfo& aTaskInfo);

    53 	IMPORT_C void ExternalizeL(RWriteStream& aStream) const;

    54 	IMPORT_C void InternalizeL(RReadStream& aStream);

    55 	//needs a copy ctor

    56 	//TTaskInfo (TTaskInfo& aTaskInfo);

    57 	

    58 	//data

    59 	/** Specifies how often the task is to be repeated.

    60 	

    61 	This is defined by the client.

    62 	

    63 	A value of 1 means once, a value of 2 means twice etc.

    64 	

    65 	Note that zero is interpreted to mean once, and a negative value is interpreted 

    66 	to mean that the task will be repeated until it is explicitly deleted. */

    67 	TInt iRepeat;

    68 	

    69 	/** The unique Id for the task.

    70 	

    71 	This is generated by the Task Scheduler. Clients should use the generated 

    72 	Id to refer to the task in future transactions. */

    73 	TInt iTaskId;

    74 	

    75 	/** The name of the task.

    76 	

    77 	This is defined by the client.

    78 	

    79 	@see TName */

    80 	TName iName;

    81 	

    82 	/** The priority of the task.

    83 	

    84 	This is defined by the client.

    85 	

    86 	Determines the order in which a client's tasks are executed. Where a client 

    87 	has two tasks with different priorities, the task with the higher priority 

    88 	will be executed first. */

    89 	TInt iPriority;

    90 	};

    91 

    92 /** 

    93 Defines a filter to be used when listing tasks scheduled in a call to RScheduler::GetTaskRefsL().

    94 

    95 @see RScheduler::GetTaskRefsL()

    96 @publishedAll

    97 @released

    98 */

    99 enum TTaskFilter

   100 	{

   101 	/** Indicates that all tasks are to be selected. */

   102 	EAllTasks,

   103 	/** Indicates those tasks associated with the executing program with which the 

   104 	calling client is associated, are to be selected. */

   105 	EMyTasks

   106 	};

   107 

   108 

   109 /** 

   110 Defines a filter to be used when listing schedules in a call to RScheduler::GetScheduleRefsL(), 

   111 and when listing tasks in a call to RScheduler::GetTaskRefsL().

   112 

   113 @see RScheduler::GetScheduleRefsL()

   114 @see RScheduler::GetTaskRefsL() 

   115 @publishedAll

   116 @released

   117 */

   118 enum TScheduleFilter

   119 	{

   120 	/** Indicates that all schedules are to be selected. */

   121 	EAllSchedules,

   122 	/** Indicates that only pending schedules are to be selected.

   123 	

   124 	Note that pending schedules are those that are enabled and have tasks associated 

   125 	with them. */

   126 	EPendingSchedules

   127 	};

   128 

   129 /** 

   130 Defines the type of interval used by a schedule entry.

   131 

   132 @see TScheduleEntryInfo

   133 @publishedAll

   134 @released

   135 */

   136 enum TIntervalType

   137 	{

   138 	/** The interval is based on hours. */

   139 	EHourly,

   140 	/** The interval is based on days. */

   141 	EDaily,

   142 	/** The interval is based on months. */

   143 	EMonthly,

   144 	/** The interval is based on years. */

   145 	EYearly

   146 	};

   147 

   148 /**

   149 Defines the types of schedules supported by the task scheduler API

   150 @internalAll

   151 */

   152 enum TScheduleType

   153 	{

   154 	/** Indicates a time based schedule. */

   155 	ETimeSchedule,

   156 	/** Indicates a conditon based schedule. */

   157 	EConditionSchedule

   158 	};

   159 

   160 

   161 /** 

   162 Defines a condition which a Publish and Subscribe Uid must satisfy.

   163 

   164 A condition encapsulates three pieces of information:

   165 

   166 the UID identifying the P&S variable against which a test is to be made.

   167 

   168 the value against which that P&S variable is to be tested.

   169 

   170 the type of test to be made.

   171 

   172 @see RScheduler::CreatePersistentSchedule

   173 @see RScheduler::EditSchedule

   174 @see RScheduler::ScheduleTask

   175 @see RScheduler::GetScheduleL

   176 @see RProperty

   177 

   178 @internalAll

   179 */

   180 class TTaskSchedulerCondition

   181 	{

   182 public:

   183 	/** 

   184 	An enumeration defining the type of test to be made against 

   185 	a Publish and Subscribe property. 

   186 	*/

   187 	enum TConditionType

   188 		{

   189 		/** Tests that a value is equal to a state variable value. */

   190 		EEquals,		

   191 		/** Tests that a value is unequal to a state variable value. */

   192 		ENotEquals,		

   193 		/** Tests that a value is greater than a state variable value. */

   194 		EGreaterThan,	

   195 		/** Tests that a value is less than a state variable value. */

   196 		ELessThan		

   197 		};

   198 	inline TTaskSchedulerCondition();

   199 	inline TTaskSchedulerCondition(TUid aCategory,

   200 								TUint aKey, 

   201 								TInt aState, 

   202 								TConditionType aType);

   203 public:

   204 	/** P&S category.*/

   205 	TUid iCategory;

   206 	/** P&S key.*/

   207 	TUint iKey;

   208 	/** Integer state of corresponding P&S variable to be tested against*/

   209 	TInt iState;

   210 	/** type of test to be performed */

   211 	TConditionType iType;

   212 	};

   213 

   214 

   215 /** 

   216 Constructs the object with default values.

   217 

   218 The UID identifying the P&S category against which a test is to be made 

   219 is set to KNullUid.  The sub key is set to zero.

   220 

   221 The value against which that P&S variable is to be tested is set to zero.

   222 

   223 The type of test to be made is set to EEquals. 

   224 */

   225 inline TTaskSchedulerCondition::TTaskSchedulerCondition()

   226 :	iCategory(KNullUid), 

   227 	iKey(0),

   228 	iState(0), 

   229 	iType(EEquals)

   230 	{

   231 	}

   232 

   233 /** 

   234 Constructs the object with the specified values.

   235 

   236 Note that the RProperty variable identified by the aCategory/aKey pair 

   237 must be of integer type for this to be a valid task scheduler condition.

   238 

   239 @param aCategory The publish and subscribe category to be tested.

   240 @param aKey The publish and suscribe sub-key to be tested.

   241 @param aState The value against which the P&S variable identified by the 

   242 specified UID is to be tested. 

   243 @param aType The type of test to be made. 

   244 

   245 @see RProperty

   246 */

   247 inline TTaskSchedulerCondition::TTaskSchedulerCondition(TUid aCategory,

   248 										TUint aKey, 

   249 										TInt aState, 

   250 										TConditionType aType)

   251 :	iCategory(aCategory),

   252 	iKey(aKey), 

   253 	iState(aState), 

   254 	iType(aType)

   255 	{

   256 	}

   257 	

   258 /** 

   259 Defines, and uniquely identifies a schedule.

   260 

   261 @see RScheduler::CreatePersistentSchedule()

   262 @see RScheduler::ScheduleTask()

   263 @see RScheduler::GetScheduleRefsL()

   264 @see RScheduler::GetTaskRefsL()

   265 @see RScheduler::GetTaskInfoL()

   266 @publishedAll

   267 @released

   268 */

   269 class TSchedulerItemRef

   270 	{

   271 public:

   272 	/** The unique Id for the schedule.

   273 	

   274 	This is generated by the Task Scheduler when the schedule is created. Clients 

   275 	should use this Id to refer to the schedule in future transactions. */

   276 	TInt iHandle;

   277 	

   278 	/** The name of the schedule.

   279 	

   280 	This is defined by the client. */

   281 	TName iName;

   282 	};

   283 

   284 /** 

   285 Contains detailed information for a single schedule entry.

   286 

   287 A schedule can have any number of schedule entries. A client passes one or 

   288 more of these objects, contained within an array, to the RScheduler functions 

   289 that create or amend a schedule.

   290 

   291 @see RScheduler::CreatePersistentSchedule()

   292 @see RScheduler::EditSchedule()

   293 @see RScheduler::ScheduleTask()

   294 @see RScheduler::GetScheduleL() 

   295 @publishedAll

   296 @deprecated and replaced by TScheduleEntryInfo2

   297 */

   298 class TScheduleEntryInfo

   299 	{

   300 public:

   301 	void ExternalizeL(RWriteStream& aStream) const;

   302 	void InternalizeL(RReadStream& aStream);

   303 

   304 	/** Defines the type of time-frame relative to which execution of tasks is timed; 

   305 	for example, EHourly implies relative to the current hour, EDaily implies 

   306 	relative to the current day.

   307 	

   308 	@see TIntervalType */

   309 	TIntervalType iIntervalType;

   310 	

   311 	/** The first time that the entry will cause execution of tasks. */

   312 	TTime iStartTime;

   313 	

   314 	/** The interval between execution of tasks.

   315 	

   316 	The way that this value is interpreted depends on the value of iIntervalType. 

   317 	For example, if the interval is 2 and iIntervalType has a value of EMonthly, 

   318 	then the interval is 2 months.

   319 	

   320 	The interval must have a minimum value of 1.

   321 	

   322 	@see TIntervalType

   323 	@see iIntervalType */

   324 	TInt iInterval;

   325 	

   326 	/** The period for which the entry is valid.

   327 	

   328 	After the validity period has expired, tasks associated with the entry will 

   329 	not be eligible for execution.

   330 	

   331 	@see TTimeIntervalMinutes */

   332 	TTimeIntervalMinutes iValidityPeriod;

   333 	};

   334 	

   335 	

   336 	

   337 /** 

   338 Contains detailed information for a single schedule entry.

   339 

   340 A schedule can have any number of schedule entries. A client passes one or 

   341 more of these objects, contained within an array, to the RScheduler functions 

   342 that create or amend a schedule.

   343 

   344 @see RScheduler::CreatePersistentSchedule()

   345 @see RScheduler::EditSchedule()

   346 @see RScheduler::ScheduleTask()

   347 @see RScheduler::GetScheduleL() 

   348 @publishedAll

   349 @released

   350 */

   351 class TScheduleEntryInfo2

   352 	{

   353 public:

   354 	//constructors

   355 	IMPORT_C TScheduleEntryInfo2();

   356 	IMPORT_C TScheduleEntryInfo2(const TScheduleEntryInfo2& aEntryInfo);

   357 	IMPORT_C TScheduleEntryInfo2(const TTsTime& aStartTime, TIntervalType aIntervalType, TInt aInterval, TTimeIntervalMinutes aValidityPeriod);

   358 	 

   359 	//utility Get and Set methods

   360 	IMPORT_C TIntervalType IntervalType() const;

   361 	IMPORT_C void SetIntervalType(TIntervalType aIntervalType);

   362 

   363 	IMPORT_C const TTsTime& StartTime() const;

   364 	IMPORT_C void SetStartTime(const TTsTime& aStartTime);

   365 

   366 	IMPORT_C TInt Interval() const;

   367 	IMPORT_C void SetInterval(TInt aInterval);

   368 

   369 	IMPORT_C TTimeIntervalMinutes ValidityPeriod() const;

   370 	IMPORT_C void SetValidityPeriod(TTimeIntervalMinutes aValidityPeriod);

   371 

   372 	//assignment operator	

   373 	IMPORT_C TScheduleEntryInfo2& operator=(const TScheduleEntryInfo2& aEntryInfo);

   374 

   375 

   376 public:

   377 	// APIs for use within the Task Scheduler server

   378 	TScheduleEntryInfo2(const TScheduleEntryInfo& aEntryInfo);

   379 	void ProcessOffsetEvent();

   380 

   381 	void ExternalizeL(RWriteStream& aStream) const;

   382 	void InternalizeL(RReadStream& aStream);

   383 

   384 private:

   385 	/** The interval between execution of tasks.

   386 	The way that this value is interpreted depends on the value of iIntervalType. 

   387 	For example, if the interval is 2 and iIntervalType has a value of EMonthly, 

   388 	then the interval is 2 months.

   389 	The interval must have a minimum value of 1.

   390 	 */

   391 	TInt iInterval;

   392 	

   393 	/** Defines the type of interval between the execution of tasks. 

   394 	May be EHourly, EDaily, EMonthly or EYearly.

   395 	 */

   396 	TIntervalType iIntervalType;

   397 	

   398 	/** The first time that the entry will cause execution of tasks. */

   399 	TTsTime iStartTime;

   400 	

   401 	/** The period for which the entry is valid.

   402 	After the validity period has expired, tasks associated with the entry will 

   403 	not be eligible for execution.

   404 	*/

   405 	TTimeIntervalMinutes iValidityPeriod;

   406 

   407 	/** For future use

   408 	*/

   409 	TAny* iReserved;	

   410 	

   411 	// Declare the test accessor as a friend

   412 	friend class TScheduleEntryInfo2_StateAccessor;

   413 	};

   414 

   415 

   416 /** 

   417 Defines the state of a schedule.

   418 

   419 An object of this type is passed to, and populated by, a call to RScheduler::GetScheduleL().

   420 

   421 @see RScheduler::GetScheduleL()

   422 @publishedAll

   423 @released

   424 */

   425 class TScheduleState2

   426 	{

   427 public:

   428 

   429 	//constructors

   430 	IMPORT_C TScheduleState2();

   431 	IMPORT_C TScheduleState2(const TScheduleState2& aScheduleState);

   432 	IMPORT_C TScheduleState2(const TName& aName, const TTsTime& aDueTime, TBool aPersists, TBool aEnabled);

   433 		

   434 	//get, set methods

   435 	IMPORT_C const TName& Name() const;

   436 	IMPORT_C void SetName(const TName& aName);

   437 

   438 	IMPORT_C const TTsTime& DueTime() const;

   439 	IMPORT_C void SetDueTime(const TTsTime& aDueTime);

   440 

   441 	IMPORT_C TBool Persists() const;

   442 	IMPORT_C void SetPersists(TBool aPersists);

   443 

   444 	IMPORT_C TBool Enabled() const;

   445 	IMPORT_C void SetEnabled(TBool aEnabled);

   446 	

   447 	IMPORT_C TScheduleState2& operator=(const TScheduleState2& aScheduleState);

   448 

   449 private:

   450 	/** The name of the schedule. */

   451 	TName iName;

   452 	

   453 	/** The time when the schedule is next due.

   454 	This only has meaning if the schedule is pending, i.e. it is enabled and has 

   455 	tasks associated with it. */

   456 	TTsTime iDueTime;

   457 	

   458 	/** Flags used to indicate:

   459 	1.  Whether the schedule is enabled or not. (bit 0)

   460 	2.	Whether the schedule is persistent or not. (bit 1)

   461 		If a schedule is persistent, its lifetime is not limited to the lifetime of 

   462 		the tasks associated with it .

   463 		If a schedule is transient, it is created together with a new scheduled task, 

   464 		and is destroyed when the task is destroyed.

   465 		

   466 		Bits 2-31 reserved for future use

   467 	*/

   468 	TUint32 iFlags;

   469 	

   470 	/** For future use

   471 	*/

   472 	TAny* iReserved;

   473 	

   474 	// Declare the test accessor as a friend

   475 	friend class TScheduleState2_StateAccessor;

   476 	};

   477 

   478 /** 

   479 Defines the state of a schedule.

   480 

   481 An object of this type is passed to, and populated by, a call to RScheduler::GetScheduleL().

   482 

   483 @see RScheduler::GetScheduleL()

   484 @publishedAll

   485 @deprecated and replaced by TScheduleState2.

   486 */

   487 class TScheduleState

   488 	{

   489 public:

   490 	//constructor for use with the deprecated APIs

   491 	TScheduleState(const TScheduleState2& aScheduleState2);

   492 	TScheduleState()

   493 		{		

   494 		}

   495 	

   496 	/** The name of the schedule. */

   497 	TName iName;

   498 	

   499 	/** The time when the schedule is next due.

   500 	

   501 	This only has meaning if the schedule is pending, i.e. it is enabled and has 

   502 	tasks associated with it. */

   503 	TTime iDueTime;

   504 	

   505 	/** Indicates whether the schedule is persistent or not.

   506 	

   507 	If a schedule is persistent, its lifetime is not limited to the lifetime of 

   508 	the tasks associated with it .

   509 	

   510 	If a schedule is transient, it is created together with a new scheduled task, 

   511 	and is destroyed when the task is destroyed. */

   512 	TBool iPersists;

   513 	

   514 	/** Indicates whether the schedule is enabled or not. */

   515 	TBool iEnabled;

   516 	};

   517 

   518 /**

   519 @internalComponent

   520 */

   521 class TScheduleInfo // Move to cschcode.h when appropriate

   522 	{

   523 public:

   524 	TScheduleState2 iState;

   525 	TInt iEntryCount;

   526 	TInt iTaskCount;

   527 	};

   528 

   529 /**

   530 @internalAll

   531 @deprecated replaced with TScheduleSettings2

   532 */

   533 class TScheduleSettings // Move to cschcode.h when appropriate

   534 	{

   535 public:

   536 	TBool iPersists;

   537 	TInt iEntryCount;

   538 	};

   539 

   540 #endif