From: Lukasz Bardeli Date: Fri, 18 Aug 2017 11:18:28 +0000 (+0200) Subject: [DataControl] Updating Guide and Mobile/TV API Reference X-Git-Tag: GitHub/PR#40/tizen-studio~58^2 X-Git-Url: http://review.tizen.org/git/?a=commitdiff_plain;h=refs%2Fchanges%2F65%2F143465%2F5;p=sdk%2Fonline-doc.git [DataControl] Updating Guide and Mobile/TV API Reference Adding information about addChangeListener and removeChangeListener PS2: Reviewed PS4: Provider data change addition reviewed PS5: Fixed try/catch statements in guide topic Change-Id: I6dd19f868e8a46cd35bb372dd7a993992ca41e38 Signed-off-by: Lukasz Bardeli --- diff --git a/org.tizen.guides/html/web/app_management/data_w.htm b/org.tizen.guides/html/web/app_management/data_w.htm index 8ed2934..9e8daac 100644 --- a/org.tizen.guides/html/web/app_management/data_w.htm +++ b/org.tizen.guides/html/web/app_management/data_w.htm @@ -31,6 +31,7 @@
  • Prerequisites
  • Managing Data in Key-value Pairs
  • Managing SQL-type Data
    • +
  • Monitoring Provider Data Changes

    • Related Info

    Prerequisites

    -

    To use the Data Control API (in mobile, wearable, and TV applications), the application has to request permission by adding the following privilege to the config.xml file:

    +

    To use the Data Control API (in mobile, wearable, and TV applications), the application has to request permission by adding the following privileges to the config.xml file:

     <tizen:privilege name="http://tizen.org/privilege/datacontrol.consumer"/>
