API description
Video Scheduler API (also known as
CCseSchedulerAPI) provides
an interface to CCseSchedulerEngine, which is used to:
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
AddScheduleCCseScheduledProgramCCseScheduledProgramsGetOverlappingSchedulesGetSchedulesByPluginUidGetSchedulesByTimeGetSchedulesByTypeRemoveScheduleTTime
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
CCseScheduledProgramCCseSchedulerAPICCseSchedulerPluginIF
Related APIs
CCseSchedulerAPICCseSchedulerEngine
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
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
CCseScheduledProgramCCseSchedulerAPICCseSchedulerEngineMCsePluginObserverPluginCompletedRunTaskL
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
CCseSchedulerAPICCseSchedulerEngineRunTaskL
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
CCseScheduledProgramCCseSchedulerEngine
Extensions to the API
There are no extensions.
Limitations of the API
There are no limitations.
Related APIs
AddScheduleCCseScheduledProgramCCseSchedulerAPIRemoveSchedule