Symbian
Symbian OS Library

SYMBIAN OS V9.3

[Index] [Spacer] [Previous] [Next]



Location: CSCH_CLI.H
Link against: schsvr.lib

Class RScheduler

class RScheduler : public RSessionBase;

Description

Client side interface to the Task Scheduler.

Derivation

Members

Defined in RScheduler:
Connect(), CreatePersistentSchedule(), CreatePersistentSchedule(), DeleteSchedule(), DeleteTask(), DisableSchedule(), EditSchedule(), EditSchedule(), EnableSchedule(), GetScheduleL(), GetScheduleL(), GetScheduleRefsL(), GetTaskDataSize(), GetTaskInfoL(), GetTaskInfoL(), GetTaskRefsL(), RScheduler(), Register(), ScheduleTask(), ScheduleTask(), ScheduleTask(), Version(), __DbgCheckHeap(), __DbgFailNext(), __DbgMarkEnd(), __DbgMarkHeap(), __DbgResetHeap(), __FaultServer()

Inherited from RHandleBase:
Attributes(), Close(), Duplicate(), FullName(), Handle(), HandleInfo(), Name(), SetHandle(), SetHandleNC(), iHandle

Inherited from RSessionBase:
CreateSession(), EAutoAttach, EExplicitAttach, Open(), Send(), SendReceive(), SetReturnedHandle(), ShareAuto(), ShareProtected(), TAttachMode


Construction and destruction


RScheduler()

IMPORT_C RScheduler();

Description

Default constructor.

[Top]


Member functions


Connect()

IMPORT_C TInt Connect();

Description

Connects a client to the Task Scheduler server, creating a session with that server.

Return value

TInt

KErrNone, if successful; otherwise one of the other system wide error codes.


Version()

IMPORT_C TVersion Version() const;

Description

Gets the client side version number.

Return value

TVersion

The version number.


Register()

IMPORT_C TInt Register(const TFileName &aFileName, const TInt aPriority);

Description

Registers a client with the Task Scheduler.

A client must register with the Task Scheduler before scheduling any tasks, but does not need to register just to create and edit schedules.

Parameters

const TFileName &aFileName

The name and full path of a program that encapsulates the client-specific knowledge for implementing tasks. On the emulator, the program should be a DLL; on an ARM processor, it should be an executable.

const TInt aPriority

A priority value.

Return value

TInt

KErrNone, if successful; otherwise one of the other system wide error codes.


CreatePersistentSchedule()

Capability: WriteDeviceData

IMPORT_C TInt CreatePersistentSchedule(TSchedulerItemRef &aRef, const CArrayFixFlat< TScheduleEntryInfo2 > &aEntryList);

Description

Creates a persistent time based schedule.

This schedule has no tasks associated with it but merely contains information about start and finish times.

Parameters

TSchedulerItemRef &aRef

Definition of the new schedule. On return this contains a valid handle to the newly created schedule.

const CArrayFixFlat< TScheduleEntryInfo2 > &aEntryList

The set of schedule entries that make up the new schedule.

Return value

TInt

KErrNone, if successful, KErrArgument if the condition array is empty, or an entry has an interval less than 1, KErrPermissionDenied if the client does not have WriteDeviceData capability. Otherwise one of the other system wide error codes.

See also:


DeleteSchedule()

Capability: Security policy note: Only clients with the same SID as the schedule creator, or WriteDeviceData capability can sucessfully call this API.

IMPORT_C TInt DeleteSchedule(const TInt aScheduleHandle) const;

Description

Deletes the specified schedule.

Note that a schedule cannot be deleted if there are tasks associated with it; the tasks must be explicitly deleted first.

Parameters

const TInt aScheduleHandle

The Id that identifies the schedule.

Return value

TInt

KErrNone if successful, KErrNotFound if there is no schedule with the specified Id, KErrArgument if there are outstanding tasks associated with the schedule, KErrPermissionDenied if the client does not have the same SID as the schedules creator or has WriteDeviceData capability, or any of the other system wide error codes.


DisableSchedule()

