Purpose

CCseSchedulerAPI provides an interface for creating scheduled events (for example, timed TV recording).

Constraints

This API is valid for all platforms running on Symbian^ 1 and S60 5.1 or later.

Classification and release information

This API is a Domain API and was first published in S60 release 5.1.

Emulator support

This API is supported in the WINS/WINSCW emulator environment, with the following exception:

  • Scheduler itself is not started in the startup phase. This means that some application needs to start scheduler before it works correctly and starts running scheduled events.

Related APIs
  • CCseSchedulerAPI

API description

Video Scheduler API (also known as CCseSchedulerAPI) provides an interface to CCseSchedulerEngine, which is used to:

  • Start a scheduled task at a specified time

  • Keep a schedule calendar and provide information about scheduled tasks to clients. This feature allows overlap handling between applications.

The main goal of CCseSchedulerEngine is to separate scheduling to its own service from applications and this way allow better component reuse. Schedule Engine allows applications to set up a scheduled task and search for existing scheduled tasks.

Schedule Engine cooperates with ScheduledTask plug-ins to execute scheduled tasks. Schedule plug-ins are provided by applications. Schedule Engine does not have information about what kind of task it is running; it simply ensures that the task starts at a given time. The task plug-in handles task execution. The client application can store plug-in specific binary data with scheduled task. Schedule Engine provides this data to the plug-in when it runs the scheduled task. Data can be application specific; Schedule Engine does not try to interpret this data.

Example tasks that can be scheduled through Video Scheduler API are:

  • Reminders: the application informs the user that a TV program is about to start. The user can choose to watch or record the program

  • Timed recording: TV recording starts at a given time and lasts for a predetermined length of time

  • Background TV program guide updates

  • Scheduled downloads or attempts to continue a failed or paused download

  • Housekeeping task

One very important feature is the search for overlapping schedules. This can be used to check schedule overlaps between applications so that the application can inform the user if he is trying to add overlapping recordings from different TV systems. The reaction to overlaps is the responsibility of the application. Note that CCseSchedulerEngine does not have information about which tasks can overlap with each other in and in which terminal setup.

CCseSchedulerEngine cannot ensure that the task does not take a longer time than informed by the application. It is assumed that applications provide honest information.

CCseSchedulerEngine allows the application to store binary data with scheduled task. CCseSchedulerEngine stores this data and provides it to the Scheduled Task plug-in when it starts the task. The Scheduled Task plug-in can, for example, start the application and send this data back to the application when running.

CCseSchedulerEngine uses Greenwich Mean Time (GMT) to store and handle scheduled tasks. The API assumes that all applications using Schedule Engine give times in GMT. If the client application displays the time to the user, the application must convert the time to local time.

CCseSchedulerEngine executes a given task only once. After that, the task is removed from the database. If the task is periodic, the task must reschedule itself.

Use cases

The two most important use cases of Video Scheduler API are adding a new schedule and removing an existing one. Adding a new schedule happens by creating CCseScheduledProgram data element, filling it with relevant information (of which the most important is the plug-in UID that is run at a given start time) and adding it to scheduler by calling AddSchedule. After AddSchedule call returns, the schedule ID can be found from CCseScheduledProgram that was given as a parameter. That ID can later be used to remove the existing schedule from scheduler by calling RemoveSchedule.

In addition to that, Video Scheduler API gives the user information schedules that have been added to it.

GetOverlappingSchedules gets two parameters, the first one is CCseScheduledProgram and the second one is an array of CCseScheduledPrograms. When the call finishes, the array is filled with CCseScheduledPrograms that are overlapping (timewise) with the first parameter.

GetSchedulesByPluginUid gets two parameters, the first one is TInt32 (plug-in UID of ECOM plug-in started when scheduled operation starts) and the second one is an array of CCseScheduledPrograms. When the call finishes, the array is filled with CCseScheduledPrograms that are using a given plug-in.

GetSchedulesByType gets two parameters, the first one is TInt32 (schedule type enumerator, see CCseScheduledProgram.h) and the second one is an array of CCseScheduledPrograms. When the call finishes, the array is filled with CCseScheduledPrograms that are of the same type.

GetSchedulesByTime gets three parameters, the first one is TTime, representing the start time, the second one is also TTime, representing the end time, and the third is an array of CCseScheduledPrograms. When the call finishes, the array is filled with CCseScheduledPrograms that are scheduled to start between the first two parameters (start and end times).

