Tizen Native API  5.0
Job scheduler

The Job scheduler API contains the job scheduler library.

Required Header

#include <job_scheduler.h>

Overview

It provides functions to define job-execution conditions. It improves the applications' performance and system health.

Related Features

Some job trigger events and some functions are related with the following features:

It is recommended to use features in your application for reliability. You can check if the device supports the related features for this API by using System Information, and control your application's actions accordingly. To ensure your application is only running on devices with specific features, please define the features in your manifest file using the manifest editor in the SDK. More details on using features in your application can be found in Feature Element.

Functions

int job_info_create (job_info_h *job_info)
 Creates the job info handle.
int job_info_destroy (job_info_h job_info)
 Destroys the job info handle and releases all its resources.
int job_info_set_periodic (job_info_h job_info, unsigned int interval)
 Sets the periodic interval of the job.
int job_info_set_persistent (job_info_h job_info, bool persistent)
 Sets the job to be automatically scheduled after the device reboots.
int job_info_set_once (job_info_h job_info, bool once)
 Sets the job not to be repeated.
int job_info_set_requirement_timeout (job_info_h job_info, unsigned int timeout)
 Sets the timeout interval of the requirements.
int job_info_set_requires_battery_not_low (job_info_h job_info, bool battery_not_low)
 Sets that the battery level must not be low to run the job.
int job_info_set_requires_charging (job_info_h job_info, bool charging)
 Sets that the battery must be charging to run the job.
int job_info_set_requires_wifi_connection (job_info_h job_info, bool wifi_connection)
 Sets that the WiFi must be connected to run the job.
int job_info_add_trigger_event (job_info_h job_info, job_trigger_event_e event)
 Adds the trigger event to the job info handle.
int job_info_remove_trigger_event (job_info_h job_info, job_trigger_event_e event)
 Removes the trigger event from the job info handle.
int job_info_get_job_id (job_info_h job_info, char **job_id)
 Gets the ID of the job.
int job_info_clone (job_info_h job_info, job_info_h *clone)
 Clones the given job_info handle.
int job_scheduler_init (void)
 Initializes the job scheduler.
int job_scheduler_finish (void)
 Finalizes the job scheduler.
int job_scheduler_schedule (job_info_h job_info, const char *job_id)
 Schedules the job.
int job_scheduler_cancel (const char *job_id)
 Cancels the scheduled job.
int job_scheduler_cancel_all (void)
 Cancels all scheduled jobs.
int job_scheduler_notify_job_finished (const char *job_id)
 Notifies that the job is finished.
int job_scheduler_foreach_job (job_scheduler_foreach_job_cb callback, void *user_data)
 Retrieves all scheduled jobs.
int job_scheduler_service_add (const char *job_id, job_service_callback_s *callback, void *user_data, job_service_h *job_service)
 Adds job service handler for receiving the information of the scheduled job.
int job_scheduler_service_remove (job_service_h job_service)
 Removes registered job service handler.

Typedefs

typedef struct job_info_s * job_info_h
 The job info handle.
typedef struct job_service_s * job_service_h
 The job service handle.
typedef void(* job_service_start_cb )(job_info_h job_info, void *user_data)
 Called when the job starts.
typedef void(* job_service_stop_cb )(job_info_h job_info, void *user_data)
 Called when the job stops.
typedef bool(* job_scheduler_foreach_job_cb )(job_info_h job_info, void *user_data)
 Called to retrieve the job information.

Typedef Documentation

typedef struct job_info_s* job_info_h

The job info handle.

Since :
4.0
typedef bool(* job_scheduler_foreach_job_cb)(job_info_h job_info, void *user_data)

Called to retrieve the job information.

Since :
4.0
Remarks:
The job_info must not be deallocated by the application.
Parameters:
[in]job_infoThe job_info handle
[in]user_dataThe user data passed from the foreach function
Returns:
true continue with the next iteration of the loop, otherwise false to break out of the loop
Precondition:
job_scheduler_foreach_job() will invoke this callback.
See also:
job_scheduler_foreach_job()
typedef struct job_service_s* job_service_h

The job service handle.

Since :
4.0
typedef void(* job_service_start_cb)(job_info_h job_info, void *user_data)

Called when the job starts.

Since :
4.0
Remarks:
The job_info MUST NOT be deallocated by the application. The job_info is managed by the platform and is valid only in the callback.
Parameters:
[in]job_infoThe job info handle
[in]user_dataThe user data passed from the callback registration function
See also:
job_scheduler_service_add()
job_service_callback_s
typedef void(* job_service_stop_cb)(job_info_h job_info, void *user_data)