Capability: Security policy note: Only clients with the same SID as the schedule creator, or WriteDeviceData capability can sucessfully call this API.

IMPORT_C TInt DisableSchedule(const TInt aScheduleHandle) const;

Description

Disables the specified schedule.

Parameters

const TInt aScheduleHandle

The Id that identifies the schedule.

Return value

TInt

KErrNone if successful, KErrNotFound if there is no schedule with the specified Id, KErrPermissionDenied if the client does not have the same SID as the schedules creator or has WriteDeviceData capability, or any of the other system wide error codes.


EnableSchedule()

Capability: Security policy note: Only clients with the same SID as the schedule creator, or WriteDeviceData capability can sucessfully call this API.

IMPORT_C TInt EnableSchedule(const TInt aScheduleHandle) const;

Description

Enables the specified schedule.

Parameters

const TInt aScheduleHandle

The Id that identifies the schedule.

Return value

TInt

KErrNone if successful. KErrNotFound if there is no schedule with the specified Id, KErrPermissionDenied if the client does not have the same SID as the schedules creator or has WriteDeviceData capability, or any of the other system wide error codes.


EditSchedule()

Capability: Security policy note: Only clients with the same SID as the schedule creator, or WriteDeviceData capability can sucessfully call this API.

IMPORT_C TInt EditSchedule(const TInt aScheduleHandle, const CArrayFixFlat< TScheduleEntryInfo2 > &aEntryList);

Description

Changes a time based schedule.

Note that changing a schedule is implemented by supplying a replacement set of schedule entries.

Parameters

const TInt aScheduleHandle

The Id that identifies the schedule.

const CArrayFixFlat< TScheduleEntryInfo2 > &aEntryList

The set of schedule entries that will make up the new schedule.

Return value

TInt

KErrNone if successful, KErrNotFound if there is no schedule with the specified Id, KErrArgument if the schedule is not a time based one, KErrPermissionDenied if the client does not have the same SID as the schedules creator or has WriteDeviceData capability, or any of the other system wide error codes.

See also:


ScheduleTask()

Capability: Security policy note: Only clients with the same SID as the schedule creator, or WriteDeviceData capability can sucessfully call this API.

IMPORT_C TInt ScheduleTask(TTaskInfo &aTaskInfo, HBufC &aTaskData, const TInt aScheduleHandle);

Description

Adds a task to an existing persistent schedule.

Parameters

TTaskInfo &aTaskInfo

Information about the task to be added to the schedule. On return the task Id is written into this class.

HBufC &aTaskData

Data that is passed to the task on execution.

const TInt aScheduleHandle

The Id that identifies the schedule to be used.

Return value

TInt

KErrNone if successful, KErrNotFound if there is no schedule with the specified Id, KErrArgument if a task with a repeat vale other than 0 is being tried to be assigned to a condition based schedule, KErrPermissionDenied if the client does not have the same SID as the schedules creator or has WriteDeviceData capability, or any of the other system wide error codes.

Panic codes

CTaskScheduler

0 The client has not registered. The client must register before adding tasks to the schedule.


ScheduleTask()

IMPORT_C TInt ScheduleTask(TTaskInfo &aTaskInfo, HBufC &aTaskData, TSchedulerItemRef &aRef, const CArrayFixFlat< TScheduleEntryInfo2 > &aEntryList);

Description

Creates a new, transient, time based schedule and adds a task to it.

Note that a transient schedule is destroyed when the task is destroyed or power is lost.

Parameters

TTaskInfo &aTaskInfo

Information about the task to be added to the transient schedule. On return the task Id is written into this class.

HBufC &aTaskData

Data that is passed to the task on execution.

TSchedulerItemRef &aRef

Definition of the new transient schedule.

const CArrayFixFlat< TScheduleEntryInfo2 > &aEntryList

The set of schedule entries that make up the new transient schedule.

Return value

TInt

KErrNone, if successful, otherwise one of the other system wide error codes.

Panic codes

CTaskScheduler

0 The client has not registered. The client must register before adding tasks to the schedule.

See also:


DeleteTask()

