<tr>
<td>Data changes on the device</td>
<td>A subscribed callback function is invoked whenever a database change occurs for a 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> APIs. If there are any changes in the corresponding 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. Data change for the Calendar / Contacts capabilities are supported only on Tizen Mobile. The media content provides notifications for changes in media types, such as image, music, sound, and video.</p></td>
+ <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. The Media Content provides notifications for changes in media types, such as image, music, sound, and video.</p></td>
</tr>
<tr>
<td>Network availability</td>
- <td>When a status change in the Wi-Fi or data network is detected, a sync job occurs.</td>
+ <td>When a status change in the Wi-Fi or data network is detected, behavior of sync operation is changed.</td>
</tr>
<tr>
<td>On demand sync</td>
<td>Sync job name</td>
<td><span style="font-family: Courier New,Courier,monospace">const char*</span></td>
<td>Yes</td>
- <td>Sync job name for managing the jobs.
+ <td>Sync job name for managing sync jobs.
<p>The on-demand and periodic sync jobs can be managed by a user-defined name. If the <span style="font-family: Courier New,Courier,monospace">sync_manager_add_periodic_sync_job()</span> function is called again with same sync job name (where all details except the name and sync job ID are changed), the function does not add a new sync job but updates the existing job. This is mainly used to reset the 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 job.
- <p>A data change sync job can provide a notification whenever a corresponding data change occurs. If the <span style="font-family: Courier New,Courier,monospace">sync_manager_add_data_change_sync_job()</span> function is used with a capability, it is operated for the related capability only. In the case of using the calendar or contact capability, the respective <span style="font-family: Courier New,Courier,monospace">http://tizen.org/privilege/calendar.read</span> or <span style="font-family: Courier New,Courier,monospace">http://tizen.org/privilege/contact.read</span> privilege is required. Data change for the Calendar / Contacts capabilities are supported only on Tizen Mobile.</p>
+ <td>Capability for adding data change sync jobs.
+ <p>A data change sync job can provide a notification whenever a corresponding data change occurs. If the <span style="font-family: Courier New,Courier,monospace">sync_manager_add_data_change_sync_job()</span> function is used with a capability, it is operated for the related capability only. In the case of using the calendar or contact capability, the respective <span style="font-family: Courier New,Courier,monospace">http://tizen.org/privilege/calendar.read</span> or <span style="font-family: Courier New,Courier,monospace">http://tizen.org/privilege/contact.read</span> privilege is required.</p>
<p>The following capabilities are available:</p>
<pre class="prettyprint">
#define SYNC_SUPPORTS_CAPABILITY_CALENDAR "http://tizen.org/sync/capability/calendar"
<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 job.
+ <td>Interval for adding periodic sync jobs.
<p>If the interval is provided, the sync job is performed periodically. If you set the periodic interval to 30 minutes, a time interval is set as a power of 2 less than 30. This means that a time interval set to 16 minutes operates the sync job every 16 minutes while skipping the first notification (so the first is in 32 minutes). The same logic applies to other cases.</p>
<p>This variable provides a periodic sync job with an inexact time. Coupling various periodic sync jobs with an interval as a power of 2 prevents the device from waking up the service application too many times.</p>
<p>The <a href="../../../../org.tizen.native.mobile.apireference/group__CAPI__SYNC__MANAGER__MODULE.html#gad6f301bc84c4e758aee1636b0122dd7e">sync_period_e</a> enumerator defines the available period intervals.</p></td>
<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 sync job behavior.
+ <td>Option for deciding sync job behavior.
<p>The behavior options can be used as an OR value. For example, the <span style="font-family: Courier New,Courier,monospace">(SYNC_OPTION_EXPEDITED | SYNC_OPTION_NO_RETRY)</span> expression is available, and means that the "Sync job is operated just once with priority".</p>
<p>The following options are available:</p>
<ul><li><span style="font-family: Courier New,Courier,monospace">SYNC_OPTION_NONE</span>: Sync job is operated normally</li>
<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 a sync job.
+ <td>User data for sync jobs.
<p>The data can contain additional information related to the registered sync jobs.</p></td>
</tr>
<tr>
<p>The Sync Adapter API allows you to:</p>
<ul>
-<li>Register callbacks for notifications about the sync job start and cancellation.</li>
+<li>Register callbacks for receiving notifications about the sync job start and cancellation.</li>
<li>Start a sync operation with an app control, so that the application's daemon needs not to stay awake.
<p>The Sync Adapter 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. In other words, when using the Sync Adapter API, you can use the App Control API indirectly.</p>
</li>
<li><a href="#periodic_sync">Initializing the Periodic Sync</a>
<p>Add a periodic sync job 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 a notification whenever a specific database change occurs.</p></li>
+ <p>Add a data change sync job for receiving notifications whenever a specific database change occurs.</p></li>
<li><a href="#foreach_sync">Initializing the ForEach Sync</a>
<p>Iterate all the registered sync jobs for managing them more efficiently.</p></li>
<li>Sync adapter
<li>Add an on-demand sync job:
<pre class="prettyprint">
-result = sync_manager_on_demand_sync_job(account, sync_job_name, SYNC_OPTION_NONE,
- sync_job_user_data, &sync_job_id);
+result = sync_manager_on_demand_sync_job(account, sync_job_name, SYNC_OPTION_NONE, sync_job_user_data, &sync_job_id);
</pre>
<p>This function can be used with various options, as shown in the following example. The <span style="font-family: Courier New,Courier,monospace">SYNC_OPTION_NO_RETRY</span> option means the sync job is not performed again when it fails. The <span style="font-family: Courier New,Courier,monospace">SYNC_OPTION_EXPEDITED</span> 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.</p>
-
+
<pre class="prettyprint">
-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);
+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>This function can also be called like in the following example, because the account handle and user data are not mandatory:</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);
+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 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.
+<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 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> function.</p>
<pre class="prettyprint">
result = sync_manager_remove_sync_job(sync_job_id);
</pre>
</li>
</ol>
-
+
<h2 id="periodic_sync" name="periodic_sync">Initializing the Periodic Sync</h2>
<p>To inform periodically a service application of the time to operate a sync job with its sync interval:</p>
<li>Add a periodic sync job with an interval as 30 minutes.
<p>This function operates the sync job with the given period interval.</p>
<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_period, SYNC_OPTION_NONE, sync_job_user_data, &sync_job_id);
</pre>
<p>This function can be used with various options, as shown in the following example. The <span style="font-family: Courier New,Courier,monospace">SYNC_OPTION_NO_RETRY</span> option means a sync job is not performed again when it fails. The <span style="font-family: Courier New,Courier,monospace">SYNC_OPTION_EXPEDITED</span> 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.</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);
+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 function can also be called like in the following example, because the account handle and user data are not mandatory:</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);
+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>The <span style="font-family: Courier New,Courier,monospace">sync_manager_add_periodic_sync_job()</span> function can renew a registered periodic sync job by using the same <span style="font-family: Courier New,Courier,monospace">sync_job_name</span> as before:
<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);
+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>All the function parameters 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.</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_sync_job()</span> function 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.
+<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> function 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> function.</p>
-
+
<pre class="prettyprint">
result = sync_manager_remove_sync_job(sync_job_id);
<li>Add a data change sync job for the calendar capability.
<p>The <span style="font-family: Courier New,Courier,monospace">sync_manager_add_data_change_sync_job()</span> function operates a sync job only for a registered capability.</p>
<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_NONE, sync_job_user_data, &sync_job_id);
</pre>
<p>This function can be used with various options, as shown in the following example. The <span style="font-family: Courier New,Courier,monospace">SYNC_OPTION_NO_RETRY</span> option means a sync job is not performed again when it fails. The <span style="font-family: Courier New,Courier,monospace">SYNC_OPTION_EXPEDITED</span> 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.</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);
+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 function can also be called like in the following example, because the account handle and user data are not mandatory:</p>
<pre class="prettyprint">
-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);
+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 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>The <span style="font-family: Courier New,Courier,monospace">sync_manager_add_data_change_sync_job()</span> function can renew a registered data change sync job by using the same <span style="font-family: Courier New,Courier,monospace">sync_capability</span> as before:
<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);
+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>
<p>All the function parameters 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.</p>
</li>
-<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> function 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.
+<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> function 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> function.</p>
<pre class="prettyprint">
<li>Define the <span style="font-family: Courier New,Courier,monospace">sync_job_cb()</span> callback, which is invoked separately for every registered sync job. In the callback, the sync jobs are verified with a 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)
+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
+ // Verify registered sync jobs
}
</pre>
</li>
<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">
-bool
-on_start_cb(account_h account, const char *sync_job_name,
- const char *sync_capability, bundle *sync_job_user_data)
+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
+ // Start data sync process
}
-void
-on_cancel_cb(account_h account, const char *sync_job_name,
- const char *sync_capability, bundle *sync_job_user_data)
+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
+ // Cancel data sync process
}
</pre>
</li>
projects / sdk / online-doc.git / commitdiff