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:

http://tizen.org/feature/network.wifi
http://tizen.org/feature/location.gps
http://tizen.org/feature/battery
http://tizen.org/feature/usb.host

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 featuring your application can be found from 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_info	The job_info handle
[in]	user_data	The 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_info	The job info handle
[in]	user_data	The 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_info	The job info handle
[in]	user_data	The user data passed from the callback registration function

See also:: job_scheduler_service_add(); job_service_callback_s

Enumeration Type Documentation

enum job_error_e

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

enum job_trigger_event_e

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

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.

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_info	The job info handle
[in]	event	The job trigger event

Returns:: 0 on success, otherwise a negative error value

Return values:

JOB_ERROR_NONE	Successful
JOB_ERROR_INVALID_PARAMETER	Invalid parameter
JOB_ERROR_IO_ERROR	IO error
JOB_ERROR_NOT_INITIALIZED	Not initialized
JOB_ERROR_NOT_SUPPORTED	Not supported
JOB_ERROR_ALREADY_EXIST	Already exist
JOB_ERROR_PERMISSION_DENIED	Permission 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_info	The job info handle
[out]	clone	If successful, a newly created job info handle will be returned

Returns:: 0 on success, otherwise a negative error value

Return values:

JOB_ERROR_NONE	Successful
JOB_ERROR_INVALID_PARAMETER	Invalid parameter
JOB_ERROR_OUT_OF_MEMORY	Out 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_info The job info handle to be newly created on success

Returns:: 0 on success, otherwise a negative error value

Return values:

JOB_ERROR_NONE	Successful
JOB_ERROR_INVALID_PARAMETER	Invalid parameter
JOB_ERROR_OUT_OF_MEMORY	Out 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_info The job info handle

Returns:: 0 on success, otherwise a negative error value

Return values:

JOB_ERROR_NONE	Successful
JOB_ERROR_INVALID_PARAMETER	Invalid 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_info	The job info handle
[out]	job_id	The ID of the job

Returns:: 0 on success, otherwise a negative error value

Return values:

JOB_ERROR_NONE	Successful
JOB_ERROR_INVALID_PARAMETER	Invalid parameter
JOB_ERROR_OUT_OF_MEMORY	Out of memory

See also:: job_scheduler_schedule()

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.

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_info	The job info handle
[in]	event	The job trigger event

Returns:: 0 on success, otherwise a negative error value

Return values:

JOB_ERROR_NONE	Successful
JOB_ERROR_INVALID_PARAMETER	Invalid 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_info	The job info handle
[in]	once	`true`, if the job does not need to be repeated

Returns:: 0 on success, otherwise a negative error value

Return values:

JOB_ERROR_NONE	Successful
JOB_ERROR_INVALID_PARAMETER	Invalid 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_info	The job info handle
[in]	interval	The periodic interval (in minutes)

Returns:: 0 on success, otherwise a negative error value

Return values:

JOB_ERROR_NONE	Successful
JOB_ERROR_INVALID_PARAMETER	Invalid 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_info	The job info handle
[in]	persistent	`true`, if the job needs to be automatically scheduled

Returns:: 0 on success, otherwise a negative error value

Return values:

JOB_ERROR_NONE	Successful
JOB_ERROR_INVALID_PARAMETER	Invalid 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_info	The job info handle
[in]	timeout	The timeout interval (ms)

Returns:: 0 on success, otherwise a negative error value

Return values:

JOB_ERROR_NONE	Successful
JOB_ERROR_INVALID_PARAMETER	Invalid 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_info	The job info handle
[in]	battery_not_low	`true`, the battery level must not be low.

Returns:: 0 on success, otherwise a negative error value

Return values:

JOB_ERROR_NONE	Successful
JOB_ERROR_INVALID_PARAMETER	Invalid parameter
JOB_ERROR_IO_ERROR	IO error
JOB_ERROR_NOT_INITIALIZED	Not initialized
JOB_ERROR_NOT_SUPPORTED	Not 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_info	The job info handle
[in]	charging	`true`, the battery must be charging.

Returns:: 0 on success, otherwise a negative error value

Return values:

JOB_ERROR_NONE	Successful
JOB_ERROR_INVALID_PARAMETER	Invalid parameter
JOB_ERROR_IO_ERROR	IO error
JOB_ERROR_NOT_INITIALIZED	Not initialized
JOB_ERROR_NOT_SUPPORTED	Not 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_info	The job info handle
[in]	wifi_connection	`true`, the WiFi must be connected.

Returns:: 0 on success, otherwise a negative error value

Return values:

JOB_ERROR_NONE	Successful
JOB_ERROR_INVALID_PARAMETER	Invalid parameter
JOB_ERROR_IO_ERROR	IO error
JOB_ERROR_NOT_INITIALIZED	Not initialized
JOB_ERROR_NOT_SUPPORTED	Not supported
JOB_ERROR_PERMISSION_DENIED	Permission 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_id The ID of the scheduled job

Returns:: 0 on success, otherwise a negative error value

Return values:

JOB_ERROR_NONE	Successful
JOB_ERROR_INVALID_PARAMETER	Invalid parameter
JOB_ERROR_NOT_INITIALIZED	Not initialized
JOB_ERROR_IO_ERROR	IO error
JOB_ERROR_NO_SUCH_JOB	No 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_NONE	Successful
JOB_ERROR_NOT_INITIALIZED	Not initialized
JOB_ERROR_IO_ERROR	IO 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_NONE	Successful
JOB_ERROR_NOT_INITIALIZED	Not 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]	callback	The iteration callback function
[in]	user_data	The user data to be passed to the callback function

Returns:: 0 on success, otherwise a negative error value

Return values:

JOB_ERROR_NONE	Successful
JOB_ERROR_INVALID_PARAMETER	Invalid parameter
JOB_ERROR_NOT_INITIALIZED	Not initialized
JOB_ERROR_NO_SUCH_JOB	No 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_NONE	Successful
JOB_ERROR_IO_ERROR	IO error
JOB_ERROR_OUT_OF_MEMORY	Out 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_id The ID of the scheduled job

Returns:: 0 on success, otherwise a negative error value

Return values:

JOB_ERROR_NONE	Successful
JOB_ERROR_INVALID_PARAMETER	Invalid parameter
JOB_ERROR_NOT_INITIALIZED	Not initialized
JOB_ERROR_NO_SUCH_JOB	No such job
JOB_ERROR_IO_ERROR	IO 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_info	The job info handle
[in]	job_id	The ID of the job

Returns:: 0 on success, otherwise a negative error value

Return values:

JOB_ERROR_NONE	Successful
JOB_ERROR_INVALID_PARAMETER	Invalid parameter
JOB_ERROR_NOT_INITIALIZED	Not initialized
JOB_ERROR_IO_ERROR	IO error
JOB_ERROR_ALREADY_EXIST	Already exist
JOB_ERROR_OUT_OF_MEMORY	Out of memory
JOB_ERROR_PERMISSION_DENIED	Permission 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_id	The ID of the job
[in]	callback	The set of callback functions to handle jobs
[in]	user_data	The user data to be passed to the callback function
[out]	job_service	The job service handle

Returns:: 0 on success, otherwise a negative error value

Return values:

JOB_ERROR_NONE	Successful
JOB_ERROR_INVALID_PARAMETER	Invalid parameter
JOB_ERROR_NOT_INITIALIZED	Not initialized
JOB_ERROR_OUT_OF_MEMORY	Out 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_notify_job_finished(); job_service_callback_s

int job_scheduler_service_remove ( job_service_h job_service )

Removes registered job service handler.

Since :: 4.0

Parameters:

[in] job_service The job service handle

Returns:: 0 on success, otherwise a negative error value

Return values:

JOB_ERROR_NONE	Successful
JOB_ERROR_INVALID_PARAMETER	Invalid parameter
JOB_ERROR_NOT_INITIALIZED	Not initialized

Precondition:: job_scheduler_init() MUST be called.

See also:: job_scheduler_init(); job_scheduler_service_add()

Required Header

Overview

Related Features

Functions

Typedefs

Typedef Documentation

Enumeration Type Documentation

Function Documentation