--- org.tizen.guides/html/index.htm | 1 + org.tizen.guides/html/native/guides_n.htm | 2 + org.tizen.guides/html/native/sync/sync_guide_n.htm | 203 ++++++++++++++++ org.tizen.guides/index.xml | 1 + org.tizen.tutorials/html/index.htm | 6 + .../html/native/sync/sync_adapter_tutorial_n.htm | 145 +++++++++++ .../html/native/sync/sync_manager_tutorial_n.htm | 268 +++++++++++++++++++++ .../html/native/sync/sync_tutorials_n.htm | 72 ++++++ org.tizen.tutorials/html/native/tutorials_n.htm | 2 + org.tizen.tutorials/index.xml | 1 + 10 files changed, 701 insertions(+) create mode 100644 org.tizen.guides/html/native/sync/sync_guide_n.htm create mode 100644 org.tizen.tutorials/html/native/sync/sync_adapter_tutorial_n.htm create mode 100644 org.tizen.tutorials/html/native/sync/sync_manager_tutorial_n.htm create mode 100644 org.tizen.tutorials/html/native/sync/sync_tutorials_n.htm diff --git a/org.tizen.guides/html/index.htm b/org.tizen.guides/html/index.htm index bf05e2c..73201c3 100644 --- a/org.tizen.guides/html/index.htm +++ b/org.tizen.guides/html/index.htm @@ -307,6 +307,7 @@

System

Device

Enables you to obtain an access token by using the oauth2 authorization.

Security
Enables you to increase the security of your application through cryptography, encryption, and request control.
Sync +
Enables you to provide your application with notification for syncing operation between server and device.
System
Enables you to handle log messages, device and system information, and manage system settings, sensors, and system storage.

Telephony diff --git a/org.tizen.guides/html/native/sync/sync_guide_n.htm b/org.tizen.guides/html/native/sync/sync_guide_n.htm new file mode 100644 index 0000000..b564a35 --- /dev/null +++ b/org.tizen.guides/html/native/sync/sync_guide_n.htm @@ -0,0 +1,203 @@ + + + + + + + + + + + + + + Sync + + + + + + +

Sync

Sync Manager provides notification for service application for maintaining consistency of application's data between server and device. The Sync API enables to manage synchronization schedule for apps.

+ +
+

The main features of the Sync Adapter API include:

Register callbacks for notification of a time to start / cancel sync job
Use app control to start or cancel sync operation, then an application's daemon doesn't need to stay awake

+ + + + + + + + + +

Note
You can test the Sync Adapter functionality only on mobile device and SDK. The wearable device does not support this feature.

+
+ +

The main features of the Sync Manager API include:

Add / Remove On demand sync job schedule
Add / Remove Periodic sync job schedule

+ + + + + + + + + +

Note
You can test the Sync Manager functionality only on mobile device and SDK. The wearable device does not support this feature.

+
+ + +

Sync Rules

+ +

Sync Manager operates sync job based on following five rules:

Table: Five rules for sync job scheduling

+ + + + + + + + + + + + + + + + + + + + + + + + + + + +

Rules	Descriptions
Data on server changes	When data changed on server, a push message arrives from a server. The server sends the push message to Account Provider Service and service applications.
Data on device changes	It is based on capabilities. Data Change Listener notices changes by using Calendar / Contacts API. If there are any changes of Calendar / Contacts data, Sync Manager notices the changes and scheduls a sync job. Changing data on Calendar DB includes in the case of Book, Event, and Todo changes. Changing data on Contacts DB includes add, remove, and modify a contacts.
Network availability	When a change in network status detected, a sync job occurs in the case of changing status of BT, WiFi, and Data Network.
On demand	Sync schedule on demand is provided through the Sync Manager API. For using this feature, you can use the API, *'sync_manager_add_sync_job(account_h account, const char capability, bundle extra)'* function. It provides feature for scheduling sync job just one time.
Sync schedule intervals	Sync schedule intervals is provided through the Sync Manager API. For using this feature, you can use the API, *'sync_manager_add_periodic_sync_job(account_h account, const char capability, bundle extra, sync_period_e sync_period)'* function. +It provides feature for scheduling sync job regularly. Also, you can appoint intervals with using several enum values which provided through the Sync Manager API. 'sync_period'.

