Tizen Native API  4.0
Functions | Typedefs | Defines
Sync Manager
Account

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 using features in 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 :
4.0
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 :
3.0
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 :
3.0
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 :
3.0
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 :
3.0
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 :
3.0
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 :
3.0
Remarks:
Release account with account_destroy() after using it.

Release sync_job_user_data with bundle_free() after using it.
Parameters:
[in]accountAn account handle on which sync operation was requested or NULL in the case of accountless sync operation
[in]sync_job_nameA string representing a sync job which has been operated or NULL in the case of data change sync operation
[in]sync_capabilityA 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_idA unique value which can manage sync jobs
[in]sync_job_user_dataUser 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_dataUser 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 :
3.0
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 :
3.0
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 :
3.0
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 :
3.0
Privilege Level:
public
Privilege:
http://tizen.org/privilege/calendar.read since
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 http://tizen.org/privilege/contact.read is needed to add data change sync job for receiving notification with SYNC_SUPPORTS_CAPABILITY_CONTACT.
Parameters:
[in]accountAn account handle on which sync operation was requested or NULL in the case of accountless sync operation
[in]sync_capabilityA string representing a sync job which will be operated whenever data change of this capability
[in]sync_optionsync options determine an way to operate sync job and can be used as ORing.
[in]sync_job_user_dataUser 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_idA 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_NONESuccessful
SYNC_ERROR_NOT_SUPPORTEDNot supported
SYNC_ERROR_INVALID_PARAMETERInvalid parameter
SYNC_ERROR_QUOTA_EXCEEDEDQuota exceeded
SYNC_ERROR_SYSTEMInternal system error
SYNC_ERROR_SYNC_ADAPTER_NOT_FOUNDSync 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 :
3.0
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]accountAn account handle on which sync operation was requested or NULL in the case of accountless sync operation
[in]sync_job_nameA string representing a sync job which will be operated with period interval
[in]sync_periodDetermines 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_optionsync options determine an way to operate sync job and can be used as ORing.
[in]sync_job_user_dataUser 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_idA 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_NONESuccessful
SYNC_ERROR_NOT_SUPPORTEDNot supported
SYNC_ERROR_INVALID_PARAMETERInvalid parameter
SYNC_ERROR_QUOTA_EXCEEDEDQuota exceeded
SYNC_ERROR_SYSTEMInternal system error
SYNC_ERROR_SYNC_ADAPTER_NOT_FOUNDSync 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 :
3.0
Parameters:
[in]sync_job_cbA callback function for receiving the result of this API
[in]user_dataUser 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_NONESuccessful
SYNC_ERROR_NOT_SUPPORTEDNot supported
SYNC_ERROR_INVALID_PARAMETERInvalid parameter
SYNC_ERROR_SYSTEMInternal 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 :
3.0
Parameters:
[in]accountAn account handle on which sync operation was requested or NULL in the case of accountless sync operation
[in]sync_job_nameA string representing a sync job which will be operated just one time
[in]sync_optionsync options determine an way to operate sync job and can be used as ORing.
[in]sync_job_user_dataUser 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_idA 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_NONESuccessful
SYNC_ERROR_NOT_SUPPORTEDNot supported
SYNC_ERROR_INVALID_PARAMETERInvalid parameter
SYNC_ERROR_QUOTA_EXCEEDEDQuota exceeded
SYNC_ERROR_SYSTEMInternal system error
SYNC_ERROR_SYNC_ADAPTER_NOT_FOUNDSync 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 :
3.0
Remarks:
sync_job_id can not be NULL.
Parameters:
[in]sync_job_idA 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_NONESuccessful
SYNC_ERROR_NOT_SUPPORTEDNot supported
SYNC_ERROR_INVALID_PARAMETERInvalid parameter
SYNC_ERROR_SYSTEMInternal 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()