Called when the job stops.

Since :
4.0
Remarks:
The job_info MUST not be deallocated by the application. The job_info is managed by the platform and is valid only in the callback.
Parameters:
[in]job_infoThe job info handle
[in]user_dataThe user data passed from the callback registration function
See also:
job_scheduler_service_add()
job_service_callback_s

Enumeration Type Documentation

Enumeration for job error.

Since :
4.0
Enumerator:
JOB_ERROR_NONE 

Successful

JOB_ERROR_INVALID_PARAMETER 

Invalid parameter

JOB_ERROR_OUT_OF_MEMORY 

Out of memory

JOB_ERROR_IO_ERROR 

IO error

JOB_ERROR_NOT_INITIALIZED 

Not initialized

JOB_ERROR_NO_SUCH_JOB 

No such job

JOB_ERROR_ALREADY_EXIST 

Already exist

JOB_ERROR_PERMISSION_DENIED 

Permission denied

JOB_ERROR_NOT_SUPPORTED 

Not supported

Enumeration for the job trigger events.

Since :
4.0
Enumerator:
JOB_TRIGGER_EVENT_BATTERY_LEVEL_EMPTY 

The battery level status: Empty

JOB_TRIGGER_EVENT_BATTERY_LEVEL_CRITICAL 

The battery level status: Critical

JOB_TRIGGER_EVENT_BATTERY_LEVEL_LOW 

The battery level status: Low

JOB_TRIGGER_EVENT_BATTERY_LEVEL_HIGH 

The battery level status: High

JOB_TRIGGER_EVENT_CHARGER_STATE_CONNECTED 

The charger state: Connected

JOB_TRIGGER_EVENT_CHARGER_STATE_DISCONNECTED 

The charger state: Disconnected

JOB_TRIGGER_EVENT_DISPLAY_STATE_ON 

The display state: On

JOB_TRIGGER_EVENT_DISPLAY_STATE_OFF 

The display state: Off

JOB_TRIGGER_EVENT_DISPLAY_STATE_DIM 

The display state: Dim

JOB_TRIGGER_EVENT_EARJACK_STATE_CONNECTED 

The earjack state: Connected

JOB_TRIGGER_EVENT_EARJACK_STATE_DISCONNECTED 

The earjack state: Disconnected

JOB_TRIGGER_EVENT_GPS_STATE_DISABLED 

The GPS state: Disabled

JOB_TRIGGER_EVENT_GPS_STATE_SEARCHING 

The GPS state: Searching

JOB_TRIGGER_EVENT_GPS_STATE_CONNECTED 

The GPS state: Connected

JOB_TRIGGER_EVENT_POWERSAVE_MODE_ENABLED 

The Power-saving mode: Enabled

JOB_TRIGGER_EVENT_POWERSAVE_MODE_DISABLED 

The Power-saving mode: Disabled

JOB_TRIGGER_EVENT_USB_STATE_CONNECTED 

The USB state: Connected

JOB_TRIGGER_EVENT_USB_STATE_DISCONNECTED 

The USB state: Disconnected

JOB_TRIGGER_EVENT_WIFI_STATE_DISABLED 

The WiFi state: Disabled
Privilege: http://tizen.org/privilege/network.get

JOB_TRIGGER_EVENT_WIFI_STATE_DISCONNECTED 

The WiFi state: Disconnected
Privilege: http://tizen.org/privilege/network.get

JOB_TRIGGER_EVENT_WIFI_STATE_CONNECTED 

The WiFi state: Connected
Privilege: http://tizen.org/privilege/network.get


Function Documentation

Adds the trigger event to the job info handle.

Since :
4.0
Remarks:
The periodic interval of the job info handle must be 0. If the interval of the job info handle is not 0, this function returns a negative error value. Regarding the event, the application may require the following privilege: http://tizen.org/privilege/network.get
If the application does not have the necessary privilege, this function returns JOB_ERROR_PERMISSION_DENIED. See job_trigger_event_e to find the corresponding privilege of each event.
Parameters:
[in]job_infoThe job info handle
[in]eventThe job trigger event
Returns:
0 on success, otherwise a negative error value
Return values:
JOB_ERROR_NONESuccessful
JOB_ERROR_INVALID_PARAMETERInvalid parameter
JOB_ERROR_IO_ERRORIO error
JOB_ERROR_NOT_INITIALIZEDNot initialized
JOB_ERROR_NOT_SUPPORTEDNot supported
JOB_ERROR_ALREADY_EXISTAlready exist
JOB_ERROR_PERMISSION_DENIEDPermission denied
Precondition:
job_scheduler_init() must be called.
See also:
job_scheduler_init()
job_info_remove_trigger_event()
job_trigger_event_e
int job_info_clone ( job_info_h  job_info,
job_info_h clone 
)

