sl@0: // Copyright (c) 2004-2009 Nokia Corporation and/or its subsidiary(-ies).
sl@0: // All rights reserved.
sl@0: // This component and the accompanying materials are made available
sl@0: // under the terms of "Eclipse Public License v1.0"
sl@0: // which accompanies this distribution, and is available
sl@0: // at the URL "http://www.eclipse.org/legal/epl-v10.html".
sl@0: //
sl@0: // Initial Contributors:
sl@0: // Nokia Corporation - initial contribution.
sl@0: //
sl@0: // Contributors:
sl@0: //
sl@0: // Description:
sl@0: // Implements RScheduler functions: client-side session with the task scheduler
sl@0: // 
sl@0: //
sl@0: 
sl@0: #include "CSCH_CLI.H"	//definition of RScheduler
sl@0: #include "CSCHCODE.H"	//opcodes
sl@0: #include "SCHEXE.H"
sl@0: #include <schinfointernal.h>
sl@0: 
sl@0: /** Default constructor. */
sl@0: EXPORT_C RScheduler::RScheduler()
sl@0:     {
sl@0:     }
sl@0: 
sl@0: /** 
sl@0: Connects a client to the Task Scheduler server, creating a session with that 
sl@0: server.
sl@0: 
sl@0: @return KErrNone, if successful; otherwise one of the other system wide error 
sl@0: codes. 
sl@0: */
sl@0: EXPORT_C TInt RScheduler::Connect()
sl@0: 	{
sl@0: 	TInt r=CreateSession(KSchSvrName, Version(),0);
sl@0: 	if (r==KErrNotFound)
sl@0: 		{
sl@0: 		r=StartSch32();
sl@0: 		if (r!=KErrNone)
sl@0: 			return r;
sl@0: 		r=CreateSession(KSchSvrName, Version(),0);
sl@0: 	    }
sl@0: 	return(r); 
sl@0: 	}
sl@0: 	
sl@0: /** 
sl@0: Gets the client side version number.
sl@0: 
sl@0: @return The version number. 
sl@0: */
sl@0: EXPORT_C TVersion RScheduler::Version() const
sl@0: 	{
sl@0: 	return(TVersion(KESchMajorVersionNumber,KESchMinorVersionNumber,KESchBuildVersionNumber));
sl@0: 	}
sl@0: 
sl@0: /** 
sl@0: Registers a client with the Task Scheduler.
sl@0: 
sl@0: A client must register with the Task Scheduler before scheduling any tasks, 
sl@0: but does not need to register just to create and edit schedules.
sl@0: 
sl@0: @param aFileName The name and full path of a program that encapsulates the 
sl@0: client-specific knowledge for implementing tasks. On the emulator, the program 
sl@0: should be a DLL; on an ARM processor, it should be an executable.
sl@0: @param aPriority A priority value.
sl@0: @return KErrNone, if successful; otherwise one of the other system wide error 
sl@0: codes. 
sl@0: */
sl@0: EXPORT_C TInt RScheduler::Register(const TFileName& aFileName,const TInt aPriority)
sl@0: 	{
sl@0: 	return SendReceive(ERegisterClient,TIpcArgs(&aFileName,aPriority));
sl@0: 	}
sl@0: 
sl@0: /** 
sl@0: Creates a persistent time based schedule.
sl@0: 
sl@0: This schedule has no tasks associated with it but merely contains information
sl@0: about start and finish times.
sl@0: 
sl@0: @capability WriteDeviceData
sl@0: @param aRef Definition of the new schedule.  On return this contains a valid
sl@0: handle to the newly created schedule.
sl@0: @param aEntryList The set of schedule entries that make up the new schedule.
sl@0: @return KErrNone, if successful, KErrArgument if the condition array is 
sl@0: empty, or an entry has an interval less than 1, KErrServerBusy, if a backup or 
sl@0: restore operation is taking place, KErrPermissionDenied if the client 
sl@0: does not have WriteDeviceData capability. 
sl@0: Otherwise one of the other system wide error codes.
sl@0: @see TScheduleEntryInfo2
sl@0: */
sl@0: EXPORT_C TInt RScheduler::CreatePersistentSchedule(TSchedulerItemRef& aRef, 
sl@0: 							const CArrayFixFlat<TScheduleEntryInfo2>& aEntryList)
sl@0: 	{
sl@0: 	TScheduleSettings2 settings;
sl@0: 	settings.iPersists = ETrue;
sl@0: 	settings.iEntryCount = aEntryList.Count();
sl@0: 	settings.iName = aRef.iName;
sl@0: 	return CreateSchedule(aRef, aEntryList, settings);
sl@0: 	}
sl@0: 
sl@0: /** 
sl@0: Creates a persistent condition based schedule.
sl@0: 
sl@0: This schedule has no tasks associated with it but merely contains information
sl@0: about conditions that must be satified to complete this schedule.
sl@0: 
sl@0: @capability WriteDeviceData
sl@0: @param aRef Definition of the new schedule.  On return this contains a valid
sl@0: handle to the newly created schedule.
sl@0: @param aConditions An array of system agent conditons 
sl@0: that make up the schedule.
sl@0: @param aDefaultRunTime The time at which the schedule with run if no
sl@0: conditions are met. If this is a local time based value, the schedule will remain
sl@0: at that local time regardless of timezone and DST changes (ie. it will float)
sl@0: If the value is UTC based, the schedule will remain at that UTC time (will not float).
sl@0: @return KErrNone, if successful, KErrArgument if the condition array is 
sl@0: empty or if the publish and subscribe variables have an invalid category, 
sl@0: KErrServerBusy, if a backup or restore operation is taking place,
sl@0: KErrPermissionDenied if the client does not have WriteDeviceData capability. 
sl@0: Otherwise one of the other system wide error codes.
sl@0: @see TTaskSchedulerCondition 
sl@0: @internalAll
sl@0: */
sl@0: EXPORT_C TInt RScheduler::CreatePersistentSchedule(TSchedulerItemRef& aRef, 
sl@0: 							const CArrayFixFlat<TTaskSchedulerCondition>& aConditions,
sl@0: 							const TTsTime& aDefaultRunTime)
sl@0: 	{
sl@0: 	TScheduleSettings2 settings;
sl@0: 	settings.iPersists = ETrue;
sl@0: 	settings.iEntryCount = aConditions.Count();
sl@0: 	settings.iName = aRef.iName;
sl@0: 	return CreateSchedule(aRef, aConditions, aDefaultRunTime, settings);	
sl@0: 	}
sl@0: 
sl@0: static TBool ScheduleEntriesAreBad(const CArrayFixFlat<TScheduleEntryInfo2>& aEntries)
sl@0: 	{//must have at least 1 entry, each entry's interval must be at least 1
sl@0: 	TInt count = aEntries.Count();
sl@0: 	if (count==0)
sl@0: 		return ETrue;
sl@0: 	for (TInt i=0; i < count; i++)
sl@0: 		{
sl@0: 		const TScheduleEntryInfo2* entry = &(aEntries.At(i));
sl@0: 		if (entry->Interval() < 1)
sl@0: 			return ETrue;
sl@0: 		}
sl@0: 	return EFalse;
sl@0: 	}
sl@0: 
sl@0: TInt RScheduler::CreateSchedule(TSchedulerItemRef& aRef, 
sl@0: 			const CArrayFixFlat<TScheduleEntryInfo2>& aEntryList, 
sl@0: 			const TScheduleSettings2& aSettings)
sl@0: 	{//check critical aspects of input here (client-side)
sl@0: 	if (ScheduleEntriesAreBad(aEntryList))
sl@0: 		return KErrArgument;
sl@0: 	
sl@0: 	//write settings (entry count + persists flag + name)
sl@0: 	TPckgC<TScheduleSettings2> pSettings(aSettings);
sl@0: 	//write entries
sl@0: 	TPtrC8 pA((TUint8*)&aEntryList.At(0), sizeof(TScheduleEntryInfo2)*aSettings.iEntryCount); 
sl@0: 	
sl@0: 	//read back generated ID
sl@0: 	TPckg<TInt> id(aRef.iHandle);
sl@0: 	return SendReceive(ECreateTimeSchedule, TIpcArgs(&pSettings, &pA, &id));
sl@0: 	}
sl@0: 	
sl@0: static TBool ScheduleEntriesAreBad(const CArrayFixFlat<TTaskSchedulerCondition>& aConditions)
sl@0: 	{//must have at least 1 condition in array. The category for a condition cannot be KNullUid.
sl@0: 	TInt count = aConditions.Count();
sl@0: 	if (count==0)
sl@0: 		return ETrue;
sl@0: 	for (TInt i=0; i < count; i++)
sl@0: 		{
sl@0: 		const TTaskSchedulerCondition* entry = &(aConditions.At(i));
sl@0: 		if (entry->iCategory == KNullUid)
sl@0: 			return ETrue;
sl@0: 		}
sl@0: 	return EFalse;
sl@0: 	}
sl@0: 
sl@0: TInt RScheduler::CreateSchedule(TSchedulerItemRef& aRef, 
sl@0: 			const CArrayFixFlat<TTaskSchedulerCondition>& aConditions,
sl@0: 			const TTsTime& aDefaultRunTime, 
sl@0: 			const TScheduleSettings2& aSettings)
sl@0: 	{//check critical aspects of input here (client-side)
sl@0: 	if (ScheduleEntriesAreBad(aConditions))
sl@0: 		return KErrArgument;
sl@0: 	
sl@0: 	//write settings (entry count + persists flag + name)
sl@0: 	TPckgC<TScheduleSettings2> pSettings(aSettings);
sl@0: 	//write entries
sl@0: 	TPtrC8 pA((TUint8*)&aConditions.At(0), sizeof(TTaskSchedulerCondition)*aSettings.iEntryCount); 
sl@0: 	//write Time
sl@0: 	TPckgC<TTsTime> pTime(aDefaultRunTime);
sl@0: 	
sl@0: 	//read back generated ID
sl@0: 	TPckg<TInt> id(aRef.iHandle);
sl@0: 	return SendReceive(ECreateConditionSchedule, TIpcArgs(&pSettings, &pA, &pTime, &id));
sl@0: 	}
sl@0: 
sl@0: /** 
sl@0: Changes a time based schedule.
sl@0: 
sl@0: Note that changing a schedule is implemented by supplying a replacement set 
sl@0: of schedule entries.
sl@0: 
sl@0: @capability Note Only clients with the same SID as the schedule creator, or 
sl@0: WriteDeviceData capability can sucessfully call this API.
sl@0: 
sl@0: @param aScheduleHandle The Id that identifies the schedule.
sl@0: @param aEntryList The set of schedule entries that will make up the new schedule.
sl@0: @return KErrNone if successful, KErrNotFound if there is no schedule with 
sl@0: the specified Id, KErrArgument if the schedule is not a time based one, 
sl@0: KErrPermissionDenied if the client does not have the same SID as the schedules
sl@0: creator or has WriteDeviceData capability, KErrServerBusy, if a backup or 
sl@0: restore operation is taking place or any of the other system wide error 
sl@0: codes.
sl@0: @see TScheduleEntryInfo2
sl@0: */
sl@0: EXPORT_C TInt RScheduler::EditSchedule(const TInt aScheduleHandle, const CArrayFixFlat<TScheduleEntryInfo2>& aEntryList)
sl@0: 	{
sl@0: 	if (ScheduleEntriesAreBad(aEntryList))
sl@0: 		return KErrArgument;
sl@0: 	TInt count = aEntryList.Count();
sl@0: 	TPtrC8 pA((TUint8*) &aEntryList.At(0), sizeof(TScheduleEntryInfo2)*count);
sl@0: 	return SendReceive(EEditTimeSchedule, TIpcArgs(count, aScheduleHandle, &pA));
sl@0: 	}
sl@0: 
sl@0: /** 
sl@0: Changes a condition based schedule.
sl@0: 
sl@0: Note that changing a schedule is implemented by supplying a replacement set 
sl@0: of schedule conditons and time.
sl@0: 
sl@0: @capability Note Only clients with the same SID as the schedule creator, or 
sl@0: WriteDeviceData capability can sucessfully call this API.
sl@0: 
sl@0: @param aScheduleHandle The Id that identifies the schedule.
sl@0: @param aConditions An array of system agent conditons 
sl@0: that make up the schedule.
sl@0: @param aDefaultRunTime The time at which the schedule with run if no
sl@0: conditions are met. If this is a local time based value, the schedule will remain
sl@0: at that local time regardless of timezone and DST changes (ie. it will float)
sl@0: If the value is UTC based, the schedule will remain at that UTC time (will not float).
sl@0: @return KErrNone if successful, KErrNotFound if there is no schedule with 
sl@0: the specified Id, KErrArgument if the schedule is not a condition based one
sl@0: or if the publish and subscribe variables, defined by aConditions category 
sl@0: and key values, do not exist or are not of integral type, 
sl@0: KErrPermissionDenied if the client does not have the same SID as the schedules
sl@0: creator or has WriteDeviceData capability, KErrServerBusy, if a backup or 
sl@0: restore operation is taking place, or any of the other system wide error 
sl@0: codes.
sl@0: 
sl@0: @internalAll
sl@0: */	
sl@0: EXPORT_C TInt RScheduler::EditSchedule(TInt aScheduleHandle, 
sl@0: 						const CArrayFixFlat<TTaskSchedulerCondition>& aConditions,
sl@0: 						const TTsTime& aDefaultRunTime)
sl@0: 	{
sl@0: 	TInt count = aConditions.Count();
sl@0: 	TPtrC8 pA((TUint8*) &aConditions.At(0), sizeof(TTaskSchedulerCondition)*count);
sl@0: 	//write Time
sl@0: 	TPckgC<TTsTime> pTime(aDefaultRunTime);
sl@0: 	return SendReceive(EEditConditionSchedule, TIpcArgs(count, aScheduleHandle, &pA, &pTime));	
sl@0: 	}
sl@0: 
sl@0: 
sl@0: /** 
sl@0: Deletes the specified schedule.
sl@0: 
sl@0: @capability Note Only clients with the same SID as the schedule creator, or 
sl@0: WriteDeviceData capability can sucessfully call this API.
sl@0: 
sl@0: Note that a schedule cannot be deleted if there are tasks associated with 
sl@0: it; the tasks must be explicitly deleted first.
sl@0: 
sl@0: @param aScheduleHandle The Id that identifies the schedule.
sl@0: @return KErrNone if successful, KErrNotFound if there is no schedule with 
sl@0: the specified Id, KErrArgument if there are outstanding tasks associated with 
sl@0: the schedule, KErrPermissionDenied if the client does not have the same SID as 
sl@0: the schedules creator or has WriteDeviceData capability, KErrServerBusy, if a 
sl@0: backup or restore operation is taking place or any of the other 
sl@0: system wide error codes.
sl@0: */
sl@0: EXPORT_C TInt RScheduler::DeleteSchedule(const TInt aScheduleHandle) const
sl@0: 	{
sl@0: 	return SendReceive(EDeleteSchedule, TIpcArgs(aScheduleHandle));
sl@0: 	}
sl@0: 
sl@0: /** 
sl@0: Disables the specified schedule.
sl@0: 
sl@0: @capability Note Only clients with the same SID as the schedule creator, or 
sl@0: WriteDeviceData capability can sucessfully call this API.
sl@0: 
sl@0: @param aScheduleHandle The Id that identifies the schedule.
sl@0: @return KErrNone if successful, KErrNotFound if there is no schedule with 
sl@0: the specified Id, KErrPermissionDenied if the client does not have the same SID 
sl@0: as the schedules creator or has WriteDeviceData capability, KErrServerBusy, if a 
sl@0: backup or restore operation is taking place or any of the other 
sl@0: system wide error codes.
sl@0: */
sl@0: EXPORT_C TInt RScheduler::DisableSchedule(const TInt aScheduleHandle) const
sl@0: 	{
sl@0: 	return SendReceive(EDisableSchedule, TIpcArgs(aScheduleHandle));
sl@0: 	}
sl@0: 
sl@0: /** 
sl@0: Enables the specified schedule.
sl@0: 
sl@0: @capability Note Only clients with the same SID as the schedule creator, or 
sl@0: WriteDeviceData capability can sucessfully call this API.
sl@0: 
sl@0: @param aScheduleHandle The Id that identifies the schedule.
sl@0: @return KErrNone if successful. KErrNotFound if there is no schedule with 
sl@0: the specified Id, KErrPermissionDenied if the client does not have the same SID 
sl@0: as the schedules creator or has WriteDeviceData capability, KErrServerBusy, if a 
sl@0: backup or restore operation is taking place or any of the other 
sl@0: system wide error codes.
sl@0: */
sl@0: EXPORT_C TInt RScheduler::EnableSchedule(const TInt aScheduleHandle) const
sl@0: 	{
sl@0: 	return SendReceive(EEnableSchedule, TIpcArgs(aScheduleHandle));
sl@0: 	}
sl@0: 
sl@0: /** 
sl@0: Adds a task to an existing persistent schedule.
sl@0: 
sl@0: Behaviour of execution after a Backup and Restore operation should be 
sl@0: considered when adding tasks to a persistent schedule. Persistent schedules might be 
sl@0: backed up when a one-off task might be pending, and become due and executed some time 
sl@0: after the backup operation. When the backup is restored, the tasks might be executed 
sl@0: again if they are still valid (restore done during the validation period for time-based 
sl@0: schedules, or conditions satisfied after restore for condition-based schedules). Clients 
sl@0: should refrain from creating tasks that might have undesired effects under these 
sl@0: conditions (e.g. by incurring a cost to the user by sending an SMS twice). 
sl@0: 
sl@0: @capability Note Only clients with the same SID as the schedule creator, or 
sl@0: WriteDeviceData capability can sucessfully call this API.
sl@0: 
sl@0: @param aTaskInfo Information about the task to be added to the schedule. On return
sl@0: the task Id is written into this class.
sl@0: @param aTaskData Data that is passed to the task on execution.
sl@0: @param aScheduleHandle The Id that identifies the schedule to be used.
sl@0: @return KErrNone if successful, KErrNotFound if there is no schedule with 
sl@0: the specified Id, KErrArgument if a task with a repeat vale other than 0 is 
sl@0: being tried to be assigned to a condition based schedule, 
sl@0: KErrPermissionDenied if the client does not have the same SID as the schedules
sl@0: creator or has WriteDeviceData capability, KErrServerBusy, if a backup or 
sl@0: restore operation is taking place or any of the other system wide error 
sl@0: codes.
sl@0: @panic CTaskScheduler 0 The client has not registered. The client must register 
sl@0: before adding tasks to the schedule. 
sl@0: */
sl@0: EXPORT_C TInt RScheduler::ScheduleTask(TTaskInfo& aTaskInfo, 
sl@0: 									HBufC& aTaskData, 
sl@0: 									const TInt aScheduleHandle)
sl@0: 	{
sl@0: 	TPckgC<TTaskInfo> pI(aTaskInfo);
sl@0: 	//scheduler writes back task id
sl@0: 	TPckg<TInt> id(aTaskInfo.iTaskId);
sl@0: 	TPtr pD(aTaskData.Des());
sl@0: 	return SendReceive(EScheduleTask, TIpcArgs(&pI,aScheduleHandle,&id, &pD));
sl@0: 	}
sl@0: 
sl@0: /** 
sl@0: Creates a new, transient, time based schedule and adds a task to it.
sl@0: 
sl@0: Note that a transient schedule is destroyed when the task is destroyed or 
sl@0: power is lost.
sl@0: 
sl@0: @param aTaskInfo Information about the task to be added to the transient schedule. 
sl@0: On return the task Id is written into this class.
sl@0: @param aTaskData Data that is passed to the task on execution.
sl@0: @param aRef Definition of the new transient schedule.
sl@0: @param aEntryList The set of schedule entries that make up the new transient 
sl@0: schedule.
sl@0: @return KErrNone, if successful, or any of the other system wide error codes.
sl@0: @panic CTaskScheduler 0 The client has not registered. The client must register 
sl@0: before adding tasks to the schedule.
sl@0: @see TScheduleEntryInfo2 
sl@0: */
sl@0: EXPORT_C TInt RScheduler::ScheduleTask(TTaskInfo& aTaskInfo, 
sl@0: 									HBufC& aTaskData, 
sl@0: 									TSchedulerItemRef& aRef,
sl@0: 									const CArrayFixFlat<TScheduleEntryInfo2>& aEntryList)
sl@0: 	{
sl@0: 	TScheduleSettings2 settings;
sl@0: 	settings.iPersists = EFalse;
sl@0: 	settings.iEntryCount = aEntryList.Count();
sl@0: 	settings.iName = aRef.iName;
sl@0: 	TInt res = CreateSchedule(aRef, aEntryList, settings);
sl@0: 	if (res==KErrNone)
sl@0: 		{
sl@0: 		res = ScheduleTask(aTaskInfo, aTaskData, aRef.iHandle);
sl@0: 		//the schedule here needs a task: so if we can't schedule a task,
sl@0: 		//need to delete schedule
sl@0: 		if (res!=KErrNone)
sl@0: 			DeleteSchedule(aRef.iHandle);
sl@0: 		}
sl@0: 	return res;
sl@0: 	}
sl@0: 
sl@0: /** 
sl@0: Creates a new, transient, condition based schedule and adds a task to it.
sl@0: 
sl@0: Note that a transient schedule is destroyed when the task is destroyed or
sl@0: power is lost.
sl@0: 
sl@0: @param aTaskInfo Information about the task to be added to the transient schedule. 
sl@0: On return the task Id is written into this class.
sl@0: @param aTaskData Data that is passed to the task on execution.
sl@0: @param aRef Definition of the new transient schedule.
sl@0: @param aConditions An array of schedule conditons that make up the schedule.
sl@0: @param aDefaultRunTime The time at which the schedule will run if no
sl@0: conditions are met. If this is a local time based value, the schedule will remain
sl@0: at that local time regardless of timezone and DST changes (ie. it will float)
sl@0: If the value is UTC based, the schedule will remain at that UTC time (will not float).
sl@0: @return KErrNone, if successful, KErrArgument if the publish and subscribe 
sl@0: variables, defined by aConditions category and key values, do not exist or 
sl@0: are not of integral type, or any of the other system wide error codes.
sl@0: @panic CTaskScheduler 0 The client has not registered. The client must register 
sl@0: before adding tasks to the schedule.
sl@0: 
sl@0: @internalAll
sl@0: */
sl@0: EXPORT_C TInt RScheduler::ScheduleTask(TTaskInfo& aTaskInfo, 
sl@0: 								HBufC& aTaskData, 
sl@0: 								TSchedulerItemRef& aRef, 
sl@0: 								const CArrayFixFlat<TTaskSchedulerCondition>& aConditions,
sl@0: 								const TTsTime& aDefaultRunTime)
sl@0: 	{
sl@0: 	TScheduleSettings2 settings;
sl@0: 	settings.iPersists = EFalse;
sl@0: 	settings.iEntryCount = aConditions.Count();
sl@0: 	settings.iName = aRef.iName;
sl@0: 	TInt res = CreateSchedule(aRef, aConditions, aDefaultRunTime, settings);
sl@0: 	if (res==KErrNone)
sl@0: 		{
sl@0: 		res = ScheduleTask(aTaskInfo, aTaskData, aRef.iHandle);
sl@0: 		//the schedule here needs a task: so if we can't schedule a task,
sl@0: 		//need to delete schedule
sl@0: 		if (res!=KErrNone)
sl@0: 			DeleteSchedule(aRef.iHandle);
sl@0: 		}
sl@0: 	return res;
sl@0: 	}
sl@0: 
sl@0: /** 
sl@0: Deletes the specified task.
sl@0: 
sl@0: @capability Note Only clients with the same SID as the relevant schedule
sl@0: creator, or WriteDeviceData capability can sucessfully call this API.
sl@0: 
sl@0: @param aTaskId The Id that identifies the task.
sl@0: @return KErrNone if successful, KErrNotFound if there is no task with the 
sl@0: specified Id, KErrPermissionDenied if the client does not have the same SID as 
sl@0: the schedules creator or has WriteDeviceData capability, KErrServerBusy, if a 
sl@0: backup or restore operation is taking place or any of the 
sl@0: other system wide error codes.
sl@0: */
sl@0: EXPORT_C TInt RScheduler::DeleteTask(const TInt aTaskId) const
sl@0: 	{
sl@0: 	return SendReceive(EDeleteTask, TIpcArgs(aTaskId));
sl@0: 	}
sl@0: 
sl@0: /** 
sl@0: Gets a list of all schedules, or a subset of schedules.
sl@0: 
sl@0: @capability Note A call to this API will only retrieve schedules created with
sl@0: the caller's SID.  If the caller has WriteDeviceData capability all schedules
sl@0: will be retrieved.
sl@0: 
sl@0: @param aScheduleRefArray On return, a populated array of schedule definitions. 
sl@0: Note that populating the array could cause this function to leave because 
sl@0: of an out of memory condition.
sl@0: @param aFilter The schedule filter.
sl@0: @return KErrNone if successful otherwise one of the other system wide error 
sl@0: codes.
sl@0: @see TSchedulerItemRef 
sl@0: */
sl@0: EXPORT_C TInt RScheduler::GetScheduleRefsL(CArrayFixFlat<TSchedulerItemRef>& aScheduleRefArray,
sl@0: 									const TScheduleFilter aFilter)
sl@0: 	{
sl@0: 	//1) get number of refs
sl@0: 	TInt count;//scheduler writes back count
sl@0: 	TPckg<TInt> pCount(count);
sl@0: 	TInt res = SendReceive(ECountSchedules, TIpcArgs(&pCount, aFilter));
sl@0: 	if (res!=KErrNone)
sl@0: 		return res;
sl@0: 	aScheduleRefArray.ResizeL(count);
sl@0: 	//2) get refs, if there are any
sl@0: 	if (count>0)
sl@0: 		{
sl@0: 		TPtr8 sPtr((TUint8*)&(aScheduleRefArray.At(0)), count*sizeof(TSchedulerItemRef));
sl@0: 		res = SendReceive(EGetScheduleRefs, TIpcArgs(count, aFilter, &sPtr));
sl@0: 		}
sl@0: 	return res;
sl@0: 	}
sl@0: 
sl@0: /** 
sl@0: Gets information relating to a specified time based schedule.
sl@0: 
sl@0: @capability Note Only clients with the same SID as the schedule creator, or 
sl@0: WriteDeviceData capability can sucessfully call this API.
sl@0: 
sl@0: @param aScheduleHandle The Id that identifies the schedule.
sl@0: @param aState On return, the state of the specified schedule.
sl@0: @param aEntries On return, a populated array of schedule entries that make 
sl@0: up the schedule. Note that populating the array could cause this function 
sl@0: to leave because of an out of memory condition.
sl@0: @param aTasks On return, a populated array of tasks associated with the schedule. 
sl@0: Note that populating the array could cause this function to leave because 
sl@0: of an out of memory condition.
sl@0: @param aDueTime On return, the time that the schedule is next due. This value may
sl@0: be local time or UTC based,dependent on the type of time used for schedule entries.
sl@0: Comparisons used within the scheduler to find the next due time are UTC based.
sl@0: @return KErrNone if successful, KErrNotFound if there is no schedule with 
sl@0: the specified Id, KErrArgument if the schedule is not a time based one, 
sl@0: KErrPermissionDenied if the client does not have the same SID as the schedules
sl@0: creator or has WriteDeviceData capability, or any of the other system wide error 
sl@0: codes.
sl@0: @see TScheduleEntryInfo2
sl@0: @see TTaskInfo 
sl@0: */
sl@0: EXPORT_C TInt RScheduler::GetScheduleL(const TInt aScheduleHandle, 
sl@0: 									TScheduleState2& aState, 
sl@0: 									CArrayFixFlat<TScheduleEntryInfo2>& aEntries, 
sl@0: 									CArrayFixFlat<TTaskInfo>& aTasks, 
sl@0: 									TTsTime& aDueTime)
sl@0: 	{
sl@0: 	TScheduleInfo info;
sl@0: 	TInt res = GetScheduleInfo(aScheduleHandle, info, aDueTime);
sl@0: 	if (res != KErrNone)
sl@0: 		return res;
sl@0: 	aState = info.iState;
sl@0: 	res = GetScheduleDataL(aScheduleHandle, info, aEntries);
sl@0: 	if (res != KErrNone)
sl@0: 		return res;
sl@0: 	res = GetTaskDataL(aScheduleHandle, info, aTasks);							
sl@0: 	return res;
sl@0: 	}
sl@0: 
sl@0: /** 
sl@0: Gets information relating to a specified condition based schedule.
sl@0: 
sl@0: @capability Note Only clients with the same SID as the schedule creator, or 
sl@0: WriteDeviceData capability can sucessfully call this API.
sl@0: 
sl@0: @param aScheduleHandle The Id that identifies the schedule.
sl@0: @param aState On return, the state of the specified schedule.
sl@0: @param aConditions On return, a populated array of schedule conditons 
sl@0: that make up the schedule. Note that populating the array could cause 
sl@0: this function to leave because of an out of memory condition.
sl@0: @param aDefaultRunTime On return, the time at which the schedule with run if
sl@0: no conditions are met. If this is a local time based value, the schedule will remain
sl@0: at that local time regardless of timezone and DST changes (ie. it will float)
sl@0: If the value is UTC based, the schedule will remain at that UTC time (will not float).
sl@0: @param aTasks On return, a populated array of tasks associated with the schedule. 
sl@0: Note that populating the array could cause this function to leave because 
sl@0: of an out of memory condition.
sl@0: @return KErrNone if successful, KErrNotFound if there is no schedule with 
sl@0: the specified Id, KErrArgument if the schedule is not a condition based one, 
sl@0: KErrPermissionDenied if the client does not have the same SID as the schedules
sl@0: creator or has WriteDeviceData capability, or any of the other system wide error 
sl@0: codes.
sl@0: @see TTaskSchedulerCondition
sl@0: @see TTaskInfo 
sl@0: 
sl@0: @internalAll
sl@0: */
sl@0: EXPORT_C TInt RScheduler::GetScheduleL(TInt aScheduleHandle, 
sl@0: 							TScheduleState2& aState, 
sl@0: 							CArrayFixFlat<TTaskSchedulerCondition>& aConditions,
sl@0: 							TTsTime& aDefaultRunTime,
sl@0: 							CArrayFixFlat<TTaskInfo>& aTasks)
sl@0: 	{
sl@0: 	TScheduleInfo info;
sl@0: 	TTsTime dummyTime;
sl@0: 	TInt res = GetScheduleInfo(aScheduleHandle, info, dummyTime);
sl@0: 	if (res != KErrNone)
sl@0: 		return res;
sl@0: 	aState = info.iState;
sl@0: 	res = GetScheduleDataL(aScheduleHandle, 
sl@0: 							info, 
sl@0: 							aConditions, 
sl@0: 							aDefaultRunTime);
sl@0: 	if (res != KErrNone)
sl@0: 		return res;
sl@0: 	res = GetTaskDataL(aScheduleHandle, info, aTasks);							
sl@0: 	return res;
sl@0: 	}
sl@0: 
sl@0: /**
sl@0: Gets the schedule type.
sl@0: 
sl@0: @capability Note Only clients with the same SID as the schedule creator, or 
sl@0: WriteDeviceData capability can sucessfully call this API.
sl@0: 
sl@0: @param aScheduleHandle The Id that identifies the schedule
sl@0: @param aScheduleType On return the type of schedule relating to the handle.
sl@0: @return KErrNone if successful, KErrNotFound if there is no schedule with 
sl@0: the specified Id, KErrPermissionDenied if the client does not have the same SID 
sl@0: as the schedules creator or has WriteDeviceData capability, or any of the other 
sl@0: system wide error codes.
sl@0: 
sl@0: @internalAll
sl@0: */
sl@0: EXPORT_C TInt RScheduler::GetScheduleTypeL(TInt aScheduleHandle,
sl@0: 											TScheduleType& aScheduleType)
sl@0: 	{
sl@0: 	TPckg<TScheduleType> id(aScheduleType);
sl@0: 	return SendReceive(EGetScheduleType, TIpcArgs(aScheduleHandle, &id));
sl@0: 	}
sl@0: 
sl@0: /** 
sl@0: Gets a list of all tasks, or a subset of tasks.
sl@0: 
sl@0: Note that if more than one client has supplied the same information when registering, 
sl@0: then it is possible for a list of tasks to be returned, which the calling 
sl@0: client has not scheduled.
sl@0: 
sl@0: @capability Note A call to this API will only retrieve tasks created with
sl@0: the caller's SID.  If the caller has WriteDeviceData capability all tasks
sl@0: will be retrieved.
sl@0: 
sl@0: @param aTasks On return, a populated array of schedule definitions. The schedule 
sl@0: definitions are those whose associated tasks satisfy the selection criteria. 
sl@0: Note that populating the array could cause this function to leave because 
sl@0: of an out of memory condition.
sl@0: @param aScheduleFilter The schedule filter.
sl@0: @param aTaskFilter The task filter.
sl@0: @return KErrNone if successful otherwise one of the other system wide error 
sl@0: codes.
sl@0: @see TSchedulerItemRef 
sl@0: */
sl@0: EXPORT_C TInt RScheduler::GetTaskRefsL(CArrayFixFlat<TSchedulerItemRef>& aTasks,
sl@0: 										const TScheduleFilter aScheduleFilter,
sl@0: 										const TTaskFilter aTaskFilter)
sl@0: 	{
sl@0: 	//1)get number of tasks
sl@0: 	TInt count;
sl@0: 	TPckg<TInt> pCount(count);
sl@0: 	TInt res = SendReceive(ECountTasks, TIpcArgs(&pCount, aScheduleFilter, aTaskFilter));
sl@0: 	if (res!=KErrNone)
sl@0: 		return res;
sl@0: 	aTasks.ResizeL(count);
sl@0: 	//2)get taskrefs
sl@0: 	if (count >0)
sl@0: 		{
sl@0: 		TPtr8 pTasks(REINTERPRET_CAST(TUint8*, &(aTasks.At(0))), count*sizeof(TSchedulerItemRef));
sl@0: 		res = SendReceive(EGetTaskRefs, TIpcArgs(count, aScheduleFilter, aTaskFilter, &pTasks));
sl@0: 		}
sl@0: 	return res;
sl@0: 	}
sl@0: 
sl@0: /** 
sl@0: Gets information relating to a specified task.
sl@0: 
sl@0: @capability Note Only clients with the same SID as the relevant schedule
sl@0: creator, or WriteDeviceData capability can sucessfully call this API.
sl@0: 
sl@0: @param aTaskId The Id that identifies the task.
sl@0: @param aTaskInfo On return, information about the task.
sl@0: @param aTaskData On return, a pointer descriptor representing the data that 
sl@0: is passed to the program to be executed. The caller must set up this pointer 
sl@0: descriptor before calling the function. The required length of the descriptor 
sl@0: can be found by calling GetTaskDataSize().
sl@0: @param aRef On return, the associated schedule definition.
sl@0: @param aNextDue On return, the time that the task is next due. This value may
sl@0: be local time or UTC based. Comparisons used to find the next due time are based on UTC.
sl@0: @return KErrNone, if successful. KErrNotFound, if there is no task with the 
sl@0: specified Id, KErrPermissionDenied if the client does not have the same SID as 
sl@0: the schedules creator or has WriteDeviceData capability. 
sl@0: */
sl@0: EXPORT_C TInt RScheduler::GetTaskInfoL(const TInt aTaskId, TTaskInfo& aTaskInfo, TPtr& aTaskData, TSchedulerItemRef& aRef, TTsTime& aNextDue)
sl@0: 	{
sl@0: 	// First of all retrieve the normal stuff
sl@0: 	TPtr8 pInfo((TUint8*)&aTaskInfo,sizeof(TTaskInfo));
sl@0: 	TInt size = aTaskData.MaxLength();
sl@0: 	TInt res = SendReceive(EGetTask, TIpcArgs(aTaskId, &pInfo, size, &aTaskData));
sl@0: 	if (res != KErrNone)
sl@0: 		return res;
sl@0: 
sl@0: 	// Next retrieve the TSchedulerItemRef and next due time
sl@0: 	TPtr8 pItemRef((TUint8*)&aRef, sizeof(TSchedulerItemRef));
sl@0: 	TPtr8 pDueTime((TUint8*)&aNextDue, sizeof(TTsTime));
sl@0: 	return SendReceive(EGetSchedulerItemRefAndNextDueTime, TIpcArgs(aTaskId, &pItemRef, &pDueTime));
sl@0: 	}
sl@0: 
sl@0: /** 
sl@0: Gets the size of the data to be passed to the task's program.
sl@0: 
sl@0: This function should be called before calling GetTaskInfoL() so that a descriptor 
sl@0: of the correct size can be set up.
sl@0: 
sl@0: @capability Note Only clients with the same SID as the relevant schedule
sl@0: creator, or WriteDeviceData capability can sucessfully call this API.
sl@0: 
sl@0: @param aTaskId The Id that identifies the task.
sl@0: @param aSize The size of the task's data.
sl@0: @return KErrNone if successful, KErrNotFound if there is no task with the 
sl@0: specified Id, KErrPermissionDenied if the client does not have the same SID as 
sl@0: the schedules creator or has WriteDeviceData capability, otherwise any of the 
sl@0: other system wide error codes.
sl@0: */
sl@0: EXPORT_C TInt RScheduler::GetTaskDataSize(const TInt aTaskId, TInt& aSize)
sl@0: 	{
sl@0: 	TPckg<TInt> pSize(aSize);
sl@0: 	return SendReceive(EGetTaskDataSize, TIpcArgs(aTaskId, &pSize));
sl@0: 	}
sl@0: 
sl@0: //Converts array of TScheduleEntryInfos to an array of TScheduleEntryInfo2s.
sl@0: void ConvertArrayToEntryInfo2L(const CArrayFixFlat<TScheduleEntryInfo>& aEntryList,
sl@0: 							CArrayFixFlat<TScheduleEntryInfo2>& aEntry2List)
sl@0: 	{
sl@0: 	aEntry2List.ResizeL(aEntryList.Count());
sl@0: 	
sl@0: 	TScheduleEntryInfo entryInfo;
sl@0: 	for (TInt i=0; i < aEntryList.Count(); i++)
sl@0: 		{
sl@0: 		entryInfo = aEntryList.At(i);
sl@0: 		//create new TScheduleEntryInfo2 object from old TScheduleEntryInfo object
sl@0: 		//assume local time for backwards compatibility
sl@0: 		TScheduleEntryInfo2 entryInfo2(entryInfo);	
sl@0: 		aEntry2List.At(i) = entryInfo2;
sl@0: 		}	
sl@0: 	}
sl@0: 
sl@0: //Converts array of TScheduleEntryInfo2s to an array of TScheduleEntryInfos.
sl@0: void ConvertArrayFromEntryInfo2L(const CArrayFixFlat<TScheduleEntryInfo2>& aEntry2List,
sl@0: 							CArrayFixFlat<TScheduleEntryInfo>& aEntryList)
sl@0: 	{
sl@0: 	TScheduleEntryInfo entryInfo;
sl@0: 	TScheduleEntryInfo2 entryInfo2;
sl@0: 	
sl@0: 	aEntryList.ResizeL(aEntry2List.Count());
sl@0: 	for(TInt i=0; i<aEntry2List.Count(); i++)
sl@0: 		{
sl@0: 		entryInfo2 = aEntry2List.At(i);
sl@0: 		
sl@0: 		//use local time for backwards compatibility
sl@0: 		entryInfo.iStartTime = entryInfo2.StartTime().GetLocalTime(); 
sl@0: 		entryInfo.iIntervalType = entryInfo2.IntervalType();
sl@0: 		entryInfo.iInterval = entryInfo2.Interval();
sl@0: 		entryInfo.iValidityPeriod = entryInfo2.ValidityPeriod();
sl@0: 		
sl@0: 		aEntryList.At(i) = entryInfo;
sl@0: 		}
sl@0: 	}
sl@0: 
sl@0: /** 
sl@0: Creates a persistent time based schedule.
sl@0: 
sl@0: This schedule has no tasks associated with it but merely contains information
sl@0: about start and finish times.
sl@0: 
sl@0: @capability WriteDeviceData
sl@0: @param aRef Definition of the new schedule.  On return this contains a valid
sl@0: handle to the newly created schedule.
sl@0: @param aEntryList The set of schedule entries that make up the new schedule.
sl@0: Start times of all entries are assumed to be local time based.
sl@0: @return KErrNone, if successful, KErrArgument if the condition array is 
sl@0: empty, or an entry has an interval less than 1, KErrServerBusy, if a backup or 
sl@0: restore operation is taking place, KErrPermissionDenied if the 
sl@0: client does not have WriteDeviceData capability. 
sl@0: Otherwise one of the other system wide error codes.
sl@0: @see TScheduleEntryInfo 
sl@0: @deprecated See note in CSch_Cli.h
sl@0: */
sl@0: EXPORT_C TInt RScheduler::CreatePersistentSchedule(TSchedulerItemRef& aRef, 
sl@0: 							const CArrayFixFlat<TScheduleEntryInfo>& aEntryList)
sl@0: 	{
sl@0: 	//create schedule settings object
sl@0: 	TScheduleSettings2 settings;
sl@0: 	settings.iPersists = ETrue;
sl@0: 	settings.iName = aRef.iName;
sl@0: 	settings.iEntryCount = aEntryList.Count();
sl@0: 	
sl@0: 	//create array of TScheduleEntryInfo2's from array of TScheduleEntryInfo's.
sl@0: 	//assume local time for backwards compatibility.
sl@0: 	CArrayFixFlat<TScheduleEntryInfo2>* entryInfo2List = new (ELeave) CArrayFixFlat<TScheduleEntryInfo2>(1);
sl@0: 	CleanupStack::PushL(entryInfo2List);
sl@0: 	ConvertArrayToEntryInfo2L(aEntryList, *entryInfo2List);
sl@0: 
sl@0: 	//create schedule using new array of TScheduleEntryInfo2s.
sl@0: 	TInt err = CreateSchedule(aRef, *entryInfo2List, settings);
sl@0: 	
sl@0: 	CleanupStack::PopAndDestroy(entryInfo2List);
sl@0: 	return err;
sl@0: 	}
sl@0: 	
sl@0: 
sl@0: 	
sl@0: /** 
sl@0: Creates a persistent condition based schedule.
sl@0: 
sl@0: This schedule has no tasks associated with it but merely contains information
sl@0: about conditions that must be satified to complete this schedule.
sl@0: 
sl@0: @capability WriteDeviceData
sl@0: @param aRef Definition of the new schedule.  On return this contains a valid
sl@0: handle to the newly created schedule.
sl@0: @param aConditions An array of system agent conditons 
sl@0: that make up the schedule.
sl@0: @param aDefaultRunTime The time at which the schedule with run if no
sl@0: conditions are met. Default run times of all schedules created 
sl@0: using this API are assumed to be local time based.
sl@0: @return KErrNone, if successful, KErrArgument if the condition array is 
sl@0: empty or if the publish and subscribe variables have an invalid category.
sl@0: KErrServerBusy, if a backup or restore operation is taking place.
sl@0: KErrPermissionDenied if the client does not have WriteDeviceData capability. 
sl@0: Otherwise one of the other system wide error codes.
sl@0: @see TTaskSchedulerCondition 
sl@0: @internalAll
sl@0: @deprecated See note in CSch_Cli.h 
sl@0: */
sl@0: EXPORT_C TInt RScheduler::CreatePersistentSchedule(TSchedulerItemRef& aRef, 
sl@0: 							const CArrayFixFlat<TTaskSchedulerCondition>& aConditions,
sl@0: 							const TTime& aDefaultRunTime)
sl@0: 	{
sl@0: 	//create schedule settings object
sl@0: 	TScheduleSettings2 settings;
sl@0: 	settings.iPersists = ETrue;
sl@0: 	settings.iEntryCount = aConditions.Count();
sl@0: 	settings.iName = aRef.iName;
sl@0: 	
sl@0: 	// create TTsTime object from TTime argument aDefaultRunTime.
sl@0: 	// assume aDefaultTime is local time based for backwards compatibility
sl@0: 	TTsTime defaultRunTime(aDefaultRunTime, EFalse);	
sl@0: 	
sl@0: 	return CreateSchedule(aRef, aConditions, defaultRunTime, settings);	
sl@0: 	}
sl@0: 
sl@0: 
sl@0: /** 
sl@0: Changes a time based schedule.
sl@0: 
sl@0: Note that changing a schedule is implemented by supplying a replacement set 
sl@0: of schedule entries.
sl@0: 
sl@0: @capability Note Only clients with the same SID as the schedule creator, or 
sl@0: WriteDeviceData capability can sucessfully call this API.
sl@0: 
sl@0: @param aScheduleHandle The Id that identifies the schedule.
sl@0: @param aEntryList The set of schedule entries that will make up the new schedule.
sl@0: Start times of all entries are assumed to be local time based.
sl@0: @return KErrNone if successful, KErrNotFound if there is no schedule with 
sl@0: the specified Id, KErrArgument if the schedule is not a time based one, 
sl@0: KErrPermissionDenied if the client does not have the same SID as the schedules
sl@0: creator or has WriteDeviceData capability, KErrServerBusy, if a backup or 
sl@0: restore operation is taking place or any of the other system wide error 
sl@0: codes.
sl@0: @see TScheduleEntryInfo 
sl@0: @deprecated See note in CSch_Cli.h
sl@0: */
sl@0: EXPORT_C TInt RScheduler::EditSchedule(const TInt aScheduleHandle, const CArrayFixFlat<TScheduleEntryInfo>& aEntryList)
sl@0: 	{
sl@0: 	TInt count = aEntryList.Count();
sl@0: 	
sl@0: 	CArrayFixFlat<TScheduleEntryInfo2>* entryInfo2List = new (ELeave) CArrayFixFlat<TScheduleEntryInfo2>(1);
sl@0: 	CleanupStack::PushL(entryInfo2List);
sl@0: 	
sl@0: 	//creates array of TScheduleEntryInfo2's from array of TScheduleEntryInfo's.
sl@0: 	//assumes local time for backwards compatibility.
sl@0: 	ConvertArrayToEntryInfo2L(aEntryList, *entryInfo2List);
sl@0: 	
sl@0: 	if (ScheduleEntriesAreBad(*entryInfo2List))
sl@0: 		return KErrArgument;
sl@0: 		
sl@0: 	TPtrC8 pA((TUint8*) &entryInfo2List->At(0), sizeof(TScheduleEntryInfo2)*count);
sl@0: 	TInt err = SendReceive(EEditTimeSchedule, TIpcArgs(count, aScheduleHandle, &pA));
sl@0: 	CleanupStack::PopAndDestroy(entryInfo2List);
sl@0: 	return err;
sl@0: 	}
sl@0: 
sl@0: /**  
sl@0: Changes a condition based schedule.
sl@0: 
sl@0: Note that changing a schedule is implemented by supplying a replacement set 
sl@0: of schedule conditons and time.
sl@0: 
sl@0: @capability Note Only clients with the same SID as the schedule creator, or 
sl@0: WriteDeviceData capability can sucessfully call this API.
sl@0: 
sl@0: @param aScheduleHandle The Id that identifies the schedule.
sl@0: @param aConditions An array of system agent conditons 
sl@0: that make up the schedule.
sl@0: @param aDefaultRunTime The time at which the schedule with run if no
sl@0: conditions are met. Note that this parameter is assumed to be local time based.
sl@0: @return KErrNone if successful, KErrNotFound if there is no schedule with 
sl@0: the specified Id, KErrArgument if the schedule is not a condition based one
sl@0: or if the publish and subscribe variables, defined by aConditions category 
sl@0: and key values, do not exist or are not of integral type, 
sl@0: KErrPermissionDenied if the client does not have the same SID as the schedules
sl@0: creator or has WriteDeviceData capability, KErrServerBusy, if a backup or 
sl@0: restore operation is taking place or any of the other system wide error 
sl@0: codes.
sl@0: 
sl@0: @internalAll
sl@0: @deprecated See note in CSch_Cli.h
sl@0: */	
sl@0: EXPORT_C TInt RScheduler::EditSchedule(TInt aScheduleHandle, 
sl@0: 						const CArrayFixFlat<TTaskSchedulerCondition>& aConditions,
sl@0: 						const TTime& aDefaultRunTime)
sl@0: 	{
sl@0: 	TInt count = aConditions.Count();
sl@0: 	TPtrC8 pA((TUint8*) &aConditions.At(0), sizeof(TTaskSchedulerCondition)*count);
sl@0: 	
sl@0: 	// create TTsTime object from aDefaultRunTime. 
sl@0: 	// aDefaultRunTime is assumed to be local time based for backwards compatibility
sl@0: 	TTsTime defaultRunTime(aDefaultRunTime, EFalse);	
sl@0: 	//write Time
sl@0: 	TPckgC<TTsTime> pTime(defaultRunTime);
sl@0: 	return SendReceive(EEditConditionSchedule, TIpcArgs(count, aScheduleHandle, &pA, &pTime));	
sl@0: 	}
sl@0: 
sl@0: 
sl@0: /** 
sl@0: Creates a new, transient, time based schedule and adds a task to it.
sl@0: 
sl@0: Note that a transient schedule is destroyed when the task is destroyed or 
sl@0: power is lost.
sl@0: 
sl@0: @param aTaskInfo Information about the task to be added to the transient schedule. 
sl@0: On return the task Id is written into this class.
sl@0: @param aTaskData Data that is passed to the task on execution.
sl@0: @param aRef Definition of the new transient schedule.
sl@0: @param aEntryList The set of schedule entries that make up the new transient 
sl@0: schedule. All entry start times are assumed to be local time based.
sl@0: @return KErrNone, if successful, otherwise one of the other system wide error 
sl@0: codes.
sl@0: @panic CTaskScheduler 0 The client has not registered. The client must register 
sl@0: before adding tasks to the schedule.
sl@0: @see TScheduleEntryInfo 
sl@0: @deprecated See note in CSch_Cli.h
sl@0: */
sl@0: EXPORT_C TInt RScheduler::ScheduleTask(TTaskInfo& aTaskInfo, 
sl@0: 									HBufC& aTaskData, 
sl@0: 									TSchedulerItemRef& aRef,
sl@0: 									const CArrayFixFlat<TScheduleEntryInfo>& aEntryList)
sl@0: 	{
sl@0: 	TScheduleSettings2 settings;
sl@0: 	settings.iPersists = EFalse;
sl@0: 	settings.iEntryCount = aEntryList.Count();
sl@0: 	settings.iName = aRef.iName;
sl@0: 	
sl@0: 	CArrayFixFlat<TScheduleEntryInfo2>* entryInfo2List = new (ELeave) CArrayFixFlat<TScheduleEntryInfo2>(1);
sl@0: 	CleanupStack::PushL(entryInfo2List);
sl@0: 
sl@0: 	//creates array of TScheduleEntryInfo2's from array of TScheduleEntryInfo's.
sl@0: 	//assumes local time for backwards compatibility.
sl@0: 	ConvertArrayToEntryInfo2L(aEntryList, *entryInfo2List);
sl@0: 
sl@0: 	TInt res = CreateSchedule(aRef, *entryInfo2List, settings);
sl@0: 	CleanupStack::PopAndDestroy(entryInfo2List);
sl@0: 	
sl@0: 	if (res==KErrNone)
sl@0: 		{
sl@0: 		res = ScheduleTask(aTaskInfo, aTaskData, aRef.iHandle);
sl@0: 		//the schedule here needs a task: so if we can't schedule a task,
sl@0: 		//need to delete schedule
sl@0: 		if (res!=KErrNone)
sl@0: 			DeleteSchedule(aRef.iHandle);
sl@0: 		}
sl@0: 	return res;
sl@0: 	}
sl@0: 
sl@0: 
sl@0: /** 
sl@0: Creates a new, transient, condition based schedule and adds a task to it.
sl@0: 
sl@0: Note that a transient schedule is destroyed when the task is destroyed or
sl@0: power is lost.
sl@0: 
sl@0: @param aTaskInfo Information about the task to be added to the transient schedule. 
sl@0: On return the task Id is written into this class.
sl@0: @param aTaskData Data that is passed to the task on execution.
sl@0: @param aRef Definition of the new transient schedule.
sl@0: @param aConditions An array of schedule conditons that make up the schedule.
sl@0: @param aDefaultRunTime The time at which the schedule with run if no
sl@0: conditions are met. aDefaultRunTime is assumed to be local time based.
sl@0: @return KErrNone, if successful, KErrArgument if the publish and subscribe 
sl@0: variables, defined by aConditions category and key values, do not exist or 
sl@0: are not of integral type, otherwise one of the other system wide error codes.
sl@0: @panic CTaskScheduler 0 The client has not registered. The client must register 
sl@0: before adding tasks to the schedule.
sl@0: 
sl@0: @internalAll
sl@0: @deprecated See note in CSch_Cli.h
sl@0: */
sl@0: EXPORT_C TInt RScheduler::ScheduleTask(TTaskInfo& aTaskInfo, 
sl@0: 								HBufC& aTaskData, 
sl@0: 								TSchedulerItemRef& aRef, 
sl@0: 								const CArrayFixFlat<TTaskSchedulerCondition>& aConditions,
sl@0: 								const TTime& aDefaultRunTime)
sl@0: 	{
sl@0: 	// create schedule settings object
sl@0: 	TScheduleSettings2 settings;
sl@0: 	settings.iPersists = EFalse;
sl@0: 	settings.iEntryCount = aConditions.Count();
sl@0: 	settings.iName = aRef.iName;
sl@0: 	
sl@0: 	// create TTsTime object from aDefaultRunTime.
sl@0: 	// assumes aDefaultRunTime is local time based for backwards compatibility
sl@0: 	TTsTime defaultRunTime(aDefaultRunTime, EFalse);
sl@0: 	
sl@0: 	TInt res = CreateSchedule(aRef, aConditions, defaultRunTime, settings);
sl@0: 	if (res==KErrNone)
sl@0: 		{
sl@0: 		res = ScheduleTask(aTaskInfo, aTaskData, aRef.iHandle);
sl@0: 		//the schedule here needs a task: so if we can't schedule a task,
sl@0: 		//need to delete schedule
sl@0: 		if (res!=KErrNone)
sl@0: 			DeleteSchedule(aRef.iHandle);
sl@0: 		}
sl@0: 	return res;
sl@0: 	}
sl@0: 
sl@0: 
sl@0: /** 
sl@0: Gets information relating to a specified time based schedule.
sl@0: 
sl@0: @capability Note Only clients with the same SID as the schedule creator, or 
sl@0: WriteDeviceData capability can sucessfully call this API.
sl@0: 
sl@0: @param aScheduleHandle The Id that identifies the schedule.
sl@0: @param aState On return, the state of the specified schedule.
sl@0: On return, aState will have a local time based iDueTime member, regardless 
sl@0: of whether the schedule is UTC or local time based. If the schedule is UTC 
sl@0: based, the due time will be converted to a local time based value before returning.
sl@0: @param aEntries On return, a populated array of schedule entries that make 
sl@0: up the schedule. All entry start times returned will be local time based, 
sl@0: though they may be UTC or local time based within the scheduler. The scheduler will
sl@0: convert any UTC based times to local time before returning.
sl@0: Note that populating the array could cause this function 
sl@0: to leave because of an out of memory condition.
sl@0: @param aTasks On return, a populated array of tasks associated with the schedule. 
sl@0: Note that populating the array could cause this function to leave because 
sl@0: of an out of memory condition.
sl@0: @param aDueTime On return, the time that the schedule is next due. This value
sl@0: will be local time based, regardless of whether the schedule is UTC or local 
sl@0: time based. If the schedule is UTC based, the due time will be converted to 
sl@0: a local time based value before returning.
sl@0: @return KErrNone if successful, KErrNotFound if there is no schedule with 
sl@0: the specified Id, KErrArgument if the schedule is not a time based one, 
sl@0: KErrPermissionDenied if the client does not have the same SID as the schedules
sl@0: creator or has WriteDeviceData capability, or any of the other system wide error 
sl@0: codes.
sl@0: @see TScheduleEntryInfo
sl@0: @see TTaskInfo 
sl@0: @deprecated See note in CSch_Cli.h
sl@0: */
sl@0: EXPORT_C TInt RScheduler::GetScheduleL(const TInt aScheduleHandle, 
sl@0: 									TScheduleState& aState, 
sl@0: 									CArrayFixFlat<TScheduleEntryInfo>& aEntries, 
sl@0: 									CArrayFixFlat<TTaskInfo>& aTasks, 
sl@0: 									TTime& aDueTime)
sl@0: 	{
sl@0: 	// set up vars required->scheduleState, entries, and time
sl@0: 	TTsTime dueTime;
sl@0: 	TScheduleState2 state;
sl@0: 	CArrayFixFlat<TScheduleEntryInfo2>* entryInfo2List = new (ELeave) CArrayFixFlat<TScheduleEntryInfo2>(1);
sl@0: 	CleanupStack::PushL(entryInfo2List);
sl@0: 	
sl@0: 	// call new API	
sl@0: 	TInt res = GetScheduleL(aScheduleHandle,
sl@0: 							state,
sl@0: 							*entryInfo2List,
sl@0: 							aTasks, 
sl@0: 							dueTime);
sl@0: 							
sl@0: 	// convert vars back to old versions
sl@0: 	// use local time for backwards compatibility
sl@0: 	aDueTime = dueTime.GetLocalTime();	
sl@0: 	aState = TScheduleState(state);
sl@0: 	ConvertArrayFromEntryInfo2L(*entryInfo2List, aEntries);
sl@0: 			
sl@0: 	CleanupStack::PopAndDestroy(entryInfo2List);
sl@0: 	return res;
sl@0: 	
sl@0: 	}
sl@0: 
sl@0: /** 
sl@0: Gets information relating to a specified condition based schedule.
sl@0: 
sl@0: @capability Note Only clients with the same SID as the schedule creator, or 
sl@0: WriteDeviceData capability can sucessfully call this API.
sl@0: 
sl@0: @param aScheduleHandle The Id that identifies the schedule.
sl@0: @param aState On return, the state of the specified schedule.
sl@0: On return, aState will have a local time based iDueTime member, regardless 
sl@0: of whether the schedule is UTC or local time based. If the schedule is UTC 
sl@0: based, the due time will be converted to a local time based value before returning.
sl@0: @param aConditions On return, a populated array of schedule conditons 
sl@0: that make up the schedule. Note that populating the array could cause 
sl@0: this function to leave because of an out of memory condition.
sl@0: @param aDefaultRunTime On return, the time at which the schedule with run if
sl@0: no conditions are met. This value will be local time based, regardless of 
sl@0: whether the schedule is UTC or local time based. If the schedule is UTC based, 
sl@0: the due time will be converted to a local time based value before returning.
sl@0: @param aTasks On return, a populated array of tasks associated with the schedule. 
sl@0: Note that populating the array could cause this function to leave because 
sl@0: of an out of memory condition.
sl@0: @return KErrNone if successful, KErrNotFound if there is no schedule with 
sl@0: the specified Id, KErrArgument if the schedule is not a condition based one, 
sl@0: KErrPermissionDenied if the client does not have the same SID as the schedules
sl@0: creator or has WriteDeviceData capability, or any of the other system wide error 
sl@0: codes.
sl@0: @see TTaskSchedulerCondition
sl@0: @see TTaskInfo 
sl@0: 
sl@0: @internalAll
sl@0: @deprecated See note in CSch_Cli.h
sl@0: */
sl@0: EXPORT_C TInt RScheduler::GetScheduleL(TInt aScheduleHandle, 
sl@0: 							TScheduleState& aState, 
sl@0: 							CArrayFixFlat<TTaskSchedulerCondition>& aConditions,
sl@0: 							TTime& aDefaultRunTime,
sl@0: 							CArrayFixFlat<TTaskInfo>& aTasks)
sl@0: 	{
sl@0: 	TScheduleInfo info;
sl@0: 	TTsTime dummyTime;
sl@0: 	TInt res = GetScheduleInfo(aScheduleHandle, info, dummyTime);
sl@0: 	if (res != KErrNone)
sl@0: 		return res;
sl@0: 	aState = TScheduleState(info.iState);
sl@0: 	TTsTime defaultRunTime;
sl@0: 	res = GetScheduleDataL(aScheduleHandle, 
sl@0: 							info, 
sl@0: 							aConditions, 
sl@0: 							defaultRunTime);
sl@0: 							
sl@0: 	//uses local time for backwards compatibility							
sl@0: 	aDefaultRunTime = defaultRunTime.GetLocalTime();
sl@0: 	
sl@0: 	if (res != KErrNone)
sl@0: 		return res;
sl@0: 	res = GetTaskDataL(aScheduleHandle, info, aTasks);							
sl@0: 	return res;
sl@0: 	}
sl@0:  
sl@0: 	
sl@0: /** 
sl@0: Gets information relating to a specified task.
sl@0: 
sl@0: @capability Note Only clients with the same SID as the relevant schedule
sl@0: creator, or WriteDeviceData capability can sucessfully call this API.
sl@0: 
sl@0: @param aTaskId The Id that identifies the task.
sl@0: @param aTaskInfo On return, information about the task.
sl@0: @param aTaskData On return, a pointer descriptor representing the data that 
sl@0: is passed to the program to be executed. The caller must set up this pointer 
sl@0: descriptor before calling the function. The required length of the descriptor 
sl@0: can be found by calling GetTaskDataSize().
sl@0: @param aRef On return, the associated schedule definition.
sl@0: @param aNextDue On return, the time that the task is next due. This value
sl@0: will be local time based, regardless of whether the schedule is UTC or local 
sl@0: time based. If the schedule is UTC based, the due time will be converted to 
sl@0: a local time based value before returning.
sl@0: @return KErrNone, if successful. KErrNotFound, if there is no task with the 
sl@0: specified Id, KErrPermissionDenied if the client does not have the same SID as 
sl@0: the schedules creator or has WriteDeviceData capability. 
sl@0: @deprecated See note in CSch_Cli.h
sl@0: */
sl@0: EXPORT_C TInt RScheduler::GetTaskInfoL(const TInt aTaskId, TTaskInfo& aTaskInfo, TPtr& aTaskData, TSchedulerItemRef& aRef, TTime& aNextDue)
sl@0: 	{
sl@0: 	// First of all retrieve the normal stuff
sl@0: 	TPtr8 pInfo((TUint8*)&aTaskInfo,sizeof(TTaskInfo));
sl@0: 	TInt size = aTaskData.MaxLength();
sl@0: 	TInt res = SendReceive(EGetTask, TIpcArgs(aTaskId, &pInfo, size, &aTaskData));
sl@0: 	if (res != KErrNone)
sl@0: 		return res;
sl@0: 
sl@0: 	// Next retrieve the TSchedulerItemRef and next due time
sl@0: 	TTsTime nextDueTime;
sl@0: 	TPtr8 pItemRef((TUint8*)&aRef, sizeof(TSchedulerItemRef));
sl@0: 	TPtr8 pDueTime((TUint8*)&nextDueTime, sizeof(TTsTime));
sl@0: 	res = SendReceive(EGetSchedulerItemRefAndNextDueTime, TIpcArgs(aTaskId, &pItemRef, &pDueTime));
sl@0: 	
sl@0: 	// use local time for backwards compatibility
sl@0: 	aNextDue = nextDueTime.GetLocalTime();
sl@0: 	return res;
sl@0: 	}
sl@0: 
sl@0: 
sl@0: //private
sl@0: // TScheduleInfo.iEntryCount is number of schedule entries for time schedules
sl@0: // and number of conditions for condition based schedules.
sl@0: TInt RScheduler::GetScheduleInfo(const TInt aScheduleHandle, TScheduleInfo& aInfo, TTsTime& aNextDue)
sl@0: 	{	
sl@0: 	TPtr8 pInfo((TUint8*)&aInfo,sizeof(TScheduleInfo));//scheduler writes back info
sl@0: 	TPtr8 pDueTime((TUint8*)&aNextDue,sizeof(TTsTime));//scheduler writes back dueTime
sl@0: 	// get info for number of entries & tasks
sl@0: 	TInt res = SendReceive(EGetScheduleInfo, TIpcArgs(aScheduleHandle, &pInfo, &pDueTime));
sl@0: 	return res;
sl@0: 	}
sl@0: 	
sl@0: TInt RScheduler::GetTaskDataL(const TInt aScheduleHandle, 
sl@0: 								const TScheduleInfo& aInfo,
sl@0: 								CArrayFixFlat<TTaskInfo>& aTasks)
sl@0: 	{
sl@0: 	// resize array
sl@0: 	aTasks.ResizeL(aInfo.iTaskCount);
sl@0: 
sl@0: 	// get entries & taskrefs & flags
sl@0: 	TPBScheduleInfo pckgInfo(aInfo);
sl@0: 	TInt res = KErrNone;
sl@0: 	if (aInfo.iTaskCount > 0)
sl@0: 		{
sl@0: 		TPtr8 pTasks((TUint8*)&(aTasks.At(0)), aInfo.iTaskCount*sizeof(TTaskInfo));
sl@0: 		res = SendReceive(EGetTaskData, TIpcArgs(aScheduleHandle, &pckgInfo, &pTasks));
sl@0: 		}
sl@0: 	return res;
sl@0: 	}
sl@0: 
sl@0: TInt RScheduler::GetScheduleDataL(const TInt aScheduleHandle, 
sl@0: 								const TScheduleInfo& aInfo,
sl@0: 								CArrayFixFlat<TScheduleEntryInfo2>& aEntries)
sl@0: 	{
sl@0: 	// resize array	
sl@0: 	aEntries.ResizeL(aInfo.iEntryCount);
sl@0: 
sl@0: 	// get entries
sl@0: 	TPBScheduleInfo pckgInfo(aInfo);
sl@0: 	TPtr8 pEntries((TUint8*)&(aEntries.At(0)), aInfo.iEntryCount*sizeof(TScheduleEntryInfo2));
sl@0: 	return SendReceive(EGetTimeScheduleData, TIpcArgs(aScheduleHandle, &pckgInfo, &pEntries));
sl@0: 	}
sl@0: 	
sl@0: TInt RScheduler::GetScheduleDataL(const TInt aScheduleHandle, 
sl@0: 								const TScheduleInfo& aInfo,
sl@0: 								CArrayFixFlat<TTaskSchedulerCondition>& aConditions,
sl@0: 								TTsTime& aDefaultRunTime)
sl@0: 	{
sl@0: 	// resize arrays	
sl@0: 	aConditions.ResizeL(aInfo.iEntryCount);
sl@0: 
sl@0: 	// get entries
sl@0: 	TPtr8 pDefaultTime((TUint8*)&aDefaultRunTime,sizeof(TTsTime));//scheduler writes back defaultTime
sl@0: 	TPBScheduleInfo pckgInfo(aInfo);
sl@0: 	TPtr8 pEntries((TUint8*)&(aConditions.At(0)), aInfo.iEntryCount*sizeof(TTaskSchedulerCondition));
sl@0: 	return SendReceive(EGetConditionScheduleData, TIpcArgs(aScheduleHandle, &pckgInfo, &pEntries, &pDefaultTime));
sl@0: 	}	
sl@0: 	
sl@0: 
sl@0: #if defined (_DEBUG)
sl@0: /** 
sl@0: Marks the start of checking the current thread's heap.
sl@0: 
sl@0: This is used for debugging, and is only implemented in debug builds.
sl@0: 
sl@0: @return In debug builds, KErrNone, if successful, otherwise one of the other 
sl@0: system wide error codes. In release builds, KErrNone always.
sl@0: @see __UHEAP_MARK 
sl@0: @internalComponent
sl@0: */
sl@0: EXPORT_C TInt RScheduler::__DbgMarkHeap()
sl@0: 	{
sl@0: 	return SendReceive(ESchDbgMarkHeap);
sl@0: 	}
sl@0: 
sl@0: /** 
sl@0: Checks that the number of allocated cells on the current thread's heap is the 
sl@0: same as the specified value.
sl@0: 
sl@0: This is used for debugging, and is only implemented in debug builds.
sl@0: 
sl@0: @param aCount In debug builds, the number of heap cells expected to be allocated. 
sl@0: In release builds, this parameter is not used.
sl@0: @return In debug builds, KErrNone, if successful, otherwise one of the other 
sl@0: system wide error codes. In release builds, KErrNone always.
sl@0: @see __UHEAP_CHECK 
sl@0: @internalComponent
sl@0: */
sl@0: EXPORT_C TInt RScheduler::__DbgCheckHeap(TInt aCount)
sl@0: 	{
sl@0: 	return SendReceive(ESchDbgCheckHeap,TIpcArgs(aCount));
sl@0: 	}
sl@0: 
sl@0: /** 
sl@0: Marks the end of checking the current thread's heap.
sl@0: 
sl@0: This is used for debugging, and is only implemented in debug builds.
sl@0: 
sl@0: @param aCount In debug builds, the number of heap cells expected to remain 
sl@0: allocated. In release builds, this parameter is not used.
sl@0: @return In debug builds, KErrNone, if successful, otherwise one of the other 
sl@0: system wide error codes. In release builds, KErrNone always.
sl@0: @see __UHEAP_MARKENDC 
sl@0: @internalComponent
sl@0: */
sl@0: EXPORT_C TInt RScheduler::__DbgMarkEnd(TInt aCount)
sl@0: 	{
sl@0: 	return SendReceive(ESchDbgMarkEnd,TIpcArgs(aCount));
sl@0: 	}
sl@0: 
sl@0: /** 
sl@0: Simulates heap allocation failure.
sl@0: 
sl@0: This is used for debugging, and is only implemented in debug builds.
sl@0: 
sl@0: @param aCount In debug builds, the rate of failure - heap allocation fails 
sl@0: every aCount attempts. In release builds, this parameter is not used.
sl@0: @return In debug builds, KErrNone, if successful, otherwise one of the other 
sl@0: system wide error codes. In release builds, KErrNone always.
sl@0: @see __UHEAP_FAILNEXT 
sl@0: @internalComponent
sl@0: */
sl@0: EXPORT_C TInt RScheduler::__DbgFailNext(TInt aCount)
sl@0: 	{
sl@0: 	return SendReceive(ESchDbgFailNext,TIpcArgs(aCount));
sl@0: 	}
sl@0: 
sl@0: /** 
sl@0: Cancels simulated heap allocation failure for the current thread's heap.
sl@0: 
sl@0: This is used for debugging, and is only implemented in debug builds.
sl@0: 
sl@0: @return In debug builds, KErrNone, if successful, otherwise one of the other 
sl@0: system wide error codes. In release builds, KErrNone always.
sl@0: @see __UHEAP_RESET 
sl@0: @internalComponent
sl@0: */
sl@0: EXPORT_C TInt RScheduler::__DbgResetHeap()
sl@0: 	{
sl@0: 	return SendReceive(ESchDbgResetHeap);
sl@0: 	}
sl@0: 
sl@0: 
sl@0: /** 
sl@0: It tries to kill the server (schsvr).
sl@0: 
sl@0: This is used for debugging, and is only implemented in debug builds.
sl@0: 
sl@0: @return In debug builds, KErrNone, if successful, otherwise one of the other 
sl@0: system wide error codes. In release builds, KErrNone always. 
sl@0: @internalComponent
sl@0: */
sl@0: EXPORT_C TInt RScheduler::__FaultServer()
sl@0: 	{
sl@0: 	return SendReceive(ESchFaultServer);
sl@0: 	}
sl@0: 
sl@0: #else
sl@0: //release build exports empty versions of these for rel/deb compatibility
sl@0: EXPORT_C TInt RScheduler::__DbgMarkHeap()
sl@0: 	{
sl@0: 	return KErrNone;
sl@0: 	}
sl@0: 
sl@0: EXPORT_C TInt RScheduler::__DbgCheckHeap(TInt /*aCount*/)
sl@0: 	{
sl@0: 	return KErrNone;
sl@0: 	}
sl@0: 
sl@0: EXPORT_C TInt RScheduler::__DbgMarkEnd(TInt /*aCount*/)
sl@0: 	{
sl@0: 	return KErrNone;
sl@0: 	}
sl@0: 
sl@0: EXPORT_C TInt RScheduler::__DbgFailNext(TInt /*aCount*/)
sl@0: 	{
sl@0: 	return KErrNone;
sl@0: 	}
sl@0: 
sl@0: EXPORT_C TInt RScheduler::__DbgResetHeap()
sl@0: 	{
sl@0: 	return KErrNone;
sl@0: 	}
sl@0: 
sl@0: EXPORT_C TInt RScheduler::__FaultServer()
sl@0: 	{
sl@0: 	return KErrNone;
sl@0: 	}
sl@0: 
sl@0: #endif // _DEBUG
sl@0: 
sl@0: 
sl@0: 
sl@0: 
sl@0: