The Sync Manager API helps applications in scheduling their data sync operations.

Required Header

#include <sync_manager.h>

Overview

The Sync Manager provides APIs for managing the sync operations. Applications will call these APIs to schedule their sync operations. Sync Manager maintains sync requests from all the applications and invokes their respective callback methods to perform data synchronization operations.

Related Features

This API is related with the following features:

http://tizen.org/feature/account.sync

It is recommended to use features in your application for reliability.
You can check if a device supports the related features for this API by using System Information, and control your application's actions accordingly.
To ensure your application is running only 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	sync_manager_on_demand_sync_job (account_h account, const char sync_job_name, sync_option_e sync_option, bundle sync_job_user_data, int *sync_job_id)
	Requests Sync Manager to perform one time sync operation.
int	sync_manager_add_periodic_sync_job (account_h account, const char sync_job_name, sync_period_e sync_period, sync_option_e sync_option, bundle sync_job_user_data, int *sync_job_id)
	Requests Sync Manager to perform periodic sync operations.
int	sync_manager_add_data_change_sync_job (account_h account, const char sync_capability, sync_option_e sync_option, bundle sync_job_user_data, int *sync_job_id)
	Requests Sync Manager to perform sync operations whenever corresponding DB changed.
int	sync_manager_remove_sync_job (int sync_job_id)
	Requests Sync Manager to remove corresponding sync job id.
int	sync_manager_foreach_sync_job (sync_manager_sync_job_cb sync_job_cb, void *user_data)
	Requests Sync Manager to query corresponding sync request.
Typedefs
typedef bool(*	sync_manager_sync_job_cb )(account_h account, const char sync_job_name, const char sync_capability, int sync_job_id, bundle sync_job_user_data, void user_data)
	Called to get the information once for each sync job.
Defines
#define	SYNC_SUPPORTS_CAPABILITY_CALENDAR "http://tizen.org/sync/capability/calendar"
	This is calendar capability string.
#define	SYNC_SUPPORTS_CAPABILITY_CONTACT "http://tizen.org/sync/capability/contact"
	This is contact capability string.
#define	SYNC_SUPPORTS_CAPABILITY_IMAGE "http://tizen.org/sync/capability/image"
	This is image capability string.
#define	SYNC_SUPPORTS_CAPABILITY_VIDEO "http://tizen.org/sync/capability/video"
	This is video capability string.
#define	SYNC_SUPPORTS_CAPABILITY_SOUND "http://tizen.org/sync/capability/sound"
	This is sound capability string.
#define	SYNC_SUPPORTS_CAPABILITY_MUSIC "http://tizen.org/sync/capability/music"
	This is music capability string.

Define Documentation

#define SYNC_SUPPORTS_CAPABILITY_CALENDAR "http://tizen.org/sync/capability/calendar"

This is calendar capability string.

Since :: 2.4

Remarks:: If you want to receive notification about calendar DB change, add it through sync_manager_add_data_change_sync_job().

See also:: sync_manager_add_data_change_sync_job()

#define SYNC_SUPPORTS_CAPABILITY_CONTACT "http://tizen.org/sync/capability/contact"

This is contact capability string.

Since :: 2.4

Remarks:: If you want to receive notification about contact DB change, add it through sync_manager_add_data_change_sync_job().

See also:: sync_manager_add_data_change_sync_job()

#define SYNC_SUPPORTS_CAPABILITY_IMAGE "http://tizen.org/sync/capability/image"

This is image capability string.

Since :: 2.4

Remarks:: If you want to receive notification about media image DB change, add it through sync_manager_add_data_change_sync_job().

See also:: sync_manager_add_data_change_sync_job()

#define SYNC_SUPPORTS_CAPABILITY_MUSIC "http://tizen.org/sync/capability/music"

This is music capability string.

Since :: 2.4

Remarks:: If you want to receive notification about media music DB change, add it through sync_manager_add_data_change_sync_job().

See also:: sync_manager_add_data_change_sync_job()

#define SYNC_SUPPORTS_CAPABILITY_SOUND "http://tizen.org/sync/capability/sound"

This is sound capability string.

Since :: 2.4

Remarks:: If you want to receive notification about media sound DB change, add it through sync_manager_add_data_change_sync_job().

See also:: sync_manager_add_data_change_sync_job()

#define SYNC_SUPPORTS_CAPABILITY_VIDEO "http://tizen.org/sync/capability/video"

This is video capability string.

Since :: 2.4

Remarks:: If you want to receive notification about media video DB change, add it through sync_manager_add_data_change_sync_job().

See also:: sync_manager_add_data_change_sync_job()

Typedef Documentation

typedef bool(* sync_manager_sync_job_cb)(account_h account, const char *sync_job_name, const char *sync_capability, int sync_job_id, bundle *sync_job_user_data, void *user_data)

Called to get the information once for each sync job.

Since :: 2.4

Remarks:: Release account with account_destroy() after using it.

Release sync_job_user_data with bundle_free() after using it.

Parameters:

[in]	account	An account handle on which sync operation was requested or `NULL` in the case of accountless sync operation
[in]	sync_job_name	A string representing a sync job which has been operated or `NULL` in the case of data change sync operation
[in]	sync_capability	A string representing a sync job which has been operated because of data change or `NULL` in the case of on demand and periodic sync operation
[in]	sync_job_id	A unique value which can manage sync jobs
[in]	sync_job_user_data	User data which contains additional information related registered sync job or it can be `NULL` in the case of requesting without sync_job_user_data
[in]	user_data	User data which contains additional information related foreach job or it can be `NULL` in the case of querying without user_data

Returns:: true to continue with the next iteration of the loop, otherwise false to break out of the loop

Precondition:: sync_manager_foreach_sync_job() calls this callback.

See also:: sync_adapter_set_callbacks(); sync_manager_foreach_sync_job()

Enumeration Type Documentation

enum sync_error_e

Enumerations of error codes for Sync Manager APIs.

Since :: 2.4

Enumerator:

SYNC_ERROR_NONE	Successful
SYNC_ERROR_NOT_SUPPORTED	Not supported (Since 4.0)
SYNC_ERROR_OUT_OF_MEMORY	Out of memory
SYNC_ERROR_IO_ERROR	I/O error
SYNC_ERROR_PERMISSION_DENIED	Permission denied
SYNC_ERROR_ALREADY_IN_PROGRESS	Duplicate data
SYNC_ERROR_INVALID_OPERATION	Error in operation
SYNC_ERROR_INVALID_PARAMETER	Invalid parameter
SYNC_ERROR_QUOTA_EXCEEDED	Quota exceeded
SYNC_ERROR_UNKNOWN	Unknown error
SYNC_ERROR_SYSTEM	System error
SYNC_ERROR_SYNC_ADAPTER_NOT_FOUND	Sync adapter is not registered

enum sync_option_e

Enumerations for sync options of sync job request APIs.

Since :: 2.4

Enumerator:

SYNC_OPTION_NONE	Sync job will be operated normally
SYNC_OPTION_EXPEDITED	Sync job will be operated as soon as possible
SYNC_OPTION_NO_RETRY	Sync job will not be performed again when it fails

enum sync_period_e

Enumerations for time intervals of a periodic sync.

Since :: 2.4

Enumerator:

SYNC_PERIOD_INTERVAL_30MIN	Sync within 30 minutes
SYNC_PERIOD_INTERVAL_1H	Sync within 1 hour
SYNC_PERIOD_INTERVAL_2H	Sync within 2 hours
SYNC_PERIOD_INTERVAL_3H	Sync within 3 hours
SYNC_PERIOD_INTERVAL_6H	Sync within 6 hours
SYNC_PERIOD_INTERVAL_12H	Sync within 12 hours
SYNC_PERIOD_INTERVAL_1DAY	Sync within 1 day

Function Documentation

int sync_manager_add_data_change_sync_job	(	account_h	account,
		const char *	sync_capability,
		sync_option_e	sync_option,
		bundle *	sync_job_user_data,
		int *	sync_job_id
	)

Requests Sync Manager to perform sync operations whenever corresponding DB changed.

Since :: 2.4

Privilege Level:: public

Privilege:: http://tizen.org/privilege/calendar.read since 2.4

Privilege:: http://tizen.org/privilege/contact.read

Remarks:: Data change sync job can be added by using its capability. In the case of adding a sync job with same capability, it will replace previous setting with new one.

http://tizen.org/privilege/calendar.read is needed to add data change sync job for receiving notification with SYNC_SUPPORTS_CAPABILITY_CALENDAR. This capability is supported on Mobile profile only.

since 2.4 http://tizen.org/privilege/contact.read is needed to add data change sync job for receiving notification with SYNC_SUPPORTS_CAPABILITY_CONTACT.

Parameters:

[in]	account	An account handle on which sync operation was requested or `NULL` in the case of accountless sync operation
[in]	sync_capability	A string representing a sync job which will be operated whenever data change of this capability
[in]	sync_option	sync options determine an way to operate sync job and can be used as ORing.
[in]	sync_job_user_data	User data which contains additional information related registered sync job or it can be `NULL` in the case of requesting without sync_job_user_data
[out]	sync_job_id	A unique value which can manage sync jobs. The number of sync job id is limited as less than a hundred.

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

Return values:

SYNC_ERROR_NONE	Successful
SYNC_ERROR_NOT_SUPPORTED	Not supported
SYNC_ERROR_INVALID_PARAMETER	Invalid parameter
SYNC_ERROR_QUOTA_EXCEEDED	Quota exceeded
SYNC_ERROR_SYSTEM	Internal system error
SYNC_ERROR_SYNC_ADAPTER_NOT_FOUND	Sync adapter is not registered

Precondition:: This function requires calling below Sync Adapter's APIs by a service application before it is called.; Call sync_adapter_set_callbacks() before calling this function.

See also:: sync_manager_remove_sync_job(); sync_option_e

int sync_manager_add_periodic_sync_job	(	account_h	account,
		const char *	sync_job_name,
		sync_period_e	sync_period,
		sync_option_e	sync_option,
		bundle *	sync_job_user_data,
		int *	sync_job_id
	)

Requests Sync Manager to perform periodic sync operations.

