Sync Manager: Scheduling for Application Data Syncing

This tutorial demonstrates how you can manage the data synchronizing schedule and control sync operations manually or periodically.

This feature is supported in mobile applications only. To use the Sync Manager API features, the service application must first set the callback functions. A UI application cannot initialize and set callbacks through the Sync Adapter API. Instead, the UI application must call the Sync Manager API to request sync operations.

Warm-up

Become familiar with the Sync Manager API basics by learning about:

• Initializing the On-demand Sync

  Add an on-demand sync job for a one-time operation.

• Initializing the Periodic Sync

  Add a periodic sync job with a recurring cycle.

• Initializing the Data Change Sync

  Add a data change sync job for receiving a notification whenever a specific database change occurs.

• Initializing the ForEach Sync

  Iterate all the registered sync jobs for managing them more efficiently.

• Sync adapter
  • Setting the Callback Functions

    Set the client callback functions for starting or canceling sync operations.

Initializing the On-demand Sync

To inform a service application of the time to operate a one-time sync job:

1. Set the sync adapter callbacks in the service application:

   #include <sync_adapter.h>
   
   int result;
   result = sync_adapter_set_callbacks(on_start_cb, on_cancel_cb);
   

2. To use the functions and data types of the Sync Manager API, include the <sync_manager.h> header file in your UI application:

   #include <sync_manager.h>
   

3. If you want to use an account, create the account and obtain the parameters that are used to call the sync_manager_on_demand_sync_job() function.

   For more information, see Creating and Managing an Account and Managing and Using the Bundle Content.

   account_h account = NULL;
   int account_id = -1;
   
   account_create(&account);
   account_set_user_name(account, "test_name");
   account_set_email_address(account, "test_email@samsung.com");
   account_set_package_name(account, "data-sync-module");
   account_set_sync_support(account, ACCOUNT_SUPPORTS_SYNC);
   account_insert_to_db(account, &account_id);
   
   const char *sync_job_name = "on_demand_sync_job";
   
   bundle *sync_job_user_data = NULL;
   sync_job_user_data = bundle_create();
   bundle_add_str(sync_job_user_data, "str", "String sync_job_user_data sample.");
   
   int sync_job_id = -1;
   

4. Add an on-demand sync job:

   result = sync_manager_on_demand_sync_job(account, sync_job_name, SYNC_OPTION_NONE, 
                                            sync_job_user_data, &sync_job_id);
   

   This function can be used with various options, as shown in the following example. The SYNC_OPTION_NO_RETRY option means the sync job is not performed again when it fails. The SYNC_OPTION_EXPEDITED option means the other sync job is operated as soon as possible. The call with the OR structure lets the other sync job operate just once with priority.

   result = sync_manager_on_demand_sync_job(account, sync_job_name2, SYNC_OPTION_NO_RETRY, 
                                            sync_job_user_data, &sync_job_id2);
   result = sync_manager_on_demand_sync_job(account, sync_job_name3, SYNC_OPTION_EXPEDITED, 
                                            sync_job_user_data, &sync_job_id3);
   result = sync_manager_on_demand_sync_job(account, sync_job_name4, 
                                            (SYNC_OPTION_NO_RETRY | SYNC_OPTION_EXPEDITED), 
                                            sync_job_user_data, &sync_job_id4);
   

   This function can also be called like in the following example, because the account handle and user data are not mandatory:

   result = sync_manager_on_demand_sync_job(NULL, sync_job_name, SYNC_OPTION_NONE, 
                                            sync_job_user_data, &sync_job_id);
   result = sync_manager_on_demand_sync_job(account, sync_job_name2, SYNC_OPTION_NO_RETRY, 
                                            NULL, &sync_job_id2);
   result = sync_manager_on_demand_sync_job(NULL, sync_job_name3, SYNC_OPTION_EXPEDITED, 
                                            NULL, &sync_job_id3);
   

   If the on-demand sync job addition process succeeds, the SYNC_ERROR_NONE value is returned.