Related APIs
  • AddSchedule
  • CCseScheduledProgram
  • CCseScheduledPrograms
  • GetOverlappingSchedules
  • GetSchedulesByPluginUid
  • GetSchedulesByTime
  • GetSchedulesByType
  • RemoveSchedule
  • TTime

API class structure

Video Scheduler API does not require any specific inheritance from the application using it. That said, the scheduled operations are made by the CCseScheduledProgram -data element. Also the plug-in that is run at a given start time must inherit from CCseSchedulerPluginIF. The client connects to the interface by creating a new copy of CCseSchedulerAPI and deleting it after it is not needed anymore. An application using scheduler is not required to be running when the start time is reached. Scheduler itself stays alive if there are schedules for it to run. Also, when run in hardware, SchedulingEngine must start automatically during the phone boot if there are active schedules.

Related APIs
  • CCseScheduledProgram
  • CCseSchedulerAPI
  • CCseSchedulerPluginIF
Related APIs
  • CCseSchedulerAPI
  • CCseSchedulerEngine

Using the Video Scheduler API

For adding new schedules:

  • Create CCseSchedulerAPI (by calling NewL).

  • Create CCseScheduledProgram with relevant information.

  • Add CCseScheduledProgram to scheduler by calling AddSchedule and giving the newly-created CCseScheduledProgram as a parameter.

  • Delete CCseSchedulerAPI.

For removing existing schedules

  • Create CCseSchedulerAPI (by calling NewL).

  • Remove schedule by calling RemoveSchedule with the ID of the removed schedule as a parameter.

  • Delete CCseSchedulerAPI.

Running scheduled operation through Video Scheduler API

Firstly, the application using Video Scheduler API must create Scheduler API to access CCseSchedulerEngine:

CCseSchedulerApi* scheduler = CCseSchedulerApi::NewL()

The application then needs the schedule (with relevant information) to be set in scheduler through CCseSchedulerAPI:

CCseScheduledProgram* newSchedule = CCseScheduledProgram::NewL();
TTime start;
start.UniversalTime();
TTimeIntervalMinutes delay( 10 );
start += delay;
newSchedule->SetStartTime( start );
newSchedule->SetEndTime( start );
newSchedule->SetAppUid( APP_UID );
newSchedule->SetPluginUid( PLUGIN_UID );

The next step is to add the newly-created CCseScheduledProgram to CCseSchedulerEngine through CCseSchedulerAPI:

scheduler->AddSchedule( *newSchedule );

After this, both CCseScheduledProgram and CCseSchedulerAPI can be destroyed

delete newSchedule;
delete scheduler;

After ten minutes, CCseSchedulerEngine creates an ECOM plug-in matching the given UID (PLUGIN_UID in this example) and calls RunTaskL -method for it. CCseSchedulerEngine simply runs the plug-in and has no knowledge what the plug-in will do. The created schedule is automatically removed from CCseSchedulerEngine after the task is completed by calling PluginCompleted (defined in MCsePluginObserver that is given as a parameter in RunTaskL). After removing, if there are no more schedules to be run in CCseSchedulerEngine, it shuts itself down.

Related APIs
  • CCseScheduledProgram
  • CCseSchedulerAPI
  • CCseSchedulerEngine
  • MCsePluginObserver
  • PluginCompleted
  • RunTaskL

Error handling

In case of error, CCseSchedulerAPI returns generic error codes.

If the launching of ECOM plug-in fails (for example, the phone crashes when executing RunTaskL), CCseSchedulerEngine tries a total of three times to run it. After that, if it still fails it is not run again and is removed from CCseSchedulerEngine.

Related APIs
  • CCseSchedulerAPI
  • CCseSchedulerEngine
  • RunTaskL

Memory overhead

Memory consumption can vary greatly. Every CCseScheduledProgram has an internal dynamic binary buffer where the application using it can put application-specific information. In case of simple reminder use, the whole CCseSchedulerEngine takes around 3 KB.

Related APIs
  • CCseScheduledProgram
  • CCseSchedulerEngine

Extensions to the API

There are no extensions.

Limitations of the API

There are no limitations.

Related APIs
  • AddSchedule
  • CCseScheduledProgram
  • CCseSchedulerAPI
  • RemoveSchedule