<th class="note">Note</th>
</tr>
<tr>
- <td class="note">The Sync Manager API domain is supported in mobile applications only. Service and UI applications should have package name as same.</td>
+ <td class="note">The Sync Manager API domain is supported in mobile applications only.<br>Service and UI applications should have package name as same.</td>
</tr>
</tbody>
</table>
-<p>On the device, you can receive notifications when the data changes in the calendar or contacts. To receive the notifications, you must define the applicable capabilities (<span style="font-family: Courier New,Courier,monospace">http://tizen.org/account/capability/calendar</span> for the calendar changes and <span style="font-family: Courier New,Courier,monospace">http://tizen.org/account/capability/contact</span> for the contact changes). If you use the <a href="../../../../org.tizen.native.mobile.apireference/group__CORE__LIB__BUNDLE__MODULE.html">Bundle</a> API, you can deliver the change data to the callback function in the form of <span style="font-family: Courier New,Courier,monospace">user_data</span> by using a key-value pair.</p>
-
<p>The main Sync Manager API features are:</p>
<ul>
-<li>Add and remove the on-demand sync job schedule.</li>
-<li>Add and remove the periodic sync job schedule.</li>
+<li>Add on-demand sync job schedules.</li>
+<li>Add periodic sync job schedules.</li>
+<li>Add data change sync job schedules.</li>
+<li>Remove registered sync job schedules.</li>
+<li>Iterate registered sync job schedules.</li>
</ul>
-<p>The sync manager operates the sync jobs based on the rules defined in the following table.</p>
+<p><br>The sync manager operates sync jobs based on the rules defined in the following table.</p>
<table>
- <caption>Table: Sync job scheduling rules
+ <caption>Table: Sync job scheduling rules<p>
</caption>
<tbody>
<tr>
<th>Description</th>
</tr>
<tr>
- <td>Data on the server changes</td>
- <td>The server sends the push message to the account provider service and service applications. When the data changes on a server, a push message arrives from a server. Then, the device which received the push message can trigger on-demand sync job.</td>
+ <td>Data changes on server</td>
+ <td>A server sends a push message to the account provider service and service applications. When the data is changed on a server, a push message is sent from the server. Then, the device which is received the push message can trigger on-demand sync job.</td>
</tr>
<tr>
- <td>Data on the device changes</td>
- <td>Changes are based on capabilities. The data change listener notices the changes by using the <a href="../../../../org.tizen.native.mobile.apireference/group__CAPI__SOCIAL__CALENDAR__SVC__MODULE.html">Calendar</a> or <a href="../../../../org.tizen.native.mobile.apireference/group__CAPI__SOCIAL__CONTACTS__SVC__MODULE.html">Contacts</a> API. If there are any changes in the calendar or contacts data, the sync manager notices the changes and schedules a sync job.
-<p>Changing data in the Calendar database includes adding, updating, and deleting books, events, and todos. Changing data in the Contacts database includes adding, removing, and modifying contacts.</p></td>
+ <td>Data changes on device</td>
+ <td>A subscribed callback function is invoked whenever DB change occurs for the registered capability. The data change listener notices the changes by using the <a href="../../../../org.tizen.native.mobile.apireference/group__CAPI__SOCIAL__CALENDAR__SVC__MODULE.html">Calendar</a>, <a href="../../../../org.tizen.native.mobile.apireference/group__CAPI__SOCIAL__CONTACTS__SVC__MODULE.html">Contacts</a>, and <a href="../../../../org.tizen.native.mobile.apireference/group__CAPI__MEDIA__CONTENT__MODULE.html">Media Content</a> API. If there are any changes in corresponding data, the sync manager notices the changes and schedules a sync job. <br><br>Changing data in the Calendar database includes adding, updating, and deleting books, events, and todos. Changing data in the Contacts database includes adding, removing, and modifying contacts.<br>Media content provides notification for the types of changed data such as image, music, sound, and video.</td>
</tr>
<tr>
<td>Network availability</td>
- <td>When a change in the Bluetooth, Wi-Fi, or data network status is detected, a sync job occurs.</td>
+ <td>When a status change in the Wi-Fi or data network is detected, a sync job occurs.</td>
</tr>
<tr>
- <td>On demand</td>
- <td>The on-demand sync means that you can schedule a sync job for one time only. You can use this feature with the <span style="font-family: Courier New,Courier,monospace">sync_manager_add_sync_job()</span> function.</td>
+ <td>On demand sync</td>
+ <td>The on-demand sync means that you can schedule a sync job for once. You can use this feature with the <span style="font-family: Courier New,Courier,monospace">sync_manager_on_demand_sync_job()</span> API.</td>
</tr>
<tr>
- <td>Sync schedule intervals</td>
- <td>Sync schedule intervals mean that you can schedule a sync job to be performed regularly. You can use this feature with the <span style="font-family: Courier New,Courier,monospace">sync_manager_add_periodic_sync_job()</span> function. You can define the sync intervals with various enumerators provided through the Sync Manager API.</td>
+ <td>Periodic sync</td>
+ <td>The periodic sync means that you can schedule a sync job to be performed regularly. You can use this feature with the <span style="font-family: Courier New,Courier,monospace">sync_manager_add_periodic_sync_job()</span> API. You can also use the sync intervals as various enumerators which is provided through the Sync Manager API. To use this API, <span style="font-family: Courier New,Courier,monospace">"http://tizen.org/privilege/alarm.set"</span> is required. Because user who use this API can use setting an alarm indirectly.</td>
</tr>
</tbody>
</table>
-<p>When you create a sync job, you can define options that set the sync job attributes. You need the Bundle API to set the sync job options for both the on-demand and periodic jobs:</p>
-<ul><li><span style="font-family: Courier New,Courier,monospace">SYNC_OPTION_NO_RETRY</span>
-<p>This sync option defines whether retrying the sync request is allowed. If the option is set to <span style="font-family: Courier New,Courier,monospace">false</span>, the sync operation tries again after the job fails.</p></li>
-<li><span style="font-family: Courier New,Courier,monospace">SYNC_OPTION_EXPEDITED</span>
-<p>All sync jobs are passed into a sync job queue. If this sync option is set to <span style="font-family: Courier New,Courier,monospace">true</span>, it gives a priority to its job relative to the other queued jobs. Both the on-demand and periodic jobs in the queue are simultaneously influenced by this option.</p></li></ul>
+
+<p><br>The following table lists the variables and theirs description for using Sync Manager.</p>
+<table border="1">
+ <caption>Table: Sync Manager variables<p></caption>
+ <tbody>
+ <tr>
+ <th>Sync Manager variable</th>
+ <th>Data type</th>
+ <th>Mandatory</th>
+ <th>Description</th>
+ </tr>
+ <tr>
+ <td>Account Handle</td>
+ <td><span style="font-family: Courier New,Courier,monospace">account_s*</span></td>
+ <td>No</td>
+ <td>Handle of account module.<p>An account handle for managing account related data.</p></td>
+ </tr>
+ <tr>
+ <td>Sync Job Name</td>
+ <td><span style="font-family: Courier New,Courier,monospace">const char*</span></td>
+ <td>Yes</td>
+ <td>Name for managing sync jobs.<p>On-demand and periodic sync jobs can be managed by using Sync Job Name. It is user defined value. If <span style="font-family: Courier New,Courier,monospace">sync_manager_add_periodic_sync_job()</span> API is called again with same Sync Job Name, not adding a new sync job but renewing all the data except Sync Job Name and Sync Job ID. That is for mainly resetting of periodic interval.</p></td>
+ </tr>
+ <tr>
+ <td>Sync Capability</td>
+ <td><span style="font-family: Courier New,Courier,monospace">const char*</span></td>
+ <td>Yes</td>
+ <td>Capability for a data change sync jobs.<p>Data change sync job can provide notification whenever corresponding data change occurs. If <span style="font-family: Courier New,Courier,monospace">sync_manager_add_data_change_sync_job()</span> API is used with a capability, it is operated only for the related capability. In the case of using calendar and contact capability, <span style="font-family: Courier New,Courier,monospace">"http://tizen.org/privilege/calendar.read"</span> and <span style="font-family: Courier New,Courier,monospace">"http://tizen.org/privilege/contact.read"</span> are required for each.</p><p>Available capabilities are below:<br>#define SYNC_SUPPORTS_CAPABILITY_CALENDAR <span style="font-family: Courier New,Courier,monospace">"http://tizen.org/sync/capability/calendar"</span><br>#define SYNC_SUPPORTS_CAPABILITY_CONTACT <span style="font-family: Courier New,Courier,monospace">"http://tizen.org/sync/capability/contact"</span><br>#define SYNC_SUPPORTS_CAPABILITY_IMAGE <span style="font-family: Courier New,Courier,monospace">"http://tizen.org/sync/capability/image"</span><br>#define SYNC_SUPPORTS_CAPABILITY_MUSIC <span style="font-family: Courier New,Courier,monospace">"http://tizen.org/sync/capability/music"</span><br>#define SYNC_SUPPORTS_CAPABILITY_SOUND <span style="font-family: Courier New,Courier,monospace">"http://tizen.org/sync/capability/sound"</span><br>#define SYNC_SUPPORTS_CAPABILITY_VIDEO <span style="font-family: Courier New,Courier,monospace">"http://tizen.org/sync/capability/video"</span></p></td>
+ </tr>
+ <tr>
+ <td>Sync Period</td>
+ <td><span style="font-family: Courier New,Courier,monospace">sync_period_e</span></td>
+ <td>Yes</td>
+ <td>Interval for a periodic sync jobs.<p>With it, sync job is provided periodically. In the case of setting periodic interval as 30 minutes, a time interval is set as power of 2 less than 30. Then, the time interval which is 16 minutes will operate the sync job every 16 minutes with skipping the first notification. So, the first will be 32 minutes. That is same for the other cases.<br>In other words, it provides periodical sync job with an inexact time. By doing so, coupling various periodic sync jobs with interval as power of 2 is for preventing waking up service application too many times from a device.</p><p>Available period intervals are below:<br>SYNC_PERIOD_INTERVAL_30MIN Sync within 30 minutes<br>SYNC_PERIOD_INTERVAL_1H Sync within 1 hour<br>SYNC_PERIOD_INTERVAL_2H Sync within 2 hours<br>SYNC_PERIOD_INTERVAL_3H Sync within 3 hours<br>SYNC_PERIOD_INTERVAL_6H Sync within 6 hours<br>SYNC_PERIOD_INTERVAL_12H Sync within 12 hours<br>SYNC_PERIOD_INTERVAL_1DAY Sync within 1 day</p></td>
+ </tr>
+ <tr>
+ <td>Sync Option</td>
+ <td><span style="font-family: Courier New,Courier,monospace">sync_option_e</span></td>
+ <td>Yes</td>
+ <td>Option for deciding the behavior of sync jobs.<p>The behavior of sync job is decided with corresponding sync option. These options can be used as OR value. For example, the expression of "(SYNC_OPTION_EXPEDITED | SYNC_OPTION_NO_RETRY)" is available. That means "Sync job will be operated just once with priority".</p><p>Available options are below:<br>SYNC_OPTION_NONE Sync job will be operated normally<br>SYNC_OPTION_EXPEDITED Sync job will be operated as soon as possible<br>SYNC_OPTION_NO_RETRY Sync job will not be performed again when it fails</p></td>
+ </tr>
+ <tr>
+ <td>Sync Job ID</td>
+ <td><span style="font-family: Courier New,Courier,monospace">int*</span></td>
+ <td>Yes</td>
+ <td>Unique ID for managing sync jobs.<p>It is generated when a sync job is added. It is required to remove the sync job. The number of Sync Job ID which can be generated is restricted as a hundred per a package.</p></td>
+ </tr>
+ <tr>
+ <td>Sync Job User Data</td>
+ <td><span style="font-family: Courier New,Courier,monospace">bundle*</span></td>
+ <td>No</td>
+ <td>User data for sync jobs.<p>User data which contains additional information related registered sync jobs.</p></td>
+ </tr>
+ <tr>
+ <td>User Data</td>
+ <td><span style="font-family: Courier New,Courier,monospace">void*</span></td>
+ <td>No</td>
+ <td>User data for <span style="font-family: Courier New,Courier,monospace">sync_manager_for_each_sync_job()</span>.<p>User data which contains additional information related foreach jobs.</p></td>
+ </tr>
+ </tbody>
+</table>
<h2>Sync Adapter</h2>
-<p>The <a href="../../../../org.tizen.native.mobile.apireference/group__CAPI__SYNC__ADAPTER__MODULE.html">Sync Adapter</a> API allows you to:</p>
<table class="note">
<tbody>
<th class="note">Note</th>
</tr>
<tr>
- <td class="note">The Sync Adapter API should be carried out by a service application which will operate data synchronization before using the Sync Manager API.</td>
+ <td class="note">The Sync Adapter API should be carried out by a service application which will operate data synchronization before using the Sync Manager API.<br>The number of service application which can set callbacks is restricted as only one per a package.</td>
</tr>
</tbody>
</table>
<p>The <a href="../../../../org.tizen.native.mobile.apireference/group__CAPI__SYNC__ADAPTER__MODULE.html">Sync Adapter</a> API allows you to:</p>
<ul>
<li>Register callbacks for notifications about the sync job start and cancellation.</li>
-<li>Use an app control to start or cancel the sync operation, so that the application daemon does not need to stay awake.
-
-<p>With the app control mechanism, you can use specific operations exported by other Tizen applications. The mechanism allows you to receive notifications when starting or canceling a sync job without using the <a href="../../../../org.tizen.native.mobile.apireference/group__CAPI__APP__CONTROL__MODULE.html">App Control</a> API separately. <br>When an app control is used, the application does not need to be in the running state to receive the notifications.</p>
-<p>The following table defines the app control operation details related to a sync operation. The applications does not need to know about them, because the operations are set primitively in the daemon.</p>
- <table>
- <caption>Table: App control operations
- </caption>
- <tbody>
- <tr>
- <th>Operation</th>
- <th>Value</th>
- <th>Description</th>
- </tr>
- <tr>
- <td><span style="font-family: Courier New,Courier,monospace">APP_CONTROL_OPERATION_START_SYNC</span></td>
- <td><span style="font-family: Courier New,Courier,monospace">http://tizen.org/appcontrol/operation/start_sync</span></td>
- <td>Start a sync operation by invoking the service application callback.</td>
- </tr>
- <tr>
- <td><span style="font-family: Courier New,Courier,monospace">APP_CONTROL_OPERATION_CANCEL_SYNC</span></td>
- <td><span style="font-family: Courier New,Courier,monospace">http://tizen.org/appcontrol/operation/cancel_sync</span></td>
- <td>Cancel a sync operation by invoking the service application callback.</td>
- </tr>
- </tbody>
- </table>
-
+<li>App control is used to start the sync operation, so that the application's daemon does not need to stay awake. <a href="../../../../org.tizen.native.mobile.apireference/group__CAPI__SYNC__ADAPTER__MODULE.html">Sync Adapter</a> API allows you to use this mechanism without using the <a href="../../../../org.tizen.native.mobile.apireference/group__CAPI__APP__CONTROL__MODULE.html">App Control</a> API separately. <p>In other words, in the case of using <a href="../../../../org.tizen.native.mobile.apireference/group__CAPI__SYNC__ADAPTER__MODULE.html">Sync Adapter</a> API, you can use the <a href="../../../../org.tizen.native.mobile.apireference/group__CAPI__APP__CONTROL__MODULE.html">App Control</a> API indirectly.</p>
</li>
</ul>
</body>
</html>
-
<ul class="toc">
<li><a href="#on_demand_sync">Initializing the On-demand Sync</a></li>
<li><a href="#periodic_sync">Initializing the Periodic Sync</a></li>
+ <li><a href="#data_change_sync">Initializing the Data Change Sync</a></li>
+ <li><a href="#foreach_sync">Initializing the ForEach Sync</a></li>
<li>Sync adapter
<ul class="toc">
<li><a href="#set_callback">Setting the Callback Functions</a></li>
<p>This tutorial demonstrates how you can manage the data synchronizing schedule and control the sync operations manually or periodically.</p>
+ <table class="note">
<tbody>
<tr>
<th class="note">Note</th>
</tr>
<tr>
- <td class="note">These features are supported in mobile applications only. To use the features of the Sync Manager API, <a href="#set_callback">Setting the Callback Functions</a> should be carried out first by a service application. <br>An UI application should not initialize and set callbacks through using the Sync Adapter API. On the contrary, the Sync Manager API should be called to request sync operations by UI application.</td>
+ <td class="note">These features are supported in mobile applications only. To use the features of the Sync Manager API, <a href="#set_callback">Setting the Callback Functions</a> should be carried out first by a service application. <br>An UI application can not initialize and set callbacks through using the Sync Adapter API. On the contrary, the Sync Manager API should be called to request sync operations by UI application.</td>
</tr>
</tbody>
</table>
+
<h2>Warm-up</h2>
<p>Become familiar with the Sync Manager API basics by learning about:</p>
<ul>
<p>Add an on-demand sync job scheduling for a one-time operation.</p></li>
<li><a href="#periodic_sync">Initializing the Periodic Sync</a>
<p>Add a periodic sync job scheduling with a recurring cycle.</p></li>
+ <li><a href="#data_change_sync">Initializing the Data Change Sync</a>
+ <p>Add a data change sync job for receiving notification whenever a specific DB changed.</p></li>
+ <li><a href="#foreach_sync">Initializing the ForEach Sync</a>
+ <p>Iterate all of registered sync jobs for managing them more efficiently.</p></li>
<li>Sync adapter
<ul>
<li><a href="#set_callback">Setting the Callback Functions</a>
</li>
</ul>
+
<h2 id="on_demand_sync" name="on_demand_sync">Initializing the On-demand Sync</h2>
-<p>To inform the service application of a one-time sync operation:</p>
+<p>To inform a service application of the time to operate one-time sync job:</p>
<ol>
-<li>To use the features of the <a href="../../../../org.tizen.native.mobile.apireference/group__CAPI__SYNC__MANAGER__MODULE.html">Sync Manager</a> API, include the <span style="font-family: Courier New,Courier,monospace"><sync_manager.h></span> header file in your UI application:
-<pre class="prettyprint">
-#include <sync_manager.h>
-</pre>
-</li>
-
-<li><a href="#set_callback">Set the sync adapter callbacks</a> in your service application:
+<li><a href="#set_callback">Set the sync adapter callbacks</a> in your service application first:
<pre class="prettyprint">
#include <sync_adapter.h>
-const char* capability = "http://tizen.org/account/capability/contact";
int result;
-result = sync_adapter_init(capability);
-result = sync_adapter_set_callbacks(on_start_cb, on_cancel_cb);
-</pre>
-<p>If no capabilities are defined (you do not want to receive notifications about calendar or contact data changes on the device):</p>
-<pre class="prettyprint">
-result = sync_adapter_init(NULL);
result = sync_adapter_set_callbacks(on_start_cb, on_cancel_cb);
</pre>
</li>
-<li>Connect to the sync manager service using the <span style="font-family: Courier New,Courier,monospace">sync_manager_connect()</span> function:
+<li>To use the features of the <a href="../../../../org.tizen.native.mobile.apireference/group__CAPI__SYNC__MANAGER__MODULE.html">Sync Manager</a> API, include the <span style="font-family: Courier New,Courier,monospace"><sync_manager.h></span> header file in your UI application:
<pre class="prettyprint">
-result = sync_manager_connect();
+#include <sync_manager.h>
</pre>
</li>
-<li>If you want to use an account (track calendar or contact data changes on the device), create the account and the bundle to obtain the parameters for the <span style="font-family: Courier New,Courier,monospace">sync_manager_add_sync_job()</span> function you need later on.
-<p>The account handle is not a mandatory parameter, because it is meant for an application that uses the sync manager without an account. For more information, see <a href="../social/account_tutorial_n.htm">Creating and Managing an Account</a> and <a href="../app_framework/bundle_tutorial_n.htm">Managing and Using the Bundle Content</a>.</p>
+<li>If you want to use an account, create the account and obtain some parameters which are used to call <span style="font-family: Courier New,Courier,monospace">sync_manager_on_demand_sync_job()</span> like below: <p>For more information, see <a href="../social/account_tutorial_n.htm">Creating and Managing an Account</a> and <a href="../app_framework/bundle_tutorial_n.htm">Managing and Using the Bundle Content</a>.</p>
<pre class="prettyprint">
account_h account = NULL;
int account_id = -1;
-bundle *extra = NULL;
-
-account_connect();
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);
-account_disconnect();
-extra = bundle_create();
-bundle_add_str(extra, SYNC_OPTION_NO_RETRY, "true");
-bundle_add_str(extra, SYNC_OPTION_EXPEDITED, "false");
+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;
</pre>
-<p>This example creates a bundle and adds options for sync-related information. Since the <span style="font-family: Courier New,Courier,monospace">SYNC_OPTION_NO_RETRY</span> is set to <span style="font-family: Courier New,Courier,monospace">true</span>, the sync service does not retry the operation if the sync operation fails.</p>
</li>
<li>To add an on-demand sync job:
<pre class="prettyprint">
-result = sync_manager_add_sync_job(account, capability, extra);
+result = sync_manager_on_demand_sync_job(account, sync_job_name, SYNC_OPTION_NONE, sync_job_user_data, &sync_job_id);
</pre>
-<p>If no account is used:</p>
+<p>This API can be used with different options each other. Below example shows the API is called with a variety of sync options. The <span style="font-family: Courier New,Courier,monospace">SYNC_OPTION_NO_RETRY</span> means a sync job will not be performed again when it fails. The <span style="font-family: Courier New,Courier,monospace">SYNC_OPTION_EXPEDITED</span> means another sync job will be operated as soon as possible. Of course, the value which is OR-ing let the other sync job operate just once with priority.</p>
<pre class="prettyprint">
-result = sync_manager_add_sync_job(NULL, NULL, extra);
+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);
</pre>
-<p>If the sync job addition process succeeds, the <span style="font-family: Courier New,Courier,monospace">SYNC_ERROR_NONE</span> value is returned.</p>
+<p>This API also can be called like below. Because, account handle and sync_job_user_data are not mandatory data:</p>
+<pre class="prettyprint">
+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);
+</pre>
+<p>If the on-demand sync job addition process succeeds, the <span style="font-family: Courier New,Courier,monospace">SYNC_ERROR_NONE</span> value is returned.</p>
</li>
-<li>When the on-demand sync is no longer needed, remove it with the <span style="font-family: Courier New,Courier,monospace">sync_manager_remove_sync_job()</span> function. If you want to stop using the account too, clean up the account handle.
-<p>At the end, disconnect from the sync manager and release the resources with the <span style="font-family: Courier New,Courier,monospace">sync_manager_disconnect()</span> function.</p>
+<li>When the on-demand sync is no longer needed, remove it with the <span style="font-family: Courier New,Courier,monospace">sync_manager_remove_sync_job()</span> API with its <span style="font-family: Courier New,Courier,monospace">sync_job_id</span>. If you want to stop using the account too, clean up the account handle. <p>At the end, unset the sync callbacks and release the resources with the <span style="font-family: Courier New,Courier,monospace">sync_adapter_unset_callbacks()</span> API.</p>
<pre class="prettyprint">
-result = sync_manager_remove_sync_job(account, capability);
+result = sync_manager_remove_sync_job(sync_job_id);
-account_connect();
account_delete_from_db_by_package_name("data-sync-module");
account_destroy(account);
-account_disconnect();
-sync_manager_disconnect();
sync_adapter_unset_callbacks();
-sync_adapter_destroy();
</pre>
<p>If no account is used:</p>
<pre class="prettyprint">
-result = sync_manager_remove_sync_job(NULL, NULL);
+result = sync_manager_remove_sync_job(sync_job_id);
-sync_manager_disconnect();
sync_adapter_unset_callbacks();
-sync_adapter_destroy();
</pre>
</li>
</ol>
+
<h2 id="periodic_sync" name="periodic_sync">Initializing the Periodic Sync</h2>
-<p>To inform the service application of a periodical sync operation and its sync interval:</p>
+<p>To inform periodically a service application of the time to operate sync job with its sync interval:</p>
<ol>
+<li><a href="#set_callback">Set the sync adapter callbacks</a> in your service application first:
+<pre class="prettyprint">
+#include <sync_adapter.h>
+
+int result;
+result = sync_adapter_set_callbacks(on_start_cb, on_cancel_cb);
+</pre>
+</li>
+
<li>To use the features of the <a href="../../../../org.tizen.native.mobile.apireference/group__CAPI__SYNC__MANAGER__MODULE.html">Sync Manager</a> API, include the <span style="font-family: Courier New,Courier,monospace"><sync_manager.h></span> header file in your UI application:
<pre class="prettyprint">
#include <sync_manager.h>
</pre>
</li>
-<li><a href="#set_callback">Set the sync adapter callbacks</a> in your service application:
+<li>If you want to use an account, create the account and obtain some parameters which are used to call <span style="font-family: Courier New,Courier,monospace">sync_manager_add_periodic_sync_job()</span> like below: <p>For more information, see <a href="../social/account_tutorial_n.htm">Creating and Managing an Account</a> and <a href="../app_framework/bundle_tutorial_n.htm">Managing and Using the Bundle Content</a>.</p>
+
<pre class="prettyprint">
-#include <sync_adapter.h>
+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* capability = "http://tizen.org/account/capability/contact";
-int result;
-result = sync_adapter_init(capability);
-result = sync_adapter_set_callbacks(on_start_cb, on_cancel_cb);
+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;
+</pre>
+</li>
+
+<li>This API will operate sync job with given period interval. To add a periodic sync job with interval as 30 minutes:
+<pre class="prettyprint">
+result = sync_manager_add_periodic_sync_job(account, sync_job_name, sync_period, SYNC_OPTION_NONE, sync_job_user_data, &sync_job_id);
+</pre>
+<p>This API can be used with different options each other. Below example shows the API is called with a variety of sync options. The <span style="font-family: Courier New,Courier,monospace">SYNC_OPTION_NO_RETRY</span> means a sync job will not be performed again when it fails. The <span style="font-family: Courier New,Courier,monospace">SYNC_OPTION_EXPEDITED</span> means another sync job will be operated as soon as possible. Of course, the value which is OR-ing let the other sync job operate just once with priority.</p>
+<pre class="prettyprint">
+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);
+</pre>
+<p>This API also can be called like below. Because, account handle and sync_job_user_data are not mandatory data:</p>
+<pre class="prettyprint">
+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);
+</pre>
+<p>If the periodic sync job addition process succeeds, the <span style="font-family: Courier New,Courier,monospace">SYNC_ERROR_NONE</span> value is returned.</p>
+</li>
+
+<li>This API can renew registered periodic sync job by using sync_job_name as same like below:
+<pre class="prettyprint">
+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);
</pre>
-<p>If no capabilities are defined (you do not want to receive notifications about calendar or contact data changes on the device):</p>
+All the settings of the API can be reset except <span style="font-family: Courier New,Courier,monospace">sync_job_name</span> and <span style="font-family: Courier New,Courier,monospace">sync_job_id</span> which are used to manage a specific sync job.
+</li>
+
+<li>When the periodic sync is no longer needed, remove it with the <span style="font-family: Courier New,Courier,monospace">sync_manager_remove_sync_job()</span> API with its <span style="font-family: Courier New,Courier,monospace">sync_job_id</span>. If you want to stop using the account too, clean up the account handle. <p>At the end, unset the sync callbacks and release the resources with the <span style="font-family: Courier New,Courier,monospace">sync_adapter_unset_callbacks()</span> API.</p>
<pre class="prettyprint">
-result = sync_adapter_init(NULL);
+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();
+</pre>
+<p>If no account is used:</p>
+<pre class="prettyprint">
+result = sync_manager_remove_sync_job(sync_job_id);
+
+sync_adapter_unset_callbacks();
+</pre>
+</li>
+</ol>
+
+
+<h2 id="data_change_sync" name="data_change_sync">Initializing the Data Change Sync</h2>
+
+<p>To inform a service application of the time to operate sync job whenever corresponding DB changed:</p>
+
+<ol>
+<li><a href="#set_callback">Set the sync adapter callbacks</a> in your service application first:
+<pre class="prettyprint">
+#include <sync_adapter.h>
+
+int result;
result = sync_adapter_set_callbacks(on_start_cb, on_cancel_cb);
</pre>
</li>
-<li>Connect to the sync manager service using the <span style="font-family: Courier New,Courier,monospace">sync_manager_connect()</span> function:
+<li>To use the features of the <a href="../../../../org.tizen.native.mobile.apireference/group__CAPI__SYNC__MANAGER__MODULE.html">Sync Manager</a> API, include the <span style="font-family: Courier New,Courier,monospace"><sync_manager.h></span> header file in your UI application:
<pre class="prettyprint">
-result = sync_manager_connect();
+#include <sync_manager.h>
</pre>
</li>
-<li>If you want to use an account (track calendar or contact data changes on the device), create the account and the bundle to obtain the parameters for the <span style="font-family: Courier New,Courier,monospace">sync_manager_add_sync_job()</span> function you need later on.
-<p>The account handle is not a mandatory parameter, because it is meant for an application that uses the sync manager without an account. For more information, see <a href="../social/account_tutorial_n.htm">Creating and Managing an Account</a> and <a href="../app_framework/bundle_tutorial_n.htm">Managing and Using the Bundle Content</a>.</p>
+<li>If you want to use an account, create the account and obtain some parameters which are used to call <span style="font-family: Courier New,Courier,monospace">sync_manager_add_data_change_sync_job()</span> like below: <p>For more information, see <a href="../social/account_tutorial_n.htm">Creating and Managing an Account</a> and <a href="../app_framework/bundle_tutorial_n.htm">Managing and Using the Bundle Content</a>.</p>
<pre class="prettyprint">
-bundle *extra = NULL;
-extra = bundle_create();
-bundle_add_str(extra, SYNC_OPTION_NO_RETRY, "false");
-bundle_add_str(extra, SYNC_OPTION_EXPEDITED, "false");
+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;
</pre>
-<p>This example creates a bundle and adds options for sync-related information. All the sync options are set to <span style="font-family: Courier New,Courier,monospace">false</span> for a periodic sync request. The sync service tries again when the sync operation has failed and does not grant priority for the sync operation.</p>
</li>
-<li>To add a periodic sync job:
+<li>This API will operate sync job only for registered capability. To add a data change sync job for calendar:
<pre class="prettyprint">
-sync_period_e sync_period = SYNC_PERIOD_INTERVAL_30MIN;
-result = sync_manager_add_periodic_sync_job(account, capability, extra, sync_period);
+result = sync_manager_add_data_change_sync_job(account, sync_capability_calendar, SYNC_OPTION_NONE, sync_job_user_data, &sync_job_id);
</pre>
-<p>If no account is used:</p>
+<p>This API can be used with different options each other. Below example shows the API is called with a variety of sync options. The <span style="font-family: Courier New,Courier,monospace">SYNC_OPTION_NO_RETRY</span> means a sync job will not be performed again when it fails. The <span style="font-family: Courier New,Courier,monospace">SYNC_OPTION_EXPEDITED</span> means another sync job will be operated as soon as possible. Of course, the value which is OR-ing let the other sync job operate just once with priority.</p>
+<pre class="prettyprint">
+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);
+</pre>
+<p>This API also can be called like below. Because, account handle and sync_job_user_data are not mandatory data:</p>
<pre class="prettyprint">
-result = sync_manager_add_periodic_sync_job(NULL, NULL, extra, sync_period);
+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);
</pre>
-<p>If the sync job addition process succeeds, the <span style="font-family: Courier New,Courier,monospace">SYNC_ERROR_NONE</span> value is returned. The last parameter stands for the time interval of the periodic sync.</p>
+<p>If the data change sync job addition process succeeds, the <span style="font-family: Courier New,Courier,monospace">SYNC_ERROR_NONE</span> value is returned.</p>
</li>
-<li>When the periodic sync is no longer needed, remove it with the <span style="font-family: Courier New,Courier,monospace">sync_manager_remove_periodic_sync_job()</span> function. If you want to stop using the account too, clean up the account handle, as shown in the <a href="#on_demand_sync">Initializing the On-demand Sync</a> use case.
+<li>This API can renew registered data change sync job by using sync_capability as same like below:
+<pre class="prettyprint">
+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);
+</pre>
+All the settings of the API can be reset except <span style="font-family: Courier New,Courier,monospace">sync_capability</span> and <span style="font-family: Courier New,Courier,monospace">sync_job_id</span> which are used to manage a specific sync job.
+</li>
-<p>At the end, disconnect from the sync manager and release the resources with the <span style="font-family: Courier New,Courier,monospace">sync_manager_disconnect()</span> function.</p>
+<li>When the data change sync is no longer needed, remove it with the <span style="font-family: Courier New,Courier,monospace">sync_manager_remove_sync_job()</span> API with its <span style="font-family: Courier New,Courier,monospace">sync_job_id</span>. If you want to stop using the account too, clean up the account handle. <p>At the end, unset the sync callbacks and release the resources with the <span style="font-family: Courier New,Courier,monospace">sync_adapter_unset_callbacks()</span> API.</p>
<pre class="prettyprint">
-result = sync_manager_remove_periodic_sync_job(account, capability);
+result = sync_manager_remove_sync_job(sync_job_id);
+
+account_delete_from_db_by_package_name("data-sync-module");
+account_destroy(account);
-sync_manager_disconnect();
sync_adapter_unset_callbacks();
-sync_adapter_destroy();
</pre>
<p>If no account is used:</p>
<pre class="prettyprint">
-result = sync_manager_remove_periodic_sync_job(NULL, NULL);
+result = sync_manager_remove_sync_job(sync_job_id);
-sync_manager_disconnect();
sync_adapter_unset_callbacks();
-sync_adapter_destroy();
</pre>
</li>
</ol>
-<h2 id="set_callback" name="set_callback">Setting the Callback Functions</h2>
-<p>To set callbacks to receive notifications about sync operations:</p>
+<h2 id="foreach_sync" name="set_callback">Initializing the ForEach Sync</h2>
+
+<p>To interate all of registered sync jobs to manage sync job more efficiently:</p>
<ol>
-<li>To use the features of the <a href="../../../../org.tizen.native.mobile.apireference/group__CAPI__SYNC__ADAPTER__MODULE.html">Sync Adapter</a> API, include the <span style="font-family: Courier New,Courier,monospace"><sync_adapter.h></span> header file in your service application:
+<li>To use the features of the <a href="../../../../org.tizen.native.mobile.apireference/group__CAPI__SYNC__MANAGER__MODULE.html">Sync Manager</a> API, include the <span style="font-family: Courier New,Courier,monospace"><sync_manager.h></span> header file in your UI application:
<pre class="prettyprint">
-#include <sync_adapter.h>
+#include <sync_manager.h>
</pre>
</li>
-<li>Initialize the sync adapter instance using the <span style="font-family: Courier New,Courier,monospace">sync_adapter_init()</span> function.
-<p>If both capabilities are defined (you can receive notification about both data changes on the device and set periodic sync job for both capabilities):</p>
+<li>Set the callback which is invoked and call the iterate function at the same time like below:
<pre class="prettyprint">
int result;
-const char* capability_cal = "http://tizen.org/account/capability/calendar";
-const char* capability_con = "http://tizen.org/account/capability/contact";
-result = sync_adapter_init(capability_cal);
-result = sync_adapter_init(capability_con);
+result = sync_manager_foreach_sync_job(sync_job_cb, NULL);
+</pre>
+</li>
+
+<li>The <span style="font-family: Courier New,Courier,monospace">sync_job_cb()</span> callback is invoked as many as existing registered sync jobs. Then, the sync jobs are verified with corresponding data.
+<pre class="prettyprint">
+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
+}
</pre>
-<p>If no capabilities are defined (you do not want to receive notifications about calendar or contact data changes on the device):</p>
+</li>
+</ol>
+
+
+<h2 id="set_callback" name="set_callback">Setting the Callback Functions</h2>
+
+<p>To set callbacks to receive notifications about sync operations:</p>
+
+<ol>
+<li>To use the features of the <a href="../../../../org.tizen.native.mobile.apireference/group__CAPI__SYNC__ADAPTER__MODULE.html">Sync Adapter</a> API, include the <span style="font-family: Courier New,Courier,monospace"><sync_adapter.h></span> header file in your service application:
<pre class="prettyprint">
-result = sync_adapter_init(NULL);
+#include <sync_adapter.h>
</pre>
</li>
<li>Subscribe to the callback functions to receive notifications for the sync operation when a specific event or condition is detected on the device:
<pre class="prettyprint">
+int result;
result = sync_adapter_set_callbacks(on_start_cb, on_cancel_cb);
</pre>
-<p>When a specific event is detected, the <span style="font-family: Courier New,Courier,monospace">sync_adapter_start_sync_cb</span> or <span style="font-family: Courier New,Courier,monospace">sync_adapter_cancel_sync_cb</span> callback is invoked.</p>
+<p>When a specific event is detected or sync job is requested, the <span style="font-family: Courier New,Courier,monospace">sync_adapter_start_sync_cb</span> or <span style="font-family: Courier New,Courier,monospace">sync_adapter_cancel_sync_cb</span> can be invoked.</p>
</li>
-<li>When the <span style="font-family: Courier New,Courier,monospace">on_start_cb()</span> callback is invoked, the predefined sync process is performed inside the callback function. The <span style="font-family: Courier New,Courier,monospace">on_cancel_cb()</span> callback works in a similar way and cancels the sync operation.
+<li>When the <span style="font-family: Courier New,Courier,monospace">on_start_cb()</span> callback is invoked, the predefined data sync process is performed inside the callback function. The <span style="font-family: Courier New,Courier,monospace">on_cancel_cb()</span> callback works in a similar way and cancels the data sync process.
<pre class="prettyprint">
-int on_start_cb(account_h account, bundle *extras, const char *capability)
+bool on_start_cb(account_h account, const char *sync_job_name, const char *sync_capability, bundle *sync_job_user_data)
{
- // Start the sync operation
+ // Start the data sync process
}
-int on_cancel_cb(account_h account, const char *capability)
+void on_cancel_cb(account_h account, const char *sync_job_name, const char *sync_capability, bundle *sync_job_user_data)
{
- // Cancel the sync operation
+ // Cancel the data sync process
}
</pre>
</li>
-<li>When the sync operation is no longer needed, destroy the sync adapter instance:
+<li>If the sync operation is no longer needed, unset callbacks to free the sync adapter instance:
<pre class="prettyprint">
result = sync_adapter_unset_callbacks();
-sync_adapter_destroy();
</pre>
</li>
-
</ol>
<script type="text/javascript" src="../../scripts/jquery.zclip.min.js"></script>
projects / sdk / online-doc.git / commitdiff