5. When the on-demand sync is no longer needed, remove it with the sync_manager_remove_sync_job() function with its sync_job_id. If you want to stop using the account too, clean up the account handle.

   At the end, unset the sync callbacks and release the resources with the sync_adapter_unset_callbacks() function.

   result = sync_manager_remove_sync_job(sync_job_id);
   
   account_delete_from_db_by_package_name("data-sync-module");
   account_destroy(account);
   
   sync_adapter_unset_callbacks();
   

   If no account is used:

   result = sync_manager_remove_sync_job(sync_job_id);
   
   sync_adapter_unset_callbacks();
   

Initializing the Periodic Sync

To inform periodically a service application of the time to operate a sync job with its sync interval:

1. Set the sync adapter callbacks in your service application:

   #include <sync_adapter.h>
   
   int result;
   result = sync_adapter_set_callbacks(on_start_cb, on_cancel_cb);
   

2. To use the functions and data types of the Sync Manager API, include the <sync_manager.h> header file in your UI application:

   #include <sync_manager.h>
   

3. If you want to use an account, create the account and obtain the parameters that are used to call the sync_manager_add_periodic_sync_job() function.

   For more information, see Creating and Managing an Account and Managing and Using the Bundle Content.

   account_h account = NULL;
   int account_id = -1;
   account_create(&account);
   account_set_user_name(account, "test_name");
   account_set_email_address(account, "test_email@samsung.com");
   account_set_package_name(account, "data-sync-module");
   account_set_sync_support(account, ACCOUNT_SUPPORTS_SYNC);
   account_insert_to_db(account, &account_id);
   
   const char *sync_job_name = "periodic_sync_job";
   
   sync_period_e sync_period = SYNC_PERIOD_INTERVAL_30MIN;
   sync_period_e sync_period2 = SYNC_PERIOD_INTERVAL_1H;
   sync_period_e sync_period3 = SYNC_PERIOD_INTERVAL_3H;
   sync_period_e sync_period4 = SYNC_PERIOD_INTERVAL_6H;
   
   bundle *sync_job_user_data = NULL;
   sync_job_user_data = bundle_create();
   bundle_add_str(sync_job_user_data, "str", "String sync_job_user_data sample.");
   
   int sync_job_id = -1;
   

4. Add a periodic sync job with an interval as 30 minutes.

   This function operates the sync job with the given period interval.

   result = sync_manager_add_periodic_sync_job(account, sync_job_name, sync_period, SYNC_OPTION_NONE, 
                                               sync_job_user_data, &sync_job_id);
   

   This function can be used with various options, as shown in the following example. The SYNC_OPTION_NO_RETRY option means a sync job is not performed again when it fails. The SYNC_OPTION_EXPEDITED option means another sync job is operated as soon as possible. The call with the OR structure lets the other sync job operate just once with priority.

   result = sync_manager_add_periodic_sync_job(account, sync_job_name2, sync_period2, SYNC_OPTION_NO_RETRY, 
                                               sync_job_user_data, &sync_job_id2);
   result = sync_manager_add_periodic_sync_job(account, sync_job_name3, sync_period3, SYNC_OPTION_EXPEDITED, 
                                               sync_job_user_data, &sync_job_id3);
   result = sync_manager_add_periodic_sync_job(account, sync_job_name4, sync_period4, 
                                               (SYNC_OPTION_NO_RETRY | SYNC_OPTION_EXPEDITED), 
                                               sync_job_user_data, &sync_job_id4);
   

   This function can also be called like in the following example, because the account handle and user data are not mandatory:

   result = sync_manager_add_periodic_sync_job(NULL, sync_job_name, sync_period, SYNC_OPTION_NONE, 
                                               sync_job_user_data, &sync_job_id);
   result = sync_manager_add_periodic_sync_job(account, sync_job_name2, sync_period2, SYNC_OPTION_NO_RETRY, 
                                               NULL, &sync_job_id2);
   result = sync_manager_add_periodic_sync_job(NULL, sync_job_name3, sync_period3, SYNC_OPTION_EXPEDITED, 
                                               NULL, &sync_job_id3);
   

   If the periodic sync job addition process succeeds, the SYNC_ERROR_NONE value is returned.