Since :: 2.4

Privilege Level:: public

Privilege:: http://tizen.org/privilege/alarm.set

Remarks:: Sync job can be added with its name. In the case of adding periodic sync job with same sync job, it will replace previous setting with new one.

Parameters:

[in]	account	An account handle on which sync operation was requested or `NULL` in the case of accountless sync operation
[in]	sync_job_name	A string representing a sync job which will be operated with period interval
[in]	sync_period	Determines time interval of periodic sync. The periodic sync operation can be triggered in that interval, but it does not guarantee exact time. The minimum value is 30 minutes.
[in]	sync_option	sync options determine an way to operate sync job and can be used as ORing.
[in]	sync_job_user_data	User data which contains additional information related registered sync job or it can be `NULL` in the case of requesting without sync_job_user_data
[out]	sync_job_id	A unique value which can manage sync jobs. The number of sync job id is limited as less than a hundred.

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

Return values:

SYNC_ERROR_NONE	Successful
SYNC_ERROR_NOT_SUPPORTED	Not supported
SYNC_ERROR_INVALID_PARAMETER	Invalid parameter
SYNC_ERROR_QUOTA_EXCEEDED	Quota exceeded
SYNC_ERROR_SYSTEM	Internal system error
SYNC_ERROR_SYNC_ADAPTER_NOT_FOUND	Sync adapter is not registered

Precondition:: This function requires calling below Sync Adapter's APIs by a service application before it is called.; Call sync_adapter_set_callbacks() before calling this function.

See also:: sync_manager_remove_sync_job(); sync_option_e; sync_period_e

int sync_manager_foreach_sync_job	(	sync_manager_sync_job_cb	sync_job_cb,
		void *	user_data
	)

Requests Sync Manager to query corresponding sync request.

Since :: 2.4

Parameters:

[in]	sync_job_cb	A callback function for receiving the result of this API
[in]	user_data	User data which contains additional information related foreach job or `NULL` if do not want to transfer user data

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

Return values:

SYNC_ERROR_NONE	Successful
SYNC_ERROR_NOT_SUPPORTED	Not supported
SYNC_ERROR_INVALID_PARAMETER	Invalid parameter
SYNC_ERROR_SYSTEM	Internal system error

Precondition:: This function requires calling at least one of the below Sync Manager's APIs before it is called.; sync_manager_on_demand_sync_job(); sync_manager_add_periodic_sync_job(); sync_manager_add_data_change_sync_job()

See also:: sync_manager_sync_job_cb(); sync_manager_on_demand_sync_job(); sync_manager_add_periodic_sync_job(); sync_manager_add_data_change_sync_job()

int sync_manager_on_demand_sync_job	(	account_h	account,
		const char *	sync_job_name,
		sync_option_e	sync_option,
		bundle *	sync_job_user_data,
		int *	sync_job_id
	)

Requests Sync Manager to perform one time sync operation.

Since :: 2.4

Parameters:

[in]	account	An account handle on which sync operation was requested or `NULL` in the case of accountless sync operation
[in]	sync_job_name	A string representing a sync job which will be operated just one time
[in]	sync_option	sync options determine an way to operate sync job and can be used as ORing.
[in]	sync_job_user_data	User data which contains additional information related registered sync job or it can be `NULL` in the case of requesting without sync_job_user_data
[out]	sync_job_id	A unique value which can manage sync jobs. The number of sync job id is limited as less than a hundred.

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

Return values:

SYNC_ERROR_NONE	Successful
SYNC_ERROR_NOT_SUPPORTED	Not supported
SYNC_ERROR_INVALID_PARAMETER	Invalid parameter
SYNC_ERROR_QUOTA_EXCEEDED	Quota exceeded
SYNC_ERROR_SYSTEM	Internal system error
SYNC_ERROR_SYNC_ADAPTER_NOT_FOUND	Sync adapter is not registered

Precondition:: This function requires calling below Sync Adapter's APIs by a service application before it is called.; Call sync_adapter_set_callbacks() before calling this function.

See also:: sync_manager_remove_sync_job(); sync_option_e

int sync_manager_remove_sync_job ( int sync_job_id )

Requests Sync Manager to remove corresponding sync job id.

Since :: 2.4

Remarks:: sync_job_id can not be NULL.

Parameters:

[in] sync_job_id A unique value of each sync job, it can be used to search specific sync job and remove it

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

Return values:

SYNC_ERROR_NONE	Successful
SYNC_ERROR_NOT_SUPPORTED	Not supported
SYNC_ERROR_INVALID_PARAMETER	Invalid parameter
SYNC_ERROR_SYSTEM	Internal system error

Precondition:: This function requires calling at least one of the below Sync Manager's APIs before it is called.; sync_manager_on_demand_sync_job(); sync_manager_add_periodic_sync_job(); sync_manager_add_data_change_sync_job()

See also:: sync_manager_on_demand_sync_job(); sync_manager_add_periodic_sync_job(); sync_manager_add_data_change_sync_job()

Required Header

Overview

Related Features

Functions

Typedefs

Defines

Define Documentation

Typedef Documentation

Enumeration Type Documentation

Function Documentation