Job Scheduler
PUBLISHED
The Job Scheduler API is specific to service applications. Using the Job Scheduler API, service applications can register a background task with trigger conditions. The service application is launched when the trigger condition occurs and can perform the background task.
The main features of the Job Scheduler API include:
- Registering a job service handler
To register the job service handler, use the
job_scheduler_service_add()
function to register the job service handler. When the job is triggered, thejob_service_start_cb()
andjob_service_stop_cb()
callbacks are invoked and you can handle the background task in the callbacks. - Creating and scheduling a job
To add the job to the scheduling list, use the
job_scheduler_schedule()
function. You can create the job and set job-execution conditions as trigger events or schedule it for a specific time. - Retrieving all scheduled jobs
To retrieve all scheduled jobs, use the
job_scheduler_foreach_job()
function. As a result, thejob_scheduler_foreach_job_cb
callback is invoked and you can get the scheduled job.
Prerequisites
To enable your application to use the job scheduler functionality:
-
To use the Job Scheduler API (in mobile [1] and wearable [2] applications), the application has to request permission. Add the following privilege to the
tizen-manifest.xml
file:<privileges> <privilege>http://tizen.org/privilege/appmanager.launch</privilege> </privileges>
-
To use the functions and trigger events of the Job Scheduler API, include the
<job_scheduler.h>
header file in your application:#include <job_scheduler.h>
Registering a Job Service Handler
To handle the scheduled job, register a job service handler:
-
To use the Job Scheduler API, initialize the job scheduler:
ret = job_scheduler_init(); if (ret != JOB_ERROR_NONE) dlog_print(DLOG_ERROR, LOG_TAG, "Failed to initialize job scheduler. err = %d", ret);
-
Create the callbacks for handling the job:
static void job_service_start(job_info_h job_info, void *user_data) { int ret; char *job_id = NULL; ret = job_info_get_job_id(job_info, &job_id); if (ret != JOB_ERROR_NONE) { dlog_print(DLOG_ERROR, LOG_TAG, "Failed to get job id. err = %d", ret); return; } dlog_print(DLOG_INFO, LOG_TAG, "[START] job ID: %s", job_id); free(job_id); } static void job_service_stop(job_info_h job_info, void *user_data) { int ret; char *job_id = NULL; ret = job_info_get_job_id(job_info, &job_id); if (ret != JOB_ERROR_NONE) { dlog_print(DLOG_ERROR, LOG_TAG, "Failed to get job id. err = %d", ret); return; } dlog_print(DLOG_INFO, LOG_TAG, "[STOP] job ID: %s", job_id); free(job_id); }
When the trigger condition occurs, the
job_service_start()
function is invoked. And then, thejob_service_stop()
function is invoked. The service application can then perform the background task. -
Register the job service handler to handle the job when the job is triggered.
job_service_callbacks callbacks = { job_service_start, job_service_stop }; job_service_h job_service = NULL; ret = job_scheduler_service_add("TestJob", &callbacks, NULL, &job_service); if (ret != JOB_ERROR_NONE) dlog_print(DLOG_ERROR, LOG_TAG, "Failed to add job service handler. err = %d", ret);
Creating and Scheduling a Job
To schedule a job, create and schedule the job:
-
To use the Job Scheduler API, initialize the job scheduler:
ret = job_scheduler_init(); if (ret != JOB_ERROR_NONE) dlog_print(DLOG_ERROR, LOG_TAG, "Failed to initialize job scheduler. err = %d", ret);
-
Create a job
The following example shows how to create a job with a trigger condition when the battery level is critical:
job_info_h job_info = NULL; ret = job_info_create(&job_info); if (ret != JOB_ERROR_NONE) dlog_print(DLOG_ERROR, LOG_TAG, "Failed to create job info. err = %d", ret); ret = job_info_add_trigger_event(job_info, JOB_TRIGGER_EVENT_BATTERY_LEVEL_CRITICAL); if (ret != JOB_ERROR_NONE) dlog_print(DLOG_ERROR, LOG_TAG, "Failed to add trigger event. err = %d", ret);
When the battery status is at critical level, the job is triggered.
The following example shows how to create a periodic job with a specific requirement. Example, the interval is set to 20 minutes and the requirement is that the battery status must not be low:
job_info_h job_info = NULL; ret = job_info_create(&job_info); if (ret != JOB_ERROR_NONE) dlog_print(DLOG_ERROR, LOG_TAG, "Failed to create job info. err = %d", ret); ret = job_info_set_periodic(job_info, 20); if (ret != JOB_ERROR_NONE) dlog_print(DLOG_ERROR, LOG_TAG, "Failed to set periodic interval. err = %d", ret); ret = job_info_set_requires_battery_now_low(job_info, true); if (ret != JOB_ERROR_NONE) dlog_print(DLOG_ERROR, LOG_TAG, "Failed to set the requirement. err = %d", ret);
Note The platform does not guarantee the accuracy of the given interval for minimizing the wakeup of the device. Hence, you must not rely on the platform for timing. -
Schedule the job:
ret = job_scheduler_schedule(job_info, "TestJob"); if (ret != JOB_ERROR_NONE) dlog_print(DLOG_ERROR, LOG_TAG, "Failed to schedule the job. err = %d", ret);
-
When no longer needed, release the job info:
ret = job_info_destroy(job_info); if (ret != JOB_ERROR_NONE) dlog_print(DLOG_ERROR, LOG_TAG, "Failed to destroy job info. err = %d", ret);
Retrieving all Scheduled Jobs
To retrieve all scheduled jobs:
-
To use the Job Scheduler API, initialize the job scheduler:
ret = job_scheduler_init(); if (ret != JOB_ERROR_NONE) dlog_print(DLOG_ERROR, LOG_TAG, "Failed to initialize job scheduler. err = %d", ret);
-
Create a callback for retrieving the scheduled job:
static bool foreach_job(job_info_h job_info, void *user_data) { int ret; char *job_id = NULL; ret = job_info_get_job_id(job_info, &job_id); if (ret != JOB_ERROR_NONE) { dlog_print(DLOG_ERROR, LOG_TAG, "Failed to get job ID, err = %d", ret); return false; } dlog_print(DLOG_INFO, LOG_TAG, "Job ID: %s", job_id); free(job_id); return true; }
-
Retrieve all the scheduled jobs:
ret = job_scheduler_foreach_job(foreach_job, NULL); if (ret != JOB_ERROR_NONE) dlog_print(DLOG_ERROR, LOG_TAG, "Failed to retrieve jobs. err = %d", ret);