-
    +<!--To receive DataControl provider data change notifications--> +<tizen:privilege name="http://tizen.org/privilege/datasharing"/> +<tizen:privilege name="http://tizen.org/privilege/appmanager.launch"/> +

    Managing Data in Key-value Pairs

    @@ -134,7 +140,7 @@ try {

  • To retrieve a SQLDataControlConsumer object (in mobile, wearable, and TV applications), use the getDataControlConsumer() method of the DataControlManager interface (in mobile, wearable, and TV applications). This object allows accessing the data stored by the DataControl provider.

    You need a running DataControl provider application, which uses the "http://tizen.org/datacontrol/provider/DictionaryDataControlProvider" provider ID.

    -/* Get SQL type DataControlConsumerObject */
+/* Get the SQL type DataControlConsumerObject */
 try {
     var globalSQLConsumer = tizen.datacontrol.getDataControlConsumer('http://tizen.org/datacontrol/provider/DictionaryDataControlProvider', 'Dictionary', 'SQL');
 }
@@ -215,6 +221,89 @@ try {
    • +

    Monitoring Provider Data Changes

    + +

    Learning how to add a listener allows you to receive notifications about DataControl provider data changes:

    +
      +
    1. +

      To retrieve a SQLDataControlConsumer object (in mobile, wearable, and TV applications), use the getDataControlConsumer() method of the DataControlManager interface (in mobile, wearable, and TV applications). This object allows you to monitor changes in the DataControl provider data.

      +

      You need a running DataControl provider application, which uses the "http://tizen.org/datacontrol/provider/DictionaryDataControlProvider" provider ID.

      +
      +/* Get the map-type DataControlConsumerObject */
+try {
+    var globalMappedConsumer = tizen.datacontrol.getDataControlConsumer('http://tizen.org/datacontrol/provider/DictionaryDataControlProvider', 'Dictionary', 'MAP');
+} catch (error) {
+    console.log("The following error occurred: " +  error.name);
+}
+
+/* Get the SQL-type DataControlConsumerObject */
+try {
+    var globalSQLConsumer = tizen.datacontrol.getDataControlConsumer('http://tizen.org/datacontrol/provider/DictionaryDataControlProvider', 'Dictionary', 'SQL');
+} catch (error) {
+    console.log("The following error occurred: " +  error.name);
+}
+
      +
      2. +
    2. +

      Define a change callback, error callback, and needed variables:

      +
      +var SqlWatcherId = 0, MapWatcherId = 0;
+
+function dataChangeSuccessCallback(eventType, rowData) {
+    console.log("Operation " + eventType + " was performed");
+    console.log("Data changed:");
+    for (var i = 0; i < rowData.columns.length; i++) {
+        console.log("column " + rowData.columns[i] + " value " + rowData.values[i]);
+    }
+}
+
+function errorCallback(error) {
+    console.log("The following error occurred: " +  error.name);
+}
+
      +
      3. +
    3. +

      Register the listeners that trigger the change callback when the provider data changes:

      +
      +try {
+    SqlWatcherId = globalSQLConsumer.addChangeListener(dataChangeSuccessCallback, errorCallback);
+    console.log("SQL change listener has been added with watchId = " + SqlWatcherId);
+} catch (error) {
+    console.log("The following error occurred: " +  error.name);
+}
+
+try {
+    MapWatcherId = globalMAPConsumer.addChangeListener(dataChangeSuccessCallback, errorCallback);
+    console.log("MAP change listener has been added with watchId = " + MapWatcherId);
+} catch (error) {
+    console.log("The following error occurred: " +  error.name);
+}
+
      +
      4. +
    4. +

      When the notifications are no longer needed, stop them with the removeChangeListener() method:

      +
      +try {
+    globalSQLConsumer.removeChangeListener(SqlWatcherId);
+} catch (error) {
+    console.log("The following error occurred: " +  error.name);
+}
+
+try {
+    globalMAPConsumer.removeChangeListener(MapWatcherId);
+} catch (error) {
+    console.log("The following error occurred: " +  error.name);
+}
+
      +
      5. +
    + +
    + Note + To monitor DataControl provider data changes, it is not enough to implement a listener in the DataControl consumer. You also need to implement the data change sending functionality in the DataControl provider. +

    The data sending implementation determines the actual change data returned to the DataControl consumer. For more information on the DataControl provider implementation, see Monitoring Data Changes.

    +
    + @@ -237,4 +326,4 @@ var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga - \ No newline at end of file + diff --git a/org.tizen.web.apireference/html/device_api/mobile/tizen/datacontrol.html b/org.tizen.web.apireference/html/device_api/mobile/tizen/datacontrol.html index 6e25a16..22a8056 100755 --- a/org.tizen.web.apireference/html/device_api/mobile/tizen/datacontrol.html +++ b/org.tizen.web.apireference/html/device_api/mobile/tizen/datacontrol.html @@ -26,8 +26,14 @@ Please read the -
  • 1. Type Definitions +
  • 1. Type Definitions
  • 2. Interfaces
    • @@ -71,46 +79,57 @@ Please read the DataControlManager - -DataControlConsumerObject getDataControlConsumer (DOMString providerId, DOMString dataId, DataType type) +
    +DataControlConsumerObject getDataControlConsumer (DOMString providerId, DOMString dataId, DataType type)
    DataControlConsumerObject - + +
    long addChangeListener (DataControlChangeCallback dataChangeCallback, optional ErrorCallback? errorCallback)
    +
    void removeChangeListener (long watchId)
    + SQLDataControlConsumer -void insert (unsigned long reqId, RowData insertionData, optional DataControlInsertSuccessCallback? successCallback, optional DataControlErrorCallback? errorCallback)
    - void update (unsigned long reqId, RowData updateData, DOMString where, optional DataControlSuccessCallback? successCallback, optional DataControlErrorCallback? errorCallback)
    - void remove (unsigned long reqId, DOMString where, optional DataControlSuccessCallback? successCallback, optional DataControlErrorCallback? errorCallback)
    - void select (unsigned long reqId, DOMString[] columns, DOMString where, DataControlSelectSuccessCallback successCallback, optional DataControlErrorCallback? errorCallback, optional unsigned long? page, optional unsigned long? maxNumberPerPage, optional DOMString? order) + +
    void insert (unsigned long reqId, RowData insertionData, optional DataControlInsertSuccessCallback? successCallback, optional DataControlErrorCallback? errorCallback)
    +
    void update (unsigned long reqId, RowData updateData, DOMString where, optional DataControlSuccessCallback? successCallback, optional DataControlErrorCallback? errorCallback)
    +
    void remove (unsigned long reqId, DOMString where, optional DataControlSuccessCallback? successCallback, optional DataControlErrorCallback? errorCallback)
    +
    void select (unsigned long reqId, DOMString[] columns, DOMString where, DataControlSelectSuccessCallback successCallback, optional DataControlErrorCallback? errorCallback, optional unsigned long? page, optional unsigned long? maxNumberPerPage, optional DOMString? order)
    + MappedDataControlConsumer -void addValue (unsigned long reqId, DOMString key, DOMString value, optional DataControlSuccessCallback? successCallback, optional DataControlErrorCallback? errorCallback)
    - void removeValue (unsigned long reqId, DOMString key, DOMString value, DataControlSuccessCallback successCallback, optional DataControlErrorCallback? errorCallback)
    - void getValue (unsigned long reqId, DOMString key, DataControlGetValueSuccessCallback successCallback, optional DataControlErrorCallback? errorCallback)
    - void updateValue (unsigned long reqId, DOMString key, DOMString oldValue, DOMString newValue, DataControlSuccessCallback successCallback, optional DataControlErrorCallback? errorCallback) + +
    void addValue (unsigned long reqId, DOMString key, DOMString value, optional DataControlSuccessCallback? successCallback, optional DataControlErrorCallback? errorCallback)
    +
    void removeValue (unsigned long reqId, DOMString key, DOMString value, DataControlSuccessCallback successCallback, optional DataControlErrorCallback? errorCallback)
    +
    void getValue (unsigned long reqId, DOMString key, DataControlGetValueSuccessCallback successCallback, optional DataControlErrorCallback? errorCallback)
    +
    void updateValue (unsigned long reqId, DOMString key, DOMString oldValue, DOMString newValue, DataControlSuccessCallback successCallback, optional DataControlErrorCallback? errorCallback)
    + DataControlSuccessCallback -void onsuccess (unsigned long reqId) +
    void onsuccess (unsigned long reqId)
    DataControlErrorCallback -void onerror (unsigned long reqId, WebAPIError error) +
    void onerror (unsigned long reqId, WebAPIError error)
    DataControlInsertSuccessCallback -void onsuccess (unsigned long reqId, long insertRowId) +
    void onsuccess (unsigned long reqId, long insertRowId)
    DataControlSelectSuccessCallback -void onsuccess (RowData[] rows, unsigned long reqId) +
    void onsuccess (RowData[] rows, unsigned long reqId)
    DataControlGetValueSuccessCallback -void onsuccess (DOMString[] values, unsigned long reqid) +
    void onsuccess (DOMString[] values, unsigned long reqid)
    + + +DataControlChangeCallback +
    void onsuccess (EventType type, RowData data)
    RowData @@ -131,6 +150,33 @@ Please read the +

    1.2. EventType

    +
    + Specifies the data change event types. The possible values are: +
    +
        enum EventType { "SQL_UPDATE", "SQL_INSERT", "SQL_DELETE", "MAP_SET", "MAP_ADD", "MAP_REMOVE"};
    +

    + Since: + 4.0 +

    +
    +
      +
    • +SQL_UPDATE - SQL update event
      • +
    • +SQL_INSERT - SQL insert event
      • +
    • +SQL_DELETE - SQL delete event
      • +
    • +MAP_SET - Map update event
      • +
    • +MAP_ADD - Map add event
      • +
    • +MAP_REMOVE - Map remove event
      • +
    +
    +

    2. Interfaces

    @@ -263,12 +309,17 @@ catch (err)

    2.3. DataControlConsumerObject

    - This interface provides common attributes for other derived DataControlConsumerObject. + This interface provides common attributes and methods for other derived DataControlConsumerObject. 
        [NoInterfaceObject] interface DataControlConsumerObject {
         readonly attribute DataType type;
         readonly attribute DOMString providerId;
         readonly attribute DOMString dataId;
+
+        long addChangeListener(DataControlChangeCallback dataChangeCallback,
+                               optional ErrorCallback? errorCallback) raises(WebAPIException);
+
+        void removeChangeListener(long watchId) raises(WebAPIException);
     };

    Since: @@ -311,6 +362,221 @@ The string consists of one or more components, separated by a slash('/').

    +
    +

    Methods

    +
    +
    +addChangeListener +
    +
    +
    + Adds a listener to receive notifications about provider data changes. +
    +
    long addChangeListener(DataControlChangeCallback dataChangeCallback, optional ErrorCallback? errorCallback);
+
    +

    + Since: + 4.0 +

    +
    +

    +The ErrorCallback method is launched with these error types: +

    +
      +
    • +IOError - If a DB operation has failed.
      • +
    +
    +

    + Privilege level: + public +

    +

    + Privilege: + http://tizen.org/privilege/datasharing +

    +

    + Privilege: + http://tizen.org/privilege/appmanager.launch +

    +
    +

    Parameters:

    +
      +
    • +dataChangeCallback: + Callback method to be invoked when received data changed notification from provider application. +
      • +
    • +errorCallback [optional] [nullable]: + Callback method to be invoked if provider changes cannot be watched. +
      • +
    +
    +
    +

    Return value:

    + long An identifier used to clear the watch subscription. +
    +
    +

    Exceptions:

    +
    • WebAPIException
        +

      • + with error type TypeMismatchError, if any input parameter +is not compatible with the expected type for that parameter. +

        • +

      • + with error type SecurityError, if the application does not have the privilege to call this method. +

        • +
      +
    +
    +
    +

    Code example:

     var watcherId = 0;
+
+ function dataChangeSuccessCallback(eventType, rowData)
+ {
+   console.log("Operation " + eventType + " was performed");
+   console.log("Data changed:");
+   for (var i = 0; i < rowData.columns.length; i++)
+   {
+     console.log("column " + rowData.columns[i] + " value " + rowData.values[i]);
+   }
+ }
+
+ function errorCallback(error)
+ {
+   console.log("The following error occurred: " +  error.name);
+ }
+
+ try
+ {
+   var rowData =
+   {
+     columns : ["WORD", "WORD_DESC"] ,
+     values  : ["'tizen1'", "'tizen2'"]
+   };
+
+   watcherId = globalSQLConsumer.addChangeListener(dataChangeSuccessCallback, errorCallback);
+   console.log("Change listener has been added with watchId = " + watcherId);
+
+   /* Define globalReqId before */
+   /* Increases globalReqId for uniqueness */
+   globalReqId++;
+   globalSQLConsumer.insert(globalReqId, rowData);
+ }
+ catch (err)
+ {
+   console.log(err.name + ": " + err.message);
+ }
+
    +
    +
    +

    Output example:

     Change listener has been added with watchId = 1
+ Operation SQL_INSERT was performed
+ Data changed:
+ column WORD value 'tizen1'
+ column WORD_DESC value 'tizen2'
+
    +
    +
    +
    +removeChangeListener +
    +
    +
    + Removes data change listener. +
    +
    void removeChangeListener(long watchId);
+
    +

    + Since: + 4.0 +

    +
    +

    +If the watchId argument is valid and corresponds to a subscription already in +place, the watch process must immediately stop and no further callbacks must be +invoked. If the watchId argument is not valid or does not correspond to a +valid subscription, the method should return without any further action. +

    +
    +

    + Privilege level: + public +

    +

    + Privilege: + http://tizen.org/privilege/datasharing +

    +

    + Privilege: + http://tizen.org/privilege/appmanager.launch +

    +
    +

    Parameters:

    +
      +
    • +watchId: + Subscription identifier. +
      • +
    +
    +
    +

    Exceptions:

    +
    • WebAPIException
        +

      • + with error type SecurityError, if the application does not have the privilege to call this method. +

        • +

      • + with error type IOError, if a DB operation has failed. +

        • +
      +
    +
    +
    +

    Code example:

     var watcherId = 0;
+
+ function dataChangeSuccessCallback(type, rowData)
+ {
+   console.log("Operation " + type + " was performed");
+   console.log("Data changed:");
+   for (var i = 0; i < rowData.columns.length; i++)
+   {
+     console.log("column " + rowData.columns[i] + " value " + rowData.values[i]);
+   }
+ }
+
+ try
+ {
+   var rowData =
+   {
+     columns : ["WORD", "WORD_DESC"] ,
+     values  : ["'tizen1'", "'tizen2'"]
+   };
+
+   watcherId = globalSQLConsumer.addChangeListener(dataChangeSuccessCallback);
+   console.log("Change listener has been added with watchId = " + watcherId);
+   /* Remove addChangeListener */
+   globalSQLConsumer.removeChangeListener(watcherId);
+   console.log("removeChangeListener was invoked");
+   /* Define globalReqId before */
+   /* Increases globalReqId for uniqueness */
+   globalReqId++;
+   globalSQLConsumer.insert(globalReqId, rowData);
+ }
+ catch (err)
+ {
+   console.log(err.name +": " + err.message);
+ }
+
    +
    +
    +

    Output example:

     Change listener has been added with watchId = 1
+ removeChangeListener was invoked
+
    +
    +
    +
    +

    2.4. SQLDataControlConsumer

    @@ -719,6 +985,7 @@ try { /* globalSQLConsumer and globalReqId should be defined before */ /* Increases globalReqId for uniqueness */ + globalReqId++; var columns = ["WORD", "WORD_DESC"]; var whereClause = "1"; console.log("----- Calling for ascending order -----"); @@ -1364,8 +1631,53 @@ catch (err)
    +
    +

    2.11. DataControlChangeCallback

    +
    + This interface provides a DataControlChangeCallback for addChangeListener method. +
    +
        [Callback=FunctionOnly, NoInterfaceObject] interface DataControlChangeCallback {
+        void onsuccess(EventType type, RowData data);
+    };
    +

    + Since: + 4.0 +

    +
    +

    Methods

    +
    +
    +onsuccess +
    +
    +
    + Called when the data is modified. +
    +
    void onsuccess(EventType type, RowData data);
+
    +

    + Since: + 4.0 +

    +
    +

    Parameters:

    +
      +
    • +type: + A type of performed operation. +
      • +
    • +data: + Object with information of columns and values of changed data. Actual data to be returned depends on data returned by data control provider application. Please refer to native documentation. +
      • +
    +
    +
    +
    +
    +
    -

    2.11. RowData

    +

    2.12. RowData

    The dictionary represents RowData holding 1 row of SQL selection results from another application.
    @@ -1408,6 +1720,8 @@ catch (err) 
    module DataControl {
     enum DataType { "MAP", "SQL"};
 
+    enum EventType { "SQL_UPDATE", "SQL_INSERT", "SQL_DELETE", "MAP_SET", "MAP_ADD", "MAP_REMOVE"};
+
     [NoInterfaceObject] interface DataControlManagerObject {
         readonly attribute DataControlManager datacontrol;
     };
@@ -1422,6 +1736,11 @@ catch (err)
         readonly attribute DataType type;
         readonly attribute DOMString providerId;
         readonly attribute DOMString dataId;
+
+        long addChangeListener(DataControlChangeCallback dataChangeCallback,
+                               optional ErrorCallback? errorCallback) raises(WebAPIException);
+
+        void removeChangeListener(long watchId) raises(WebAPIException);
     };
 
     [NoInterfaceObject] interface SQLDataControlConsumer : DataControlConsumerObject {
@@ -1481,6 +1800,10 @@ catch (err)
         void onsuccess(DOMString[] values, unsigned long reqid);
     };
 
+    [Callback=FunctionOnly, NoInterfaceObject] interface DataControlChangeCallback {
+        void onsuccess(EventType type, RowData data);
+    };
+
 
     dictionary RowData {
         DOMString[] columns;
diff --git a/org.tizen.web.apireference/html/device_api/tv/tizen/datacontrol.html b/org.tizen.web.apireference/html/device_api/tv/tizen/datacontrol.html
index dd8ef1e..c8f0369 100755
--- a/org.tizen.web.apireference/html/device_api/tv/tizen/datacontrol.html
+++ b/org.tizen.web.apireference/html/device_api/tv/tizen/datacontrol.html
@@ -27,7 +27,11 @@ Please read the 
 
  • 1. Type Definitions
+
    • 
+
  • 
+                    1.2. EventType
+
    • 
+
 
 
  • 2. Interfaces
 
    • 
@@ -76,7 +82,10 @@ Please read the DataControlConsumerObject
-
+
+
    long addChangeListener (DataControlChangeCallback dataChangeCallback, optional ErrorCallback? errorCallback)
    
+
    void removeChangeListener (long watchId)
    
+
 
 
 SQLDataControlConsumer
@@ -117,6 +126,10 @@ Please read the onsuccess (DOMString[] values, unsigned long reqid)
    +DataControlChangeCallback +
    void onsuccess (EventType type, RowData data)
    + + RowData @@ -135,6 +148,33 @@ Please read the +

    1.2. EventType

    +
    + Specifies the data change event types. The possible values are: +
    +
        enum EventType { "SQL_UPDATE", "SQL_INSERT", "SQL_DELETE", "MAP_SET", "MAP_ADD", "MAP_REMOVE"};
    +

    + Since: + 4.0 +

    +
    +
      +
    • +SQL_UPDATE - SQL update event
      • +
    • +SQL_INSERT - SQL insert event
      • +
    • +SQL_DELETE - SQL delete event
      • +
    • +MAP_SET - Map update event
      • +
    • +MAP_ADD - Map add event
      • +
    • +MAP_REMOVE - Map remove event
      • +
    +
    +

    2. Interfaces

    @@ -267,12 +307,17 @@ catch (err)

    2.3. DataControlConsumerObject

    - This interface provides common attributes for other derived DataControlConsumerObject. + This interface provides common attributes and methods for other derived DataControlConsumerObject. 
        [NoInterfaceObject] interface DataControlConsumerObject {
         readonly attribute DataType type;
         readonly attribute DOMString providerId;
         readonly attribute DOMString dataId;
+
+        long addChangeListener(DataControlChangeCallback dataChangeCallback,
+                               optional ErrorCallback? errorCallback) raises(WebAPIException);
+
+        void removeChangeListener(long watchId) raises(WebAPIException);
     };

    Since: @@ -315,6 +360,221 @@ The string consists of one or more components, separated by a slash('/').

    +
    +

    Methods

    +
    +
    +addChangeListener +
    +
    +
    + Adds a listener to receive notifications about provider data changes. +
    +
    long addChangeListener(DataControlChangeCallback dataChangeCallback, optional ErrorCallback? errorCallback);
+
    +

    + Since: + 4.0 +

    +
    +

    +The ErrorCallback method is launched with these error types: +

    +
      +
    • +IOError - If a DB operation has failed.
      • +
    +
    +

    + Privilege level: + public +

    +

    + Privilege: + http://tizen.org/privilege/datasharing +

    +

    + Privilege: + http://tizen.org/privilege/appmanager.launch +

    +
    +

    Parameters:

    +
      +
    • +dataChangeCallback: + Callback method to be invoked when received data changed notification from provider application. +
      • +
    • +errorCallback [optional] [nullable]: + Callback method to be invoked if provider changes cannot be watched. +
      • +
    +
    +
    +

    Return value:

    + long An identifier used to clear the watch subscription. +
    +
    +

    Exceptions:

    +
    • WebAPIException
        +

      • + with error type TypeMismatchError, if any input parameter +is not compatible with the expected type for that parameter. +

        • +

      • + with error type SecurityError, if the application does not have the privilege to call this method. +

        • +
      +
    +
    +
    +

    Code example:

     var watcherId = 0;
+
+ function dataChangeSuccessCallback(eventType, rowData)
+ {
+   console.log("Operation " + eventType + " was performed");
+   console.log("Data changed:");
+   for (var i = 0; i < rowData.columns.length; i++)
+   {
+     console.log("column " + rowData.columns[i] + " value " + rowData.values[i]);
+   }
+ }
+
+ function errorCallback(error)
+ {
+   console.log("The following error occurred: " +  error.name);
+ }
+
+ try
+ {
+   var rowData =
+   {
+     columns : ["WORD", "WORD_DESC"] ,
+     values  : ["'tizen1'", "'tizen2'"]
+   };
+
+   watcherId = globalSQLConsumer.addChangeListener(dataChangeSuccessCallback, errorCallback);
+   console.log("Change listener has been added with watchId = " + watcherId);
+
+   /* Define globalReqId before */
+   /* Increases globalReqId for uniqueness */
+   globalReqId++;
+   globalSQLConsumer.insert(globalReqId, rowData);
+ }
+ catch (err)
+ {
+   console.log(err.name + ": " + err.message);
+ }
+
    +
    +
    +

    Output example:

     Change listener has been added with watchId = 1
+ Operation SQL_INSERT was performed
+ Data changed:
+ column WORD value 'tizen1'
+ column WORD_DESC value 'tizen2'
+
    +
    +
    +
    +removeChangeListener +
    +
    +
    + Removes data change listener. +
    +
    void removeChangeListener(long watchId);
+
    +

    + Since: + 4.0 +

    +
    +

    +If the watchId argument is valid and corresponds to a subscription already in +place, the watch process must immediately stop and no further callbacks must be +invoked. If the watchId argument is not valid or does not correspond to a +valid subscription, the method should return without any further action. +

    +
    +

    + Privilege level: + public +

    +

    + Privilege: + http://tizen.org/privilege/datasharing +

    +

    + Privilege: + http://tizen.org/privilege/appmanager.launch +

    +
    +

    Parameters:

    +
      +
    • +watchId: + Subscription identifier. +
      • +
    +
    +
    +

    Exceptions:

    +
    • WebAPIException
        +

      • + with error type SecurityError, if the application does not have the privilege to call this method. +

        • +

      • + with error type IOError, if a DB operation has failed. +

        • +
      +
    +
    +
    +

    Code example:

     var watcherId = 0;
+
+ function dataChangeSuccessCallback(type, rowData)
+ {
+   console.log("Operation " + type + " was performed");
+   console.log("Data changed:");
+   for (var i = 0; i < rowData.columns.length; i++)
+   {
+     console.log("column " + rowData.columns[i] + " value " + rowData.values[i]);
+   }
+ }
+
+ try
+ {
+   var rowData =
+   {
+     columns : ["WORD", "WORD_DESC"] ,
+     values  : ["'tizen1'", "'tizen2'"]
+   };
+
+   watcherId = globalSQLConsumer.addChangeListener(dataChangeSuccessCallback);
+   console.log("Change listener has been added with watchId = " + watcherId);
+   /* Remove addChangeListener */
+   globalSQLConsumer.removeChangeListener(watcherId);
+   console.log("removeChangeListener was invoked");
+   /* Define globalReqId before */
+   /* Increases globalReqId for uniqueness */
+   globalReqId++;
+   globalSQLConsumer.insert(globalReqId, rowData);
+ }
+ catch (err)
+ {
+   console.log(err.name +": " + err.message);
+ }
+
    +
    +
    +

    Output example:

     Change listener has been added with watchId = 1
+ removeChangeListener was invoked
+
    +
    +
    +
    +

    2.4. SQLDataControlConsumer

    @@ -395,9 +655,6 @@ The string consists of one or more components, separated by a slash('/'). with error type TypeMismatchError, if the parameter type is not compatible with the expected type for that parameter.

  • - with error type InvalidValuesError, if the passed parameter is not available on the data provider side or platform or if an SQL query with invalid parameters has been made. -

    • -

  • with error type IOError, if a DB operation has failed.

  • @@ -493,9 +750,6 @@ catch (err) with error type TypeMismatchError, if the parameter type is not compatible with the expected type for that parameter.

  • - with error type InvalidValuesError, if the passed parameter is not available on the data provider side or platform or if an SQL query with invalid parameters has been made. -

    • -

  • with error type IOError, if a DB operation has failed.

  • @@ -587,9 +841,6 @@ catch (err) with error type TypeMismatchError, if the parameter type is not compatible with the expected type for that parameter.

  • - with error type InvalidValuesError, if the passed parameter is not available on the data provider side or platform or if an SQL query with invalid parameters has been made. -

    • -

  • with error type IOError, if a DB operation has failed.

  • @@ -640,11 +891,6 @@ catch (err) Since: 2.4

    -
    -

    -If either of the page or maxNumberPerPage parameters are set to null or are not set, only the first 20 rows are included in the result set. -

    -

    Privilege level: public @@ -700,9 +946,6 @@ If either of the page or maxNumberPerPage parameters are set t with error type TypeMismatchError, if the parameter type is not compatible with the expected type for that parameter.

  • - with error type InvalidValuesError, if the passed parameter is not available on the data provider side or platform or if an SQL query with invalid parameters has been made. -

    • -

  • with error type IOError, if a DB operation has failed.

  • @@ -846,9 +1089,6 @@ catch (err) with error type TypeMismatchError, if the parameter type is not compatible with the expected type for that parameter.

  • - with error type InvalidValuesError, if the passed parameter is not available on the data provider side or platform. -

    • -

  • with error type IOError, if a DB operation has failed.

  • @@ -939,9 +1179,6 @@ catch (err) with error type TypeMismatchError, if the parameter type is not compatible with the expected type for that parameter.

  • - with error type InvalidValuesError, if the passed parameter is not available on the data provider side or platform. -

    • -

  • with error type IOError, if a DB operation has failed.

  • @@ -1031,9 +1268,6 @@ catch (err) with error type TypeMismatchError, if the parameter type is not compatible with the expected type for that parameter.

  • - with error type InvalidValuesError, if the passed parameter is not available on the data provider side or platform. -

    • -

  • with error type IOError, if a DB operation has failed.

  • @@ -1131,9 +1365,6 @@ catch (err) with error type TypeMismatchError, if the parameter type is not compatible with the expected type for that parameter.

  • - with error type InvalidValuesError, if the passed parameter is not available on the data provider side or platform. -

    • -

  • with error type IOError, if a DB operation has failed.

  • @@ -1398,8 +1629,53 @@ catch (err)

    • +
    +

    2.11. DataControlChangeCallback

    +
    + This interface provides a DataControlChangeCallback for addChangeListener method. +
    +
        [Callback=FunctionOnly, NoInterfaceObject] interface DataControlChangeCallback {
+        void onsuccess(EventType type, RowData data);
+    };
    +

    + Since: + 4.0 +

    +
    +

    Methods

    +
    +
    +onsuccess +
    +
    +
    + Called when the data is modified. +
    +
    void onsuccess(EventType type, RowData data);
+
    +

    + Since: + 4.0 +

    +
    +

    Parameters:

    +
      +
    • +type: + A type of performed operation. +
      • +
    • +data: + Object with information of columns and values of changed data. Actual data to be returned depends on data returned by data control provider application. Please refer to native documentation. +
      • +
    +
    +
    +
    +
    +
    -

    2.11. RowData

    +

    2.12. RowData

    The dictionary represents RowData holding 1 row of SQL selection results from another application.
    @@ -1442,6 +1718,8 @@ catch (err) 
    module DataControl {
     enum DataType { "MAP", "SQL"};
 
+    enum EventType { "SQL_UPDATE", "SQL_INSERT", "SQL_DELETE", "MAP_SET", "MAP_ADD", "MAP_REMOVE"};
+
     [NoInterfaceObject] interface DataControlManagerObject {
         readonly attribute DataControlManager datacontrol;
     };
@@ -1456,6 +1734,11 @@ catch (err)
         readonly attribute DataType type;
         readonly attribute DOMString providerId;
         readonly attribute DOMString dataId;
+
+        long addChangeListener(DataControlChangeCallback dataChangeCallback,
+                               optional ErrorCallback? errorCallback) raises(WebAPIException);
+
+        void removeChangeListener(long watchId) raises(WebAPIException);
     };
 
     [NoInterfaceObject] interface SQLDataControlConsumer : DataControlConsumerObject {
@@ -1515,6 +1798,10 @@ catch (err)
         void onsuccess(DOMString[] values, unsigned long reqid);
     };
 
+    [Callback=FunctionOnly, NoInterfaceObject] interface DataControlChangeCallback {
+        void onsuccess(EventType type, RowData data);
+    };
+
 
     dictionary RowData {
         DOMString[] columns;
diff --git a/org.tizen.web.apireference/html/device_api/wearable/tizen/datacontrol.html b/org.tizen.web.apireference/html/device_api/wearable/tizen/datacontrol.html
index 1bc1317..84b917a 100755
--- a/org.tizen.web.apireference/html/device_api/wearable/tizen/datacontrol.html
+++ b/org.tizen.web.apireference/html/device_api/wearable/tizen/datacontrol.html
@@ -25,9 +25,14 @@ Please read the 
-
  • 1. Type Definitions
 
    • 
 
  • 2. Interfaces
 
    • 
@@ -76,7 +83,10 @@ Please read the DataControlConsumerObject
-
+
+
    long addChangeListener (DataControlChangeCallback dataChangeCallback, optional ErrorCallback? errorCallback)
    
+
    void removeChangeListener (long watchId)
    
+
 
 
 SQLDataControlConsumer
@@ -117,6 +127,10 @@ Please read the onsuccess (DOMString[] values, unsigned long reqid)
    +DataControlChangeCallback +
    void onsuccess (EventType type, RowData data)
    + + RowData @@ -135,6 +149,33 @@ Please read the +

    1.2. EventType

    +
    + Specifies the data change event types. The possible values are: +
    +
        enum EventType { "SQL_UPDATE", "SQL_INSERT", "SQL_DELETE", "MAP_SET", "MAP_ADD", "MAP_REMOVE"};
    +

    + Since: + 4.0 +

    +
    +
      +
    • +SQL_UPDATE - SQL update event
      • +
    • +SQL_INSERT - SQL insert event
      • +
    • +SQL_DELETE - SQL delete event
      • +
    • +MAP_SET - Map update event
      • +
    • +MAP_ADD - Map add event
      • +
    • +MAP_REMOVE - Map remove event
      • +
    +
    +

    2. Interfaces

    @@ -267,12 +308,17 @@ catch (err)

    2.3. DataControlConsumerObject

    - This interface provides common attributes for other derived DataControlConsumerObject. + This interface provides common attributes and methods for other derived DataControlConsumerObject. 
        [NoInterfaceObject] interface DataControlConsumerObject {
         readonly attribute DataType type;
         readonly attribute DOMString providerId;
         readonly attribute DOMString dataId;
+
+        long addChangeListener(DataControlChangeCallback dataChangeCallback,
+                               optional ErrorCallback? errorCallback) raises(WebAPIException);
+
+        void removeChangeListener(long watchId) raises(WebAPIException);
     };

    Since: @@ -315,6 +361,221 @@ The string consists of one or more components, separated by a slash('/').

    +
    +

    Methods

    +
    +
    +addChangeListener +
    +
    +
    + Adds a listener to receive notifications about provider data changes. +
    +
    long addChangeListener(DataControlChangeCallback dataChangeCallback, optional ErrorCallback? errorCallback);
+
    +

    + Since: + 4.0 +

    +
    +

    +The ErrorCallback method is launched with these error types: +

    +
      +
    • +IOError - If a DB operation has failed.
      • +
    +
    +

    + Privilege level: + public +

    +

    + Privilege: + http://tizen.org/privilege/datasharing +

    +

    + Privilege: + http://tizen.org/privilege/appmanager.launch +

    +
    +

    Parameters:

    +
      +
    • +dataChangeCallback: + Callback method to be invoked when received data changed notification from provider application. +
      • +
    • +errorCallback [optional] [nullable]: + Callback method to be invoked if provider changes cannot be watched. +
      • +
    +
    +
    +

    Return value:

    + long An identifier used to clear the watch subscription. +
    +
    +

    Exceptions:

    +
    • WebAPIException
        +

      • + with error type TypeMismatchError, if any input parameter +is not compatible with the expected type for that parameter. +

        • +

      • + with error type SecurityError, if the application does not have the privilege to call this method. +

        • +
      +
    +
    +
    +

    Code example:

     var watcherId = 0;
+
+ function dataChangeSuccessCallback(eventType, rowData)
+ {
+   console.log("Operation " + eventType + " was performed");
+   console.log("Data changed:");
+   for (var i = 0; i < rowData.columns.length; i++)
+   {
+     console.log("column " + rowData.columns[i] + " value " + rowData.values[i]);
+   }
+ }
+
+ function errorCallback(error)
+ {
+   console.log("The following error occurred: " +  error.name);
+ }
+
+ try
+ {
+   var rowData =
+   {
+     columns : ["WORD", "WORD_DESC"] ,
+     values  : ["'tizen1'", "'tizen2'"]
+   };
+
+   watcherId = globalSQLConsumer.addChangeListener(dataChangeSuccessCallback, errorCallback);
+   console.log("Change listener has been added with watchId = " + watcherId);
+
+   /* Define globalReqId before */
+   /* Increases globalReqId for uniqueness */
+   globalReqId++;
+   globalSQLConsumer.insert(globalReqId, rowData);
+ }
+ catch (err)
+ {
+   console.log(err.name + ": " + err.message);
+ }
+
    +
    +
    +

    Output example:

     Change listener has been added with watchId = 1
+ Operation SQL_INSERT was performed
+ Data changed:
+ column WORD value 'tizen1'
+ column WORD_DESC value 'tizen2'
+
    +
    +
    +
    +removeChangeListener +
    +
    +
    + Removes data change listener. +
    +
    void removeChangeListener(long watchId);
+
    +

    + Since: + 4.0 +

    +
    +

    +If the watchId argument is valid and corresponds to a subscription already in +place, the watch process must immediately stop and no further callbacks must be +invoked. If the watchId argument is not valid or does not correspond to a +valid subscription, the method should return without any further action. +

    +
    +

    + Privilege level: + public +

    +

    + Privilege: + http://tizen.org/privilege/datasharing +

    +

    + Privilege: + http://tizen.org/privilege/appmanager.launch +

    +
    +

    Parameters:

    +
      +
    • +watchId: + Subscription identifier. +
      • +
    +
    +
    +

    Exceptions:

    +
    • WebAPIException
        +

      • + with error type SecurityError, if the application does not have the privilege to call this method. +

        • +

      • + with error type IOError, if a DB operation has failed. +

        • +
      +
    +
    +
    +

    Code example:

     var watcherId = 0;
+
+ function dataChangeSuccessCallback(type, rowData)
+ {
+   console.log("Operation " + type + " was performed");
+   console.log("Data changed:");
+   for (var i = 0; i < rowData.columns.length; i++)
+   {
+     console.log("column " + rowData.columns[i] + " value " + rowData.values[i]);
+   }
+ }
+
+ try
+ {
+   var rowData =
+   {
+     columns : ["WORD", "WORD_DESC"] ,
+     values  : ["'tizen1'", "'tizen2'"]
+   };
+
+   watcherId = globalSQLConsumer.addChangeListener(dataChangeSuccessCallback);
+   console.log("Change listener has been added with watchId = " + watcherId);
+   /* Remove addChangeListener */
+   globalSQLConsumer.removeChangeListener(watcherId);
+   console.log("removeChangeListener was invoked");
+   /* Define globalReqId before */
+   /* Increases globalReqId for uniqueness */
+   globalReqId++;
+   globalSQLConsumer.insert(globalReqId, rowData);
+ }
+ catch (err)
+ {
+   console.log(err.name +": " + err.message);
+ }
+
    +
    +
    +

    Output example:

     Change listener has been added with watchId = 1
+ removeChangeListener was invoked
+
    +
    +
    +
    +

    2.4. SQLDataControlConsumer

    @@ -639,6 +900,9 @@ catch (err) Privilege: http://tizen.org/privilege/datacontrol.consumer

    +

    Remark : + order is supported since Tizen 3.0 +

    Parameters:

      @@ -1366,8 +1630,53 @@ catch (err)
    +
    +

    2.11. DataControlChangeCallback

    +
    + This interface provides a DataControlChangeCallback for addChangeListener method. +
    +
        [Callback=FunctionOnly, NoInterfaceObject] interface DataControlChangeCallback {
+        void onsuccess(EventType type, RowData data);
+    };
    +

    + Since: + 4.0 +

    +
    +

    Methods

    +
    +
    +onsuccess +
    +
    +
    + Called when the data is modified. +
    +
    void onsuccess(EventType type, RowData data);
+
    +

    + Since: + 4.0 +

    +
    +

    Parameters:

    +
      +
    • +type: + A type of performed operation. +
      • +
    • +data: + Object with information of columns and values of changed data. Actual data to be returned depends on data returned by data control provider application. Please refer to native documentation. +
      • +
    +
    +
    +
    +
    +
    -

    2.11. RowData

    +

    2.12. RowData

    The dictionary represents RowData holding 1 row of SQL selection results from another application.
    @@ -1410,6 +1719,8 @@ catch (err) 
    module DataControl {
     enum DataType { "MAP", "SQL"};
 
+    enum EventType { "SQL_UPDATE", "SQL_INSERT", "SQL_DELETE", "MAP_SET", "MAP_ADD", "MAP_REMOVE"};
+
     [NoInterfaceObject] interface DataControlManagerObject {
         readonly attribute DataControlManager datacontrol;
     };
@@ -1424,6 +1735,11 @@ catch (err)
         readonly attribute DataType type;
         readonly attribute DOMString providerId;
         readonly attribute DOMString dataId;
+
+        long addChangeListener(DataControlChangeCallback dataChangeCallback,
+                               optional ErrorCallback? errorCallback) raises(WebAPIException);
+
+        void removeChangeListener(long watchId) raises(WebAPIException);
     };
 
     [NoInterfaceObject] interface SQLDataControlConsumer : DataControlConsumerObject {
@@ -1471,7 +1787,7 @@ catch (err)
     };
 
     [Callback=FunctionOnly, NoInterfaceObject] interface DataControlInsertSuccessCallback {
-    void onsuccess(unsigned long reqId, long insertRowId);
+        void onsuccess(unsigned long reqId, long insertRowId);
     };
 
 
@@ -1483,6 +1799,10 @@ catch (err)
         void onsuccess(DOMString[] values, unsigned long reqid);
     };
 
+    [Callback=FunctionOnly, NoInterfaceObject] interface DataControlChangeCallback {
+        void onsuccess(EventType type, RowData data);
+    };
+
 
     dictionary RowData {
         DOMString[] columns;