+ + +

Sync Capabilities

+ +

There are two capabilities. Those can receive data changed notifications of calendar, contacts by setting these capabilities. Also, if you use bundle API, you can deliver in the form of user_data to callback function by using key value pair.

Table: The kind of sync job options

+ + + + + + + + + + + + + + + +

Options	Descriptions
"http://tizen.org/account/capability/calendar"	An capability for receiving notification when calendar data changed. Adding, updating, and deleting calendar data such as event, book, and todo.
"http://tizen.org/account/capability/contact"	An capability for receiving notification when contacts data changed. Adding, updating, and deleting contacts data such as name, phone number, E-mail.

+ + +

Sync Options

+ +

There are two options which can set attributes of the sync job. It is required using bundle API to set the sync job. So, with the Sync Manager Tutorial and Bundle Tutorial, you can set the sync option for syncing 'On demand' and 'Periodic' job. Also, if you use bundle API, you can deliver in the form of user_data to callback function by using key value pair.

Table: The kind of sync job options

+ + + + + + + + + + + + + + + +

Options	Descriptions
SYNC_OPTION_NO_RETRY	An sync option to denote if retrying the sync request is allowed or not. If the option is set as false, a sync operation will retry when the job failed.
SYNC_OPTION_EXPEDITED	All of sync jobs are passed into sync job queue. This option is limited to the case of priorities. So, it just means giving priority. If the option is set as true, it gives a priority relative to the other jobs. In other words, both 'On demand' and 'Periodic' jobs which came to the queue simultaneously are influenced by the option.

+ + +

App Control

+ +

App Control is a standard mechanism for using specific operations exported by applications in Tizen. With the Sync Adapter API, you can receive notifications without using separately App Control API when starting / canceling sync job is scheduled. Also, apps doesn't be running state for receiving the notification anymore. +Below table is explaining the state of App Control operation which is related to a sync operation. Apps doesn't need to know about it, because those operations are set in daemon primitively. +

Table: The kind of App Control operations

+ + + + + + + + + + + + + + + + + + +

Operations	Values	Descriptions
APP_CONTROL_OPERATION_START_SYNC	"http://tizen.org/appcontrol/operation/start_sync"	start a sync operation by invoking service application callback.
APP_CONTROL_OPERATION_CANCEL_SYNC	"http://tizen.org/appcontrol/operation/cancel_sync"	cancel a sync operation by invoking service application callback.

+ + + + +

+ +

+ + + + + + + + diff --git a/org.tizen.guides/index.xml b/org.tizen.guides/index.xml index 192c16c..d7db438 100644 --- a/org.tizen.guides/index.xml +++ b/org.tizen.guides/index.xml @@ -213,6 +213,7 @@ + diff --git a/org.tizen.tutorials/html/index.htm b/org.tizen.tutorials/html/index.htm index a40de7d..14f3594 100644 --- a/org.tizen.tutorials/html/index.htm +++ b/org.tizen.tutorials/html/index.htm @@ -360,6 +360,12 @@

Contacts

Sync +

Sync Adapter
Sync Manager

System

Device

Sync Adapter: Making sync mechanism implementation easy

+ +

This tutorial demonstrates how you can set callbacks which will perform start or cancel sync operation. The Sync Adapter API provides function which sets callback functions to be called by Sync Manager for starting or canceling sync operation:

+ +

Warm-up

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

Set Callback Functions +
Set client callback functions for starting or canceling sync operation.

+ +

Show All
Hide All

+ +

+
+
Set Callback Functions
+ Hide +
+
+ +
To set callbacks to receive notification for a time to sync operation. + +
1. To use the features of the Sync Adapter API, include the <sync_adapter.h> header file in your application: +
```
+#include <sync_adapter.h>
+
```
  +
2. Initialize Sync Adapter's instance using the sync_adapter_init() function: +
```
+int result;
+const char* capability = "http://tizen.org/account/capability/calendar";
+result = sync_adapter_init(capability);
+
```
  +In the case of accountless, as follows: +
```
+result = sync_adapter_init(NULL);
+
```
  +