Clones the given job_info handle.

Since :
4.0
Remarks:
The newly created job_info handle must be released by using job_info_destroy().
Parameters:
[in]job_infoThe job info handle
[out]cloneIf successful, a newly created job info handle will be returned
Returns:
0 on success, otherwise a negative error value
Return values:
JOB_ERROR_NONESuccessful
JOB_ERROR_INVALID_PARAMETERInvalid parameter
JOB_ERROR_OUT_OF_MEMORYOut of memory
See also:
job_info_destroy()
int job_info_create ( job_info_h job_info)

Creates the job info handle.

Since :
4.0
Remarks:
The job_info must be released by using job_info_destroy(). The job will be started by the periodic interval or the trigger events.
Parameters:
[out]job_infoThe job info handle to be newly created on success
Returns:
0 on success, otherwise a negative error value
Return values:
JOB_ERROR_NONESuccessful
JOB_ERROR_INVALID_PARAMETERInvalid parameter
JOB_ERROR_OUT_OF_MEMORYOut of memory
See also:
job_info_destroy()
job_info_set_periodic()
job_info_add_trigger_event()
int job_info_destroy ( job_info_h  job_info)

Destroys the job info handle and releases all its resources.

Since :
4.0
Parameters:
[in]job_infoThe job info handle
Returns:
0 on success, otherwise a negative error value
Return values:
JOB_ERROR_NONESuccessful
JOB_ERROR_INVALID_PARAMETERInvalid parameter
See also:
job_info_create()
int job_info_get_job_id ( job_info_h  job_info,
char **  job_id 
)

Gets the ID of the job.

Since :
4.0
Remarks:
The job_info must be scheduled by using job_scheduler_schedule(). If the job_info is not scheduled, this function returns a negative error value. The job_id must be released by using free().
Parameters:
[in]job_infoThe job info handle
[out]job_idThe ID of the job
Returns:
0 on success, otherwise a negative error value
Return values:
JOB_ERROR_NONESuccessful
JOB_ERROR_INVALID_PARAMETERInvalid parameter
JOB_ERROR_OUT_OF_MEMORYOut of memory
See also:
job_scheduler_schedule()

Removes the trigger event from the job info handle.

Since :
4.0
Remarks:
The periodic interval of the job info handle must be 0. If the interval of the job info handle is not 0, this function returns a negative error value.
Parameters:
[in]job_infoThe job info handle
[in]eventThe job trigger event
Returns:
0 on success, otherwise a negative error value
Return values:
JOB_ERROR_NONESuccessful
JOB_ERROR_INVALID_PARAMETERInvalid parameter
See also:
job_info_add_trigger_event()
job_trigger_event_e
int job_info_set_once ( job_info_h  job_info,
bool  once 
)

Sets the job not to be repeated.

Since :
4.0
Remarks:
If it's a persistent job, setting it to a one-time job returns a negative error value on scheduling by using job_scheduler_schedule().
Parameters:
[in]job_infoThe job info handle
[in]oncetrue, if the job does not need to be repeated
Returns:
0 on success, otherwise a negative error value
Return values:
JOB_ERROR_NONESuccessful
JOB_ERROR_INVALID_PARAMETERInvalid parameter
See also:
job_info_set_persistent()
job_scheduler_schedule()
int job_info_set_periodic ( job_info_h  job_info,
unsigned int  interval 
)

Sets the periodic interval of the job.

Since :
4.0
Remarks:
The platform does not guarantee the accuracy of the given interval for minimizing the wakeups of the device. Thus you should not rely on it for timing. If this function is called after adding the job trigger events by using job_info_add_trigger_event(), the function returns a negative error value.
Parameters:
[in]job_infoThe job info handle
[in]intervalThe periodic interval (in minutes)
Returns:
0 on success, otherwise a negative error value
Return values:
JOB_ERROR_NONESuccessful
JOB_ERROR_INVALID_PARAMETERInvalid parameter
See also:
job_info_destroy()
int job_info_set_persistent ( job_info_h  job_info,
bool  persistent 
)

