From bad2d54eea669278f7a1511af18cdca6ef191732 Mon Sep 17 00:00:00 2001 From: Ickhee Woo Date: Wed, 26 Aug 2015 17:42:52 +0900 Subject: [PATCH] modified sync-manager tutorial and guide for ACR-364. Change-Id: I4852379dcad0e67152782410594c2942ca3c271c Signed-off-by: Ickhee Woo --- .../html/native/account/sync_manager_n.htm | 131 +++++---- .../native/account/sync_manager_tutorial_n.htm | 308 ++++++++++++++------- 2 files changed, 292 insertions(+), 147 deletions(-) diff --git a/org.tizen.guides/html/native/account/sync_manager_n.htm b/org.tizen.guides/html/native/account/sync_manager_n.htm index cf7906f..7a07b9e 100644 --- a/org.tizen.guides/html/native/account/sync_manager_n.htm +++ b/org.tizen.guides/html/native/account/sync_manager_n.htm @@ -41,21 +41,22 @@ Note - The Sync Manager API domain is supported in mobile applications only. Service and UI applications should have package name as same. + The Sync Manager API domain is supported in mobile applications only.
Service and UI applications should have package name as same. -

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 (http://tizen.org/account/capability/calendar for the calendar changes and http://tizen.org/account/capability/contact for the contact changes). If you use the Bundle API, you can deliver the change data to the callback function in the form of user_data by using a key-value pair.

-

The main Sync Manager API features are:

-

The sync manager operates the sync jobs based on the rules defined in the following table.

+


The sync manager operates sync jobs based on the rules defined in the following table.

- @@ -63,38 +64,92 @@ - - + + - - + + - + - - + + - - + +
Table: Sync job scheduling rules + Table: Sync job scheduling rules
Description
Data on the server changesThe 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.Data changes on serverA 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.
Data on the device changesChanges are based on capabilities. The data change listener notices the changes by using the Calendar or Contacts API. If there are any changes in the calendar or contacts data, the sync manager notices the changes and schedules a sync job. -

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 changes on deviceA subscribed callback function is invoked whenever DB change occurs for the registered capability. The data change listener notices the changes by using the Calendar, Contacts, and Media Content API. If there are any changes in corresponding data, the sync manager notices the changes and schedules a sync job.

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.
Media content provides notification for the types of changed data such as image, music, sound, and video.
Network availabilityWhen a change in the Bluetooth, Wi-Fi, or data network status is detected, a sync job occurs.When a status change in the Wi-Fi or data network is detected, a sync job occurs.
On demandThe on-demand sync means that you can schedule a sync job for one time only. You can use this feature with the sync_manager_add_sync_job() function.On demand syncThe on-demand sync means that you can schedule a sync job for once. You can use this feature with the sync_manager_on_demand_sync_job() API.
Sync schedule intervalsSync schedule intervals mean that you can schedule a sync job to be performed regularly. You can use this feature with the sync_manager_add_periodic_sync_job() function. You can define the sync intervals with various enumerators provided through the Sync Manager API.Periodic syncThe periodic sync means that you can schedule a sync job to be performed regularly. You can use this feature with the sync_manager_add_periodic_sync_job() API. You can also use the sync intervals as various enumerators which is provided through the Sync Manager API. To use this API, "http://tizen.org/privilege/alarm.set" is required. Because user who use this API can use setting an alarm indirectly.
-

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:

- + +


The following table lists the variables and theirs description for using Sync Manager.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table: Sync Manager variables

Sync Manager variableData typeMandatoryDescription
Account Handleaccount_s*NoHandle of account module.

An account handle for managing account related data.

Sync Job Nameconst char*YesName for managing sync jobs.

On-demand and periodic sync jobs can be managed by using Sync Job Name. It is user defined value. If sync_manager_add_periodic_sync_job() 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.

Sync Capabilityconst char*YesCapability for a data change sync jobs.

Data change sync job can provide notification whenever corresponding data change occurs. If sync_manager_add_data_change_sync_job() API is used with a capability, it is operated only for the related capability. In the case of using calendar and contact capability, "http://tizen.org/privilege/calendar.read" and "http://tizen.org/privilege/contact.read" are required for each.

Available capabilities are below:
#define    SYNC_SUPPORTS_CAPABILITY_CALENDAR    "http://tizen.org/sync/capability/calendar"
#define    SYNC_SUPPORTS_CAPABILITY_CONTACT    "http://tizen.org/sync/capability/contact"
#define    SYNC_SUPPORTS_CAPABILITY_IMAGE    "http://tizen.org/sync/capability/image"
#define    SYNC_SUPPORTS_CAPABILITY_MUSIC    "http://tizen.org/sync/capability/music"
#define    SYNC_SUPPORTS_CAPABILITY_SOUND    "http://tizen.org/sync/capability/sound"
#define    SYNC_SUPPORTS_CAPABILITY_VIDEO    "http://tizen.org/sync/capability/video"

Sync Periodsync_period_eYesInterval for a periodic sync jobs.

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.
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.

Available period intervals are below:
SYNC_PERIOD_INTERVAL_30MIN    Sync within 30 minutes
SYNC_PERIOD_INTERVAL_1H    Sync within 1 hour
SYNC_PERIOD_INTERVAL_2H    Sync within 2 hours
SYNC_PERIOD_INTERVAL_3H    Sync within 3 hours
SYNC_PERIOD_INTERVAL_6H    Sync within 6 hours
SYNC_PERIOD_INTERVAL_12H    Sync within 12 hours
SYNC_PERIOD_INTERVAL_1DAY    Sync within 1 day

Sync Optionsync_option_eYesOption for deciding the behavior of sync jobs.

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".

Available options are below:
SYNC_OPTION_NONE    Sync job will be operated normally
SYNC_OPTION_EXPEDITED    Sync job will be operated as soon as possible
SYNC_OPTION_NO_RETRY    Sync job will not be performed again when it fails

Sync Job IDint*YesUnique ID for managing sync jobs.

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.

Sync Job User Databundle*NoUser data for sync jobs.

User data which contains additional information related registered sync jobs.

User Datavoid*NoUser data for sync_manager_for_each_sync_job().

User data which contains additional information related foreach jobs.

Sync Adapter

-

The Sync Adapter API allows you to:

@@ -102,7 +157,7 @@ - +
Note
The Sync Adapter API should be carried out by a service application which will operate data synchronization before using the Sync Manager API.The Sync Adapter API should be carried out by a service application which will operate data synchronization before using the Sync Manager API.
The number of service application which can set callbacks is restricted as only one per a package.
@@ -110,32 +165,7 @@

The Sync Adapter API allows you to:

@@ -163,4 +193,3 @@ var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga - diff --git a/org.tizen.tutorials/html/native/account/sync_manager_tutorial_n.htm b/org.tizen.tutorials/html/native/account/sync_manager_tutorial_n.htm index 10e7c34..340dc2b 100644 --- a/org.tizen.tutorials/html/native/account/sync_manager_tutorial_n.htm +++ b/org.tizen.tutorials/html/native/account/sync_manager_tutorial_n.htm @@ -25,6 +25,8 @@