3. Using below API is required for sync operation subscribe to notifications about specific rule for synchronization scheduling, use the sync_adapter_set_callbacks() function to set a callback functions. When specific event is detected, the sync_adapter_start_sync_cb or sync_adapter_cancel_sync_cb is invoked. +The following example subscribes the callback functions to receive notifications when the specific event or condition is detected on device. Then, the callback functions to be invoked by Sync Manager for sync operation: +
```
+result = sync_adapter_set_callbacks(on_start_cb, on_cancel_cb);
+
```
  +
4. When the on_start_cb() callback is invoked, sync process predefined is performed inside the callback function. in the case of on_cancel_cb() is same.
```
+int on_start_cb(account_h account, bundle *extras, const char *capability)
+{
+	   //process for starting sync operation.
+}
+
+int on_cancel_cb(account_h account, const char *capability)
+{
+	   //process for canceling sync operation.
+}
+
```
  +
5. When sync operation is no longer used, destroy the instance of Sync Adapter: +
```
+result = sync_adapter_unset_callbacks();
+sync_adapter_destroy();
+
```
  +
+
+

+ + + + +

Sync Manager: Managing all sync related activities

+ +

This tutorial demonstrates how you can manage the schedule of time to synchronize data. The Sync Manager API provides function which can control sync operation manually or periodically:

+ +

Warm-up

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

On Demand Sync +
Add on demand sync job scheduling for one time operation.
Periodic Sync +
Add periodic sync job scheduling with a cycle.

+ +

Show All
Hide All

+ +

+
+
On Demand Sync
+ Hide +
+
+ +
To inform explicitly service app of a time to sync operation once.
+ +
1. To use the features of the Sync Manager API, include the <sync_manager.h> header file in your application: +
```
+#include <sync_manager.h>
+
```
  +
2. Sync Adapter callbacks should be set first. Setting Sync Adapter callbacks can be verified at Sync Adapter. To set callbacks, as follows: +
```
+#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);
+
```
  +In the case of accountless, as follows: +
```
+result = sync_adapter_init(NULL);
+result = sync_adapter_set_callbacks(on_start_cb, on_cancel_cb);
+
```
  +
3. Connect to Sync Manager service using the sync_manager_connect() function: +
```
+result = sync_manager_connect();
+
```
  +
4. In the case of using Account, Account and bundle creation should be performed previously for sync_manager_add_sync_job()'s parameters. But, Account handle is not a mandatory parameter. Because, that is for an application which want to use the Sync Manager without Account. See the Creating and Managing an Account part for Account creation in Account Tutorial. Also, see the Managing and Using the Bundle Content part for Bundle creation in Bundle Tutorial. For example,: +
```
+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(extra, SYNC_OPTION_NO_RETRY, "true");
+bundle_add(extra, SYNC_OPTION_EXPEDITED, "false");
+
```
  +The above example creates bundle and adds option for sync related information. If the SYNC_OPTION_NO_RETRY is set as true, sync service will not retry operation when sync operation is failed. +
5. To add on demand sync job, as follows: +
```
+result = sync_manager_add_sync_job(account, capability, extra);
+
```
  +In the case of accountless, as follows: +
```
+result = sync_manager_add_sync_job(NULL, NULL, extra);
+
```
  +If sync job process had been made well, returns value SYNC_ERROR_NONE. +
6. When on demand sync is no longer used, remove the sync job with the sync_manager_remove_sync_job() function. If you want to stop using account, should not forget clean-up account handle. Also, disconnect from Sync Manager and release the resources with the sync_manager_disconnect() function: +
```
+result = sync_manager_remove_sync_job(account, capability);
+
+account_connect();
+account_get_account_id(account, &account_id);
+account_delete_from_db_by_id(account_id);
+account_destroy(account);
+account_disconnect();
+
+sync_manager_disconnect();
+sync_adapter_unset_callbacks();
+sync_adapter_destroy();
+
```
  +In the case of accountless, as follows: +
```
+result = sync_manager_remove_sync_job(NULL, NULL);
+
+sync_manager_disconnect();
+sync_adapter_unset_callbacks();
+sync_adapter_destroy();
+
```
  +