Sets the job to be automatically scheduled after the device reboots.

Since :
4.0
Remarks:
If it's a one-time job, setting it to a persistent job returns a negative error value on scheduling by using job_scheduler_schedule().
Parameters:
[in]job_infoThe job info handle
[in]persistenttrue, if the job needs to be automatically scheduled
Returns:
0 on success, otherwise a negative error value
Return values:
JOB_ERROR_NONESuccessful
JOB_ERROR_INVALID_PARAMETERInvalid parameter
See also:
job_info_set_once()
job_scheduler_schedule()
int job_info_set_requirement_timeout ( job_info_h  job_info,
unsigned int  timeout 
)

Sets the timeout interval of the requirements.

Since :
4.0
Remarks:
If the requirements are not satisfied within the timeout value, the job does not start.
Parameters:
[in]job_infoThe job info handle
[in]timeoutThe timeout interval (ms)
Returns:
0 on success, otherwise a negative error value
Return values:
JOB_ERROR_NONESuccessful
JOB_ERROR_INVALID_PARAMETERInvalid parameter
int job_info_set_requires_battery_not_low ( job_info_h  job_info,
bool  battery_not_low 
)

Sets that the battery level must not be low to run the job.

Since :
4.0
Parameters:
[in]job_infoThe job info handle
[in]battery_not_lowtrue, the battery level must not be low.
Returns:
0 on success, otherwise a negative error value
Return values:
JOB_ERROR_NONESuccessful
JOB_ERROR_INVALID_PARAMETERInvalid parameter
JOB_ERROR_IO_ERRORIO error
JOB_ERROR_NOT_INITIALIZEDNot initialized
JOB_ERROR_NOT_SUPPORTEDNot supported
Precondition:
job_scheduler_init() must be called.
See also:
job_scheduler_init()
int job_info_set_requires_charging ( job_info_h  job_info,
bool  charging 
)

Sets that the battery must be charging to run the job.

Since :
4.0
Parameters:
[in]job_infoThe job info handle
[in]chargingtrue, the battery must be charging.
Returns:
0 on success, otherwise a negative error value
Return values:
JOB_ERROR_NONESuccessful
JOB_ERROR_INVALID_PARAMETERInvalid parameter
JOB_ERROR_IO_ERRORIO error
JOB_ERROR_NOT_INITIALIZEDNot initialized
JOB_ERROR_NOT_SUPPORTEDNot supported
Precondition:
job_scheduler_init() must be called.
See also:
job_scheduler_init()
int job_info_set_requires_wifi_connection ( job_info_h  job_info,
bool  wifi_connection 
)

Sets that the WiFi must be connected to run the job.

Since :
4.0
Privilege Level:
public
Privilege:
http://tizen.org/privilege/network.get
Parameters:
[in]job_infoThe job info handle
[in]wifi_connectiontrue, the WiFi must be connected.
Returns:
0 on success, otherwise a negative error value
Return values:
JOB_ERROR_NONESuccessful
JOB_ERROR_INVALID_PARAMETERInvalid parameter
JOB_ERROR_IO_ERRORIO error
JOB_ERROR_NOT_INITIALIZEDNot initialized
JOB_ERROR_NOT_SUPPORTEDNot supported
JOB_ERROR_PERMISSION_DENIEDPermission denied
Precondition:
job_scheduler_init() must be called.
See also:
job_scheduler_init()
int job_scheduler_cancel ( const char *  job_id)

Cancels the scheduled job.

Since :
4.0
Parameters:
[in]job_idThe ID of the scheduled job
Returns:
0 on success, otherwise a negative error value
Return values:
JOB_ERROR_NONESuccessful
JOB_ERROR_INVALID_PARAMETERInvalid parameter
JOB_ERROR_NOT_INITIALIZEDNot initialized
JOB_ERROR_IO_ERRORIO error
JOB_ERROR_NO_SUCH_JOBNo such job
Precondition:
job_scheduler_init() MUST be called.
See also:
job_scheduler_init()
int job_scheduler_cancel_all ( void  )

Cancels all scheduled jobs.

Since :
4.0
Returns:
0 on success, otherwise a negative error value
Return values:
JOB_ERROR_NONESuccessful
JOB_ERROR_NOT_INITIALIZEDNot initialized
JOB_ERROR_IO_ERRORIO error
Precondition:
job_scheduler_init() MUST be called.
See also:
job_scheduler_init()
int job_scheduler_finish ( void  )

Finalizes the job scheduler.

Since :
4.0
Returns:
0 on success, otherwise a negative error value
Return values:
JOB_ERROR_NONESuccessful
JOB_ERROR_NOT_INITIALIZEDNot initialized
See also:
job_scheduler_init()
int job_scheduler_foreach_job ( job_scheduler_foreach_job_cb  callback,
void *  user_data 
)

Retrieves all scheduled jobs.

Since :
4.0
Parameters:
[in]callbackThe iteration callback function
[in]user_dataThe user data to be passed to the callback function
Returns:
0 on success, otherwise a negative error value
Return values:
JOB_ERROR_NONESuccessful
JOB_ERROR_INVALID_PARAMETERInvalid parameter
JOB_ERROR_NOT_INITIALIZEDNot initialized
JOB_ERROR_NO_SUCH_JOBNo scheduled jobs
Precondition:
job_scheduler_init() MUST be called.
See also:
job_scheduler_init()
int job_scheduler_init ( void  )

Initializes the job scheduler.

Since :
4.0
Returns:
0 on success, otherwise a negative error value
Return values:
JOB_ERROR_NONESuccessful
JOB_ERROR_IO_ERRORIO error
JOB_ERROR_OUT_OF_MEMORYOut of memory
See also:
job_scheduler_finish()
int job_scheduler_notify_job_finished ( const char *  job_id)

Notifies that the job is finished.

Since :
4.0
Remarks:
If the job has been launched, the system kept awake for a while. It is highly recommended to notify that the job is done, the system thus knows it does not need to be kept awake.
Parameters:
[in]job_idThe ID of the scheduled job
Returns:
0 on success, otherwise a negative error value
Return values:
JOB_ERROR_NONESuccessful
JOB_ERROR_INVALID_PARAMETERInvalid parameter
JOB_ERROR_NOT_INITIALIZEDNot initialized
JOB_ERROR_NO_SUCH_JOBNo such job
JOB_ERROR_IO_ERRORIO error
Precondition:
job_scheduler_init() MUST be called.
See also:
job_scheduler_init()
int job_scheduler_schedule ( job_info_h  job_info,
const char *  job_id 
)

Schedules the job.

Since :
4.0
Privilege Level:
public
Privilege:
http://tizen.org/privilege/appmanager.launch
Parameters:
[in]job_infoThe job info handle
[in]job_idThe ID of the job
Returns:
0 on success, otherwise a negative error value
Return values:
JOB_ERROR_NONESuccessful
JOB_ERROR_INVALID_PARAMETERInvalid parameter
JOB_ERROR_NOT_INITIALIZEDNot initialized
JOB_ERROR_IO_ERRORIO error
JOB_ERROR_ALREADY_EXISTAlready exist
JOB_ERROR_OUT_OF_MEMORYOut of memory
JOB_ERROR_PERMISSION_DENIEDPermission denied
Precondition:
job_scheduler_init() MUST be called.
See also:
job_scheduler_init()
job_info_create()
int job_scheduler_service_add ( const char *  job_id,
job_service_callback_s callback,
void *  user_data,
job_service_h job_service 
)

Adds job service handler for receiving the information of the scheduled job.

Since :
4.0
Remarks:
The job_service handle should be released using job_scheduler_service_remove().
Parameters:
[in]job_idThe ID of the job
[in]callbackThe set of callback functions to handle jobs
[in]user_dataThe user data to be passed to the callback function
[out]job_serviceThe job service handle
Returns:
0 on success, otherwise a negative error value
Return values:
JOB_ERROR_NONESuccessful
JOB_ERROR_INVALID_PARAMETERInvalid parameter
JOB_ERROR_NOT_INITIALIZEDNot initialized
JOB_ERROR_OUT_OF_MEMORYOut of memory
Precondition:
job_scheduler_init() MUST be called.
See also:
job_scheduler_init()
job_scheduler_service_remove()
job_service_start_cb()
job_service_stop_cb()
job_scheduler_job_finished()
job_service_callback_s

Removes registered job service handler.

Since :
4.0
Parameters:
[in]job_serviceThe job service handle
Returns:
0 on success, otherwise a negative error value
Return values:
JOB_ERROR_NONESuccessful
JOB_ERROR_INVALID_PARAMETERInvalid parameter
JOB_ERROR_NOT_INITIALIZEDNot initialized
Precondition:
job_scheduler_init() MUST be called.
See also:
job_scheduler_init()
job_scheduler_service_add()