5. The sync_manager_add_periodic_sync_job() function can renew a registered periodic sync job by using the same sync_job_name as before:

   result = sync_manager_add_periodic_sync_job(account, sync_job_name, sync_period, SYNC_OPTION_NONE, 
                                               sync_job_user_data, &sync_job_id);
   result = sync_manager_add_periodic_sync_job(account, sync_job_name, sync_period2, SYNC_OPTION_EXPEDITED, 
                                               sync_job_user_data2, &sync_job_id);
   

   All the function parameters can be reset except sync_job_name and sync_job_id, which are used to manage a specific sync job.

6. When the periodic sync is no longer needed, remove it with the sync_manager_remove_sync_job() function with its sync_job_id. If you want to stop using the account too, clean up the account handle.

   At the end, unset the sync callbacks and release the resources with the sync_adapter_unset_callbacks() function.

   result = sync_manager_remove_sync_job(sync_job_id);
   
   account_delete_from_db_by_package_name("data-sync-module");
   account_destroy(account);
   
   sync_adapter_unset_callbacks();
   

   If no account is used:

   result = sync_manager_remove_sync_job(sync_job_id);
   
   sync_adapter_unset_callbacks();
   

Initializing the Data Change Sync

To inform a service application of the time to operate a sync job whenever a corresponding database change occurs:

1. Set the sync adapter callbacks in your service application:

   #include <sync_adapter.h>
   
   int result;
   result = sync_adapter_set_callbacks(on_start_cb, on_cancel_cb);
   

2. To use the functions and data types of the Sync Manager API, include the <sync_manager.h> header file in your UI application:

   #include <sync_manager.h>
   

3. If you want to use an account, create the account and obtain the parameters that are used to call the sync_manager_add_data_change_sync_job() function.

   For more information, see Creating and Managing an Account and Managing and Using the Bundle Content.

   account_h account = NULL;
   int account_id = -1;
   account_create(&account);
   account_set_user_name(account, "test_name");
   account_set_email_address(account, "test_email@samsung.com");
   account_set_package_name(account, "data-sync-module");
   account_set_sync_support(account, ACCOUNT_SUPPORTS_SYNC);
   account_insert_to_db(account, &account_id);
   
   const char *sync_capability_calendar = SYNC_SUPPORTS_CAPABILITY_CALENDAR;
   const char *sync_capability_contact = SYNC_SUPPORTS_CAPABILITY_CONTACT;
   const char *sync_capability_image = SYNC_SUPPORTS_CAPABILITY_IMAGE;
   const char *sync_capability_music = SYNC_SUPPORTS_CAPABILITY_MUSIC;
   const char *sync_capability_sound = SYNC_SUPPORTS_CAPABILITY_SOUND;
   const char *sync_capability_video = SYNC_SUPPORTS_CAPABILITY_VIDEO;
   
   bundle *sync_job_user_data = NULL;
   sync_job_user_data = bundle_create();
   bundle_add_str(sync_job_user_data, "str", "String sync_job_user_data sample.");
   
   int sync_job_id = -1;
   