+
+
+
+
Periodic Sync
+ Hide +
+
+ +
To inform regularly service app of times to sync operation with an interval.
+ +
1. To use the features of the Sync Manager API, include the <sync_manager.h> header file in your application: +
```
+#include <sync_manager.h>
+
```
  +
2. Sync Adapter callbacks should be set first. Setting Sync Adapter callbacks can be verified at Sync Adapter. To set callbacks, as follows: +
```
+#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);
+
```
  +In the case of accountless, as follows: +
```
+result = sync_adapter_init(NULL);
+result = sync_adapter_set_callbacks(on_start_cb, on_cancel_cb);
+
```
  +
3. Connect to Sync Manager service using the sync_manager_connect() function: +
```
+int result;
+result = sync_manager_connect();
+
```
  +
4. In the case of using Account, Account and bundle creation should be performed previously for sync_manager_add_sync_job()'s parameters. But, Account handle is not a mandatory parameter. Because, an application is not using the Account in order to use the Sync Manager. See the Creating and Managing an Account part for Account creation in Account Tutorial or above On Demand Turorial. Also, see the Managing and Using the Bundle Content part for Bundle creation in Bundle Tutorial. For example,: +
```
+bundle *extra = NULL;
+extra = bundle_create();
+bundle_add(extra, SYNC_OPTION_NO_RETRY, "false");
+bundle_add(extra, SYNC_OPTION_EXPEDITED, "false");
+
```
  +The above example creates bundle and adds option for sync related information. All of the sync option is false for periodic sync request. The sync option will retry when sync operation is failed and doesn't grant priority for sync operation. +
5. To add periodic sync job, as follows: +
```
+sync_period_e sync_period = SYNC_PERIOD_INTERVAL_30MIN;
+result = sync_manager_add_periodic_sync_job(account, capability, extra, sync_period);
+
```
  +In the case of accountless, as follows: +
```
+result = sync_manager_add_periodic_sync_job(NULL, NULL, extra, sync_period);
+
```
  +If sync job process had been made well, returns value SYNC_ERROR_NONE. Last parameter means time interval of periodic sync. +
6. When periodic sync is no longer used, remove the sync job with the sync_manager_remove_periodic_sync_job() function. If you want to stop using account, should not forget clean-up account handle. That can be verified above On Demand Tutorial. Also, disconnect from Sync Manager and release the resources with the sync_manager_disconnect() function: +
```
+result = sync_manager_remove_periodic_sync_job(account, capability);
+
+sync_manager_disconnect();
+sync_adapter_unset_callbacks();
+sync_adapter_destroy();
+
```
  +In the case of accountless, as follows: +
```
+result = sync_manager_remove_periodic_sync_job(NULL, NULL);
+
+sync_manager_disconnect();
+sync_adapter_unset_callbacks();
+sync_adapter_destroy();
+
```
  +
+
+

+ + + + +

Sync: Scheduling for Syncing of Application's Data

The sync tutorials demonstrate how you can synchronize data between mobile device and server:

+ Sync Adapter: Making sync mechanism implementation easy +
Demonstrates how you can receive the notification of a sync operation.
+
+ Sync Manager: Managing all sync related activities +
Demonstrates how you can manage the schedule of time to synchronize data.
+

+ + + + + +

Demonstrate how you can increase the security of your application through cryptography and request control.

Social: Managing Personal Data
Demonstrate how you can manage the user's personal data, such as contacts, calendars, and call history, on the device.
Sync: Scheduling for Syncing of Application's Data +
Demonstrate how you can manage your application with notification for syncing operation between server and device.
System: Getting System Information and Managing Devices
Demonstrate how you can manage data related to or provided by the device.
Telephony: Handling Phone Call, SIM Card, and Network Information diff --git a/org.tizen.tutorials/index.xml b/org.tizen.tutorials/index.xml index 2654453..4cf2000 100644 --- a/org.tizen.tutorials/index.xml +++ b/org.tizen.tutorials/index.xml @@ -236,6 +236,7 @@ + -- 2.7.4

Sync

Sync Rules

Sync Capabilities

Sync Options

App Control

Sync Adapter: Making sync mechanism implementation easy

Warm-up

Set Callback Functions

Sync Manager: Managing all sync related activities

Warm-up

On Demand Sync

Periodic Sync

Sync: Scheduling for Syncing of Application's Data