Capability: Security policy note: Only clients with the same SID as the relevant schedule creator, or WriteDeviceData capability can sucessfully call this API.

IMPORT_C TInt DeleteTask(const TInt aTaskId) const;

Description

Deletes the specified task.

Parameters

const TInt aTaskId

The Id that identifies the task.

Return value

TInt

KErrNone if successful, KErrNotFound if there is no task with the specified Id, KErrPermissionDenied if the client does not have the same SID as the schedules creator or has WriteDeviceData capability, otherwise any of the other system wide error codes.


GetScheduleRefsL()

Capability: Security policy note: A call to this API will only retrieve schedules created with the caller's SID. If the caller has WriteDeviceData capability all schedules will be retrieved.

IMPORT_C TInt GetScheduleRefsL(CArrayFixFlat< TSchedulerItemRef > &aScheduleRefArray, const TScheduleFilter aFilter);

Description

Gets a list of all schedules, or a subset of schedules.

Parameters

CArrayFixFlat< TSchedulerItemRef > &aScheduleRefArray

On return, a populated array of schedule definitions. Note that populating the array could cause this function to leave because of an out of memory condition.

const TScheduleFilter aFilter

The schedule filter.

Return value

TInt

KErrNone if successful otherwise one of the other system wide error codes.

See also:


GetScheduleL()

Capability: Security policy note: Only clients with the same SID as the schedule creator, or WriteDeviceData capability can sucessfully call this API.

IMPORT_C TInt GetScheduleL(const TInt aScheduleHandle, TScheduleState2 &aState, CArrayFixFlat< TScheduleEntryInfo2 > &aEntries, CArrayFixFlat< TTaskInfo > &aTasks, TTsTime &aDueTime);

Description

Gets information relating to a specified time based schedule.

Parameters

const TInt aScheduleHandle

The Id that identifies the schedule.

TScheduleState2 &aState

On return, the state of the specified schedule.

CArrayFixFlat< TScheduleEntryInfo2 > &aEntries

On return, a populated array of schedule entries that make up the schedule. Note that populating the array could cause this function to leave because of an out of memory condition.

CArrayFixFlat< TTaskInfo > &aTasks

On return, a populated array of tasks associated with the schedule. Note that populating the array could cause this function to leave because of an out of memory condition.

TTsTime &aDueTime

On return, the time that the schedule is next due. This value may be local time or UTC based,dependent on the type of time used for schedule entries. Comparisons used within the scheduler to find the next due time are UTC based.

Return value

TInt

KErrNone if successful, KErrNotFound if there is no schedule with the specified Id, KErrArgument if the schedule is not a time based one, KErrPermissionDenied if the client does not have the same SID as the schedules creator or has WriteDeviceData capability, or any of the other system wide error codes.

See also:


GetTaskRefsL()

Capability: Security policy note: A call to this API will only retrieve tasks created with the caller's SID. If the caller has WriteDeviceData capability all tasks will be retrieved.

IMPORT_C TInt GetTaskRefsL(CArrayFixFlat< TSchedulerItemRef > &aTasks, const TScheduleFilter aScheduleFilter, const TTaskFilter aTaskFilter);

Description

Gets a list of all tasks, or a subset of tasks.

Note that if more than one client has supplied the same information when registering, then it is possible for a list of tasks to be returned, which the calling client has not scheduled.

Parameters

CArrayFixFlat< TSchedulerItemRef > &aTasks

On return, a populated array of schedule definitions. The schedule definitions are those whose associated tasks satisfy the selection criteria. Note that populating the array could cause this function to leave because of an out of memory condition.

const TScheduleFilter aScheduleFilter

The schedule filter.

const TTaskFilter aTaskFilter

The task filter.

Return value

TInt

KErrNone if successful otherwise one of the other system wide error codes.

See also:


GetTaskInfoL()

Capability: Security policy note: Only clients with the same SID as the relevant schedule creator, or WriteDeviceData capability can sucessfully call this API.

IMPORT_C TInt GetTaskInfoL(const TInt aTaskId, TTaskInfo &aTaskInfo, TPtr &aTaskData, TSchedulerItemRef &aRef, TTsTime &aNextDue);