4. Add a data change sync job for the calendar capability.

   The sync_manager_add_data_change_sync_job() function operates a sync job only for a registered capability.

   result = sync_manager_add_data_change_sync_job(account, sync_capability_calendar, SYNC_OPTION_NONE, 
                                                  sync_job_user_data, &sync_job_id);
   

   This function can be used with various options, as shown in the following example. The SYNC_OPTION_NO_RETRY option means a sync job is not performed again when it fails. The SYNC_OPTION_EXPEDITED option means another sync job is operated as soon as possible. The call with the OR structure lets the other sync job operate just once with priority.

   result = sync_manager_add_data_change_sync_job(account, sync_capability_calendar, SYNC_OPTION_NO_RETRY, 
                                                  sync_job_user_data, &sync_job_id2);
   result = sync_manager_add_data_change_sync_job(account, sync_capability_contact, SYNC_OPTION_EXPEDITED, 
                                                  sync_job_user_data, &sync_job_id3);
   result = sync_manager_add_data_change_sync_job(account, sync_capability_image, 
                                                  (SYNC_OPTION_NO_RETRY | SYNC_OPTION_EXPEDITED), 
                                                  sync_job_user_data, &sync_job_id4);
   

   This function can also be called like in the following example, because the account handle and user data are not mandatory:

   result = sync_manager_add_data_change_sync_job(NULL, sync_capability_music, SYNC_OPTION_NONE, 
                                                  sync_job_user_data, &sync_job_id);
   result = sync_manager_add_data_change_sync_job(account, sync_capability_sound, SYNC_OPTION_NO_RETRY, 
                                                  NULL, &sync_job_id2);
   result = sync_manager_add_data_change_sync_job(NULL, sync_capability_video, SYNC_OPTION_EXPEDITED, 
                                                  NULL, &sync_job_id3);
   

   If the data change sync job addition process succeeds, the SYNC_ERROR_NONE value is returned.

5. The sync_manager_add_data_change_sync_job() function can renew a registered data change sync job by using the same sync_capability as before:

   result = sync_manager_add_data_change_sync_job(account, sync_capability_calendar, SYNC_OPTION_NONE, 
                                                  sync_job_user_data, &sync_job_id);
   result = sync_manager_add_data_change_sync_job(account, sync_capability_calendar, SYNC_OPTION_EXPEDITED, 
                                                  sync_job_user_data2, &sync_job_id);
   

   All the function parameters can be reset except sync_capability and sync_job_id, which are used to manage a specific sync job.

6. When the data change sync is no longer needed, remove it with the sync_manager_remove_sync_job() function with its sync_job_id. If you want to stop using the account too, clean up the account handle.

   At the end, unset the sync callbacks and release the resources with the sync_adapter_unset_callbacks() function.

   result = sync_manager_remove_sync_job(sync_job_id);
   
   account_delete_from_db_by_package_name("data-sync-module");
   account_destroy(account);
   
   sync_adapter_unset_callbacks();
   

   If no account is used:

   result = sync_manager_remove_sync_job(sync_job_id);
   
   sync_adapter_unset_callbacks();
   

Initializing the ForEach Sync

To iterate all registered sync jobs to manage them more efficiently:

1. To use the functions and data types of the Sync Manager API, include the <sync_manager.h> header file in your UI application:

   #include <sync_manager.h>
   

2. Set the callback to be invoked and call the iterate function at the same time:

   int result;
   result = sync_manager_foreach_sync_job(sync_job_cb, NULL);
   

3. Define the sync_job_cb() callback, which is invoked separately for every registered sync job. In the callback, the sync jobs are verified with a corresponding data.

   bool 
   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)
   {
      // Verify the registered sync jobs
   }
   

Setting the Callback Functions

To set callbacks to receive notifications about sync operations:

1. To use the functions and data types of the Sync Adapter API, include the <sync_adapter.h> header file in your service application:

   #include <sync_adapter.h>
   

2. Subscribe to the callback functions to receive notifications for the sync operation when a specific event or condition is detected on the device:

   int result;
   result = sync_adapter_set_callbacks(on_start_cb, on_cancel_cb);
   

   When a specific event is detected or a sync job is requested, the applicable callback is invoked.

3. When the on_start_cb() callback is invoked, the predefined data sync process is performed inside the callback function. The on_cancel_cb() callback works in a similar way and cancels the data sync process.

   bool 
   on_start_cb(account_h account, const char *sync_job_name, 
               const char *sync_capability, bundle *sync_job_user_data)
   {
      // Start the data sync process
   }
   
   void 
   on_cancel_cb(account_h account, const char *sync_job_name, 
                const char *sync_capability, bundle *sync_job_user_data)
   {
      // Cancel the data sync process
   }
   

4. When the sync operation notifications are no longer needed, unset the callbacks to free the sync adapter instance:

   result = sync_adapter_unset_callbacks();