Description

Gets information relating to a specified task.

Parameters

const TInt aTaskId

The Id that identifies the task.

TTaskInfo &aTaskInfo

On return, information about the task.

TPtr &aTaskData

On return, a pointer descriptor representing the data that is passed to the program to be executed. The caller must set up this pointer descriptor before calling the function. The required length of the descriptor can be found by calling GetTaskDataSize().

TSchedulerItemRef &aRef

On return, the associated schedule definition.

TTsTime &aNextDue

On return, the time that the task is next due. This value may be local time or UTC based. Comparisons used to find the next due time are based on UTC.

Return value

TInt

KErrNone, if successful. KErrNotFound, if there is no task with the specified Id, KErrPermissionDenied if the client does not have the same SID as the schedules creator or has WriteDeviceData capability.


GetTaskDataSize()

Capability: Security policy note: Only clients with the same SID as the relevant schedule creator, or WriteDeviceData capability can sucessfully call this API.

IMPORT_C TInt GetTaskDataSize(const TInt aTaskId, TInt &aSize);

Description

Gets the size of the data to be passed to the task's program.

This function should be called before calling GetTaskInfoL() so that a descriptor of the correct size can be set up.

Parameters

const TInt aTaskId

The Id that identifies the task.

TInt &aSize

The size of the task's data.

Return value

TInt

KErrNone if successful, KErrNotFound if there is no task with the specified Id, KErrPermissionDenied if the client does not have the same SID as the schedules creator or has WriteDeviceData capability, otherwise any of the other system wide error codes.


CreatePersistentSchedule()

Capability: WriteDeviceData

IMPORT_C TInt CreatePersistentSchedule(TSchedulerItemRef &aRef, const CArrayFixFlat< TScheduleEntryInfo > &aEntryList);

Description

Creates a persistent time based schedule.

This schedule has no tasks associated with it but merely contains information about start and finish times.

Parameters

TSchedulerItemRef &aRef

Definition of the new schedule. On return this contains a valid handle to the newly created schedule.

const CArrayFixFlat< TScheduleEntryInfo > &aEntryList

The set of schedule entries that make up the new schedule. Start times of all entries are assumed to be local time based.

Return value

TInt

KErrNone, if successful, KErrArgument if the condition array is empty, or an entry has an interval less than 1, KErrPermissionDenied if the client does not have WriteDeviceData capability. Otherwise one of the other system wide error codes.

See also:


EditSchedule()

Capability: Security policy note: Only clients with the same SID as the schedule creator, or WriteDeviceData capability can sucessfully call this API.

IMPORT_C TInt EditSchedule(const TInt aScheduleHandle, const CArrayFixFlat< TScheduleEntryInfo > &aEntryList);

Description

Changes a time based schedule.

Note that changing a schedule is implemented by supplying a replacement set of schedule entries.

Parameters

const TInt aScheduleHandle

The Id that identifies the schedule.

const CArrayFixFlat< TScheduleEntryInfo > &aEntryList

The set of schedule entries that will make up the new schedule. Start times of all entries are assumed to be local time based.

Return value

TInt

KErrNone if successful, KErrNotFound if there is no schedule with the specified Id, KErrArgument if the schedule is not a time based one, KErrPermissionDenied if the client does not have the same SID as the schedules creator or has WriteDeviceData capability, or any of the other system wide error codes.

See also:


ScheduleTask()

IMPORT_C TInt ScheduleTask(TTaskInfo &aTaskInfo, HBufC &aTaskData, TSchedulerItemRef &aRef, const CArrayFixFlat< TScheduleEntryInfo > &aEntryList);

Description

Creates a new, transient, time based schedule and adds a task to it.

Note that a transient schedule is destroyed when the task is destroyed or power is lost.

Parameters

TTaskInfo &aTaskInfo

Information about the task to be added to the transient schedule. On return the task Id is written into this class.

HBufC &aTaskData

Data that is passed to the task on execution.

TSchedulerItemRef &aRef

Definition of the new transient schedule.

const CArrayFixFlat< TScheduleEntryInfo > &aEntryList

The set of schedule entries that make up the new transient schedule. All entry start times are assumed to be local time based.

Return value

TInt

KErrNone, if successful, otherwise one of the other system wide error codes.

Panic codes

CTaskScheduler

0 The client has not registered. The client must register before adding tasks to the schedule.

See also:


GetScheduleL()

Capability: Security policy note: Only clients with the same SID as the schedule creator, or WriteDeviceData capability can sucessfully call this API.

IMPORT_C TInt GetScheduleL(const TInt aScheduleHandle, TScheduleState &aState, CArrayFixFlat< TScheduleEntryInfo > &aEntries, CArrayFixFlat< TTaskInfo > &aTasks, TTime &aDueTime);

Description

Gets information relating to a specified time based schedule.

Parameters

const TInt aScheduleHandle

The Id that identifies the schedule.

TScheduleState &aState

On return, the state of the specified schedule. On return, aState will have a local time based iDueTime member, regardless of whether the schedule is UTC or local time based. If the schedule is UTC based, the due time will be converted to a local time based value before returning.

CArrayFixFlat< TScheduleEntryInfo > &aEntries

On return, a populated array of schedule entries that make up the schedule. All entry start times returned will be local time based, though they may be UTC or local time based within the scheduler. The scheduler will convert any UTC based times to local time before returning. Note that populating the array could cause this function to leave because of an out of memory condition.

CArrayFixFlat< TTaskInfo > &aTasks

On return, a populated array of tasks associated with the schedule. Note that populating the array could cause this function to leave because of an out of memory condition.

TTime &aDueTime

On return, the time that the schedule is next due. This value will be local time based, regardless of whether the schedule is UTC or local time based. If the schedule is UTC based, the due time will be converted to a local time based value before returning.

Return value

TInt

KErrNone if successful, KErrNotFound if there is no schedule with the specified Id, KErrArgument if the schedule is not a time based one, KErrPermissionDenied if the client does not have the same SID as the schedules creator or has WriteDeviceData capability, or any of the other system wide error codes.

See also:


GetTaskInfoL()

Capability: Security policy note: Only clients with the same SID as the relevant schedule creator, or WriteDeviceData capability can sucessfully call this API.

IMPORT_C TInt GetTaskInfoL(const TInt aTaskId, TTaskInfo &aTaskInfo, TPtr &aTaskData, TSchedulerItemRef &aRef, TTime &aNextDue);

Description

Gets information relating to a specified task.

Parameters

const TInt aTaskId

The Id that identifies the task.

TTaskInfo &aTaskInfo

On return, information about the task.

TPtr &aTaskData

On return, a pointer descriptor representing the data that is passed to the program to be executed. The caller must set up this pointer descriptor before calling the function. The required length of the descriptor can be found by calling GetTaskDataSize().

TSchedulerItemRef &aRef

On return, the associated schedule definition.

TTime &aNextDue

On return, the time that the task is next due. This value will be local time based, regardless of whether the schedule is UTC or local time based. If the schedule is UTC based, the due time will be converted to a local time based value before returning.

Return value

TInt

KErrNone, if successful. KErrNotFound, if there is no task with the specified Id, KErrPermissionDenied if the client does not have the same SID as the schedules creator or has WriteDeviceData capability.


__DbgMarkHeap()

IMPORT_C TInt __DbgMarkHeap();

Description

Return value

TInt


__DbgCheckHeap()

IMPORT_C TInt __DbgCheckHeap(TInt aCount);

Description

Parameters

TInt aCount

Return value

TInt


__DbgMarkEnd()

IMPORT_C TInt __DbgMarkEnd(TInt aCount);

Description

Parameters

TInt aCount

Return value

TInt


__DbgFailNext()

IMPORT_C TInt __DbgFailNext(TInt aCount);

Description

Parameters

TInt aCount

Return value

TInt


__DbgResetHeap()

IMPORT_C TInt __DbgResetHeap();

Description

Return value

TInt


__FaultServer()

IMPORT_C TInt __FaultServer();

Description

Return value

TInt