<li><a href="#prerequisites">Prerequisites</a></li>
<li><a href="#map">Managing Data in Key-value Pairs</a></li>
<li><a href="#sql">Managing SQL-type Data</a></li>
+ <li><a href="#listener">Monitoring Provider Data Changes</a></li>
</ul>
<p class="toc-title">Related Info</p>
<ul class="toc">
<div id="container"><div id="contents"><div class="content">
<h1>Data Control</h1>
- <p>Data control allows you to read and modify data stored and provided by another application. The application storing and controlling the data is called a DataControl provider application. The application using the data is called a DataControl consumer application. A single DataControl provider can serve multiple DataControl consumers.</p>
+ <p>Data control allows you to read and modify data stored and provided by another application, and monitor changes in that data. The application storing and controlling the data is called a DataControl provider application. The application using the data is called a DataControl consumer application. A single DataControl provider can serve multiple DataControl consumers.</p>
<p>The Data Control API is mandatory for both Tizen mobile and wearable profiles, which means that it is supported in all mobile and wearable applications. All mandatory APIs are supported on the Tizen Emulators.</p>
<p>The main data control features are:</p>
<p>You can <a href="#map">get, add, update, and remove values assigned to a key</a> using the <code>MappedDataControlConsumer</code> interface (in <a href="../../../../org.tizen.web.apireference/html/device_api/mobile/tizen/datacontrol.html#MappedDataControlConsumer">mobile</a>, <a href="../../../../org.tizen.web.apireference/html/device_api/wearable/tizen/datacontrol.html#MappedDataControlConsumer">wearable</a>, and <a href="../../../../org.tizen.web.apireference/html/device_api/tv/tizen/datacontrol.html#MappedDataControlConsumer">TV</a> applications).</p></li>
<li>Complex data storage using a SQL-type database and queries
<p>You can <a href="#sql">select, insert, update, and remove data</a> using the <code>SQLDataControlConsumer</code> interface (in <a href="../../../../org.tizen.web.apireference/html/device_api/mobile/tizen/datacontrol.html#SQLDataControlConsumer">mobile</a>, <a href="../../../../org.tizen.web.apireference/html/device_api/wearable/tizen/datacontrol.html#SQLDataControlConsumer">wearable</a>, and <a href="../../../../org.tizen.web.apireference/html/device_api/tv/tizen/datacontrol.html#SQLDataControlConsumer">TV</a> applications).</p></li>
+ <li>Provider data change monitoring
+ <p>You can <a href="#listener">receive notifications</a> about changes in DataControl provider applications.</p></li>
</ul>
<h2 id="prerequisites">Prerequisites</h2>
-<p>To use the Data Control API (in <a href="../../../../org.tizen.web.apireference/html/device_api/mobile/tizen/datacontrol.html">mobile</a>, <a href="../../../../org.tizen.web.apireference/html/device_api/wearable/tizen/datacontrol.html">wearable</a>, and <a href="../../../../org.tizen.web.apireference/html/device_api/tv/tizen/datacontrol.html">TV</a> applications), the application has to request permission by adding the following privilege to the <code>config.xml</code> file:</p>
+<p>To use the Data Control API (in <a href="../../../../org.tizen.web.apireference/html/device_api/mobile/tizen/datacontrol.html">mobile</a>, <a href="../../../../org.tizen.web.apireference/html/device_api/wearable/tizen/datacontrol.html">wearable</a>, and <a href="../../../../org.tizen.web.apireference/html/device_api/tv/tizen/datacontrol.html">TV</a> applications), the application has to request permission by adding the following privileges to the <code>config.xml</code> file:</p>
<pre class="prettyprint">
<tizen:privilege name="http://tizen.org/privilege/datacontrol.consumer"/>
-</pre>
+<!--To receive DataControl provider data change notifications-->
+<tizen:privilege name="http://tizen.org/privilege/datasharing"/>
+<tizen:privilege name="http://tizen.org/privilege/appmanager.launch"/>
+</pre>
<h2 id="map" name="map">Managing Data in Key-value Pairs</h2>
<li><p>To retrieve a <code>SQLDataControlConsumer</code> object (in <a href="../../../../org.tizen.web.apireference/html/device_api/mobile/tizen/datacontrol.html#SQLDataControlConsumer">mobile</a>, <a href="../../../../org.tizen.web.apireference/html/device_api/wearable/tizen/datacontrol.html#SQLDataControlConsumer">wearable</a>, and <a href="../../../../org.tizen.web.apireference/html/device_api/tv/tizen/datacontrol.html#SQLDataControlConsumer">TV</a> applications), use the <code>getDataControlConsumer()</code> method of the <code>DataControlManager</code> interface (in <a href="../../../../org.tizen.web.apireference/html/device_api/mobile/tizen/datacontrol.html#DataControlManager">mobile</a>, <a href="../../../../org.tizen.web.apireference/html/device_api/wearable/tizen/datacontrol.html#DataControlManager">wearable</a>, and <a href="../../../../org.tizen.web.apireference/html/device_api/tv/tizen/datacontrol.html#DataControlManager">TV</a> applications). This object allows accessing the data stored by the DataControl provider.</p>
<p>You need a running DataControl provider application, which uses the <code>"http://tizen.org/datacontrol/provider/DictionaryDataControlProvider"</code> provider ID.</p>
<pre class="prettyprint">
-/* Get SQL type DataControlConsumerObject */
+/* Get the SQL type DataControlConsumerObject */
try {
var globalSQLConsumer = tizen.datacontrol.getDataControlConsumer('http://tizen.org/datacontrol/provider/DictionaryDataControlProvider', 'Dictionary', 'SQL');
}
</pre> </li></ul></li>
</ol>
+<h2 id="listener" name="listener">Monitoring Provider Data Changes</h2>
+
+<p>Learning how to add a listener allows you to receive notifications about DataControl provider data changes:</p>
+<ol>
+ <li>
+ <p>To retrieve a <code>SQLDataControlConsumer</code> object (in <a href="../../../../org.tizen.web.apireference/html/device_api/mobile/tizen/datacontrol.html#SQLDataControlConsumer">mobile</a>, <a href="../../../../org.tizen.web.apireference/html/device_api/wearable/tizen/datacontrol.html#SQLDataControlConsumer">wearable</a>, and <a href="../../../../org.tizen.web.apireference/html/device_api/tv/tizen/datacontrol.html#SQLDataControlConsumer">TV</a> applications), use the <code>getDataControlConsumer()</code> method of the <code>DataControlManager</code> interface (in <a href="../../../../org.tizen.web.apireference/html/device_api/mobile/tizen/datacontrol.html#DataControlManager">mobile</a>, <a href="../../../../org.tizen.web.apireference/html/device_api/wearable/tizen/datacontrol.html#DataControlManager">wearable</a>, and <a href="../../../../org.tizen.web.apireference/html/device_api/tv/tizen/datacontrol.html#DataControlManager">TV</a> applications). This object allows you to monitor changes in the DataControl provider data.</p>
+ <p>You need a running DataControl provider application, which uses the <code>"http://tizen.org/datacontrol/provider/DictionaryDataControlProvider"</code> provider ID.</p>
+<pre class="prettyprint">
+/* 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);
+}
+</pre>
+ </li>
+ <li>
+ <p>Define a change callback, error callback, and needed variables:</p>
+<pre class="prettyprint">
+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);
+}
+</pre>
+ </li>
+ <li>
+ <p>Register the listeners that trigger the change callback when the provider data changes:</p>
+<pre class="prettyprint">
+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);
+}
+</pre>
+ </li>
+ <li>
+ <p>When the notifications are no longer needed, stop them with the <code>removeChangeListener()</code> method:</p>
+<pre class="prettyprint">
+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);
+}
+</pre>
+ </li>
+</ol>
+
+<div class="note">
+ <strong>Note</strong>
+ 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.
+ <p>The data sending implementation determines the actual change data returned to the DataControl consumer. For more information on the DataControl provider implementation, see <a href="../../native/app_management/data_control_n.htm#map3">Monitoring Data Changes</a>.</p>
+</div>
+
<script type="text/javascript" src="../../scripts/jquery.zclip.min.js"></script>
<script type="text/javascript" src="../../scripts/showhide.js"></script>
</div></div></div>
</script>
</body>
-</html>
\ No newline at end of file
+</html>
</p>
<h2>Table of Contents</h2>
<ul class="toc">
-<li>1. <a href="#typedefs-section">Type Definitions</a><ul class="toc"><li>1.1. <a href="#DataType">DataType</a>
-</li></ul>
+<li>1. <a href="#typedefs-section">Type Definitions</a><ul class="toc">
+<li>
+ 1.1. <a href="#DataType">DataType</a>
+</li>
+<li>
+ 1.2. <a href="#EventType">EventType</a>
+</li>
+</ul>
</li>
<li>2. <a href="#interfaces-section">Interfaces</a><ul class="toc">
<li>2.1. <a href="#DataControlManagerObject">DataControlManagerObject</a>
</li>
<li>2.10. <a href="#DataControlGetValueSuccessCallback">DataControlGetValueSuccessCallback</a>
</li>
-<li>2.11. <a href="#RowData">RowData</a>
+<li>2.11. <a href="#DataControlChangeCallback">DataControlChangeCallback</a>
+</li>
+<li>2.12. <a href="#RowData">RowData</a>
</li>
</ul>
</li>
</tr>
<tr>
<td><a href="#DataControlManager">DataControlManager</a></td>
-<td>
-<a href="#DataControlConsumerObject">DataControlConsumerObject</a> <a href="#DataControlManager::getDataControlConsumer">getDataControlConsumer</a> (DOMString providerId, DOMString dataId, <a href="#DataType">DataType</a> type)</td>
+<td><div>
+<a href="#DataControlConsumerObject">DataControlConsumerObject</a> <a href="#DataControlManager::getDataControlConsumer">getDataControlConsumer</a> (DOMString providerId, DOMString dataId, <a href="#DataType">DataType</a> type)</div></td>
</tr>
<tr>
<td><a href="#DataControlConsumerObject">DataControlConsumerObject</a></td>
-<td></td>
+<td>
+<div>long <a href="#DataControlConsumerObject::addChangeListener">addChangeListener</a> (<a href="#DataControlChangeCallback">DataControlChangeCallback</a> dataChangeCallback, optional <a href="tizen.html#ErrorCallback">ErrorCallback</a>? errorCallback)</div>
+<div>void <a href="#DataControlConsumerObject::removeChangeListener">removeChangeListener</a> (long watchId)</div>
+</td>
</tr>
<tr>
<td><a href="#SQLDataControlConsumer">SQLDataControlConsumer</a></td>
-<td>void <a href="#SQLDataControlConsumer::insert">insert</a> (unsigned long reqId, <a href="#RowData">RowData</a> insertionData, optional <a href="#DataControlInsertSuccessCallback">DataControlInsertSuccessCallback</a>? successCallback, optional <a href="#DataControlErrorCallback">DataControlErrorCallback</a>? errorCallback)<br>
- void <a href="#SQLDataControlConsumer::update">update</a> (unsigned long reqId, <a href="#RowData">RowData</a> updateData, DOMString where, optional <a href="#DataControlSuccessCallback">DataControlSuccessCallback</a>? successCallback, optional <a href="#DataControlErrorCallback">DataControlErrorCallback</a>? errorCallback)<br>
- void <a href="#SQLDataControlConsumer::remove">remove</a> (unsigned long reqId, DOMString where, optional <a href="#DataControlSuccessCallback">DataControlSuccessCallback</a>? successCallback, optional <a href="#DataControlErrorCallback">DataControlErrorCallback</a>? errorCallback)<br>
- void <a href="#SQLDataControlConsumer::select">select</a> (unsigned long reqId, DOMString[] columns, DOMString where, <a href="#DataControlSelectSuccessCallback">DataControlSelectSuccessCallback</a> successCallback, optional <a href="#DataControlErrorCallback">DataControlErrorCallback</a>? errorCallback, optional unsigned long? page, optional unsigned long? maxNumberPerPage, optional DOMString? order)</td>
+<td>
+<div>void <a href="#SQLDataControlConsumer::insert">insert</a> (unsigned long reqId, <a href="#RowData">RowData</a> insertionData, optional <a href="#DataControlInsertSuccessCallback">DataControlInsertSuccessCallback</a>? successCallback, optional <a href="#DataControlErrorCallback">DataControlErrorCallback</a>? errorCallback)</div>
+<div>void <a href="#SQLDataControlConsumer::update">update</a> (unsigned long reqId, <a href="#RowData">RowData</a> updateData, DOMString where, optional <a href="#DataControlSuccessCallback">DataControlSuccessCallback</a>? successCallback, optional <a href="#DataControlErrorCallback">DataControlErrorCallback</a>? errorCallback)</div>
+<div>void <a href="#SQLDataControlConsumer::remove">remove</a> (unsigned long reqId, DOMString where, optional <a href="#DataControlSuccessCallback">DataControlSuccessCallback</a>? successCallback, optional <a href="#DataControlErrorCallback">DataControlErrorCallback</a>? errorCallback)</div>
+<div>void <a href="#SQLDataControlConsumer::select">select</a> (unsigned long reqId, DOMString[] columns, DOMString where, <a href="#DataControlSelectSuccessCallback">DataControlSelectSuccessCallback</a> successCallback, optional <a href="#DataControlErrorCallback">DataControlErrorCallback</a>? errorCallback, optional unsigned long? page, optional unsigned long? maxNumberPerPage, optional DOMString? order)</div>
+</td>
</tr>
<tr>
<td><a href="#MappedDataControlConsumer">MappedDataControlConsumer</a></td>
-<td>void <a href="#MappedDataControlConsumer::addValue">addValue</a> (unsigned long reqId, DOMString key, DOMString value, optional <a href="#DataControlSuccessCallback">DataControlSuccessCallback</a>? successCallback, optional <a href="#DataControlErrorCallback">DataControlErrorCallback</a>? errorCallback)<br>
- void <a href="#MappedDataControlConsumer::removeValue">removeValue</a> (unsigned long reqId, DOMString key, DOMString value, <a href="#DataControlSuccessCallback">DataControlSuccessCallback</a> successCallback, optional <a href="#DataControlErrorCallback">DataControlErrorCallback</a>? errorCallback)<br>
- void <a href="#MappedDataControlConsumer::getValue">getValue</a> (unsigned long reqId, DOMString key, <a href="#DataControlGetValueSuccessCallback">DataControlGetValueSuccessCallback</a> successCallback, optional <a href="#DataControlErrorCallback">DataControlErrorCallback</a>? errorCallback)<br>
- void <a href="#MappedDataControlConsumer::updateValue">updateValue</a> (unsigned long reqId, DOMString key, DOMString oldValue, DOMString newValue, <a href="#DataControlSuccessCallback">DataControlSuccessCallback</a> successCallback, optional <a href="#DataControlErrorCallback">DataControlErrorCallback</a>? errorCallback)</td>
+<td>
+<div>void <a href="#MappedDataControlConsumer::addValue">addValue</a> (unsigned long reqId, DOMString key, DOMString value, optional <a href="#DataControlSuccessCallback">DataControlSuccessCallback</a>? successCallback, optional <a href="#DataControlErrorCallback">DataControlErrorCallback</a>? errorCallback)</div>
+<div>void <a href="#MappedDataControlConsumer::removeValue">removeValue</a> (unsigned long reqId, DOMString key, DOMString value, <a href="#DataControlSuccessCallback">DataControlSuccessCallback</a> successCallback, optional <a href="#DataControlErrorCallback">DataControlErrorCallback</a>? errorCallback)</div>
+<div>void <a href="#MappedDataControlConsumer::getValue">getValue</a> (unsigned long reqId, DOMString key, <a href="#DataControlGetValueSuccessCallback">DataControlGetValueSuccessCallback</a> successCallback, optional <a href="#DataControlErrorCallback">DataControlErrorCallback</a>? errorCallback)</div>
+<div>void <a href="#MappedDataControlConsumer::updateValue">updateValue</a> (unsigned long reqId, DOMString key, DOMString oldValue, DOMString newValue, <a href="#DataControlSuccessCallback">DataControlSuccessCallback</a> successCallback, optional <a href="#DataControlErrorCallback">DataControlErrorCallback</a>? errorCallback)</div>
+</td>
</tr>
<tr>
<td><a href="#DataControlSuccessCallback">DataControlSuccessCallback</a></td>
-<td>void <a href="#DataControlSuccessCallback::onsuccess">onsuccess</a> (unsigned long reqId)</td>
+<td><div>void <a href="#DataControlSuccessCallback::onsuccess">onsuccess</a> (unsigned long reqId)</div></td>
</tr>
<tr>
<td><a href="#DataControlErrorCallback">DataControlErrorCallback</a></td>
-<td>void <a href="#DataControlErrorCallback::onerror">onerror</a> (unsigned long reqId, <a href="tizen.html#WebAPIError">WebAPIError</a> error)</td>
+<td><div>void <a href="#DataControlErrorCallback::onerror">onerror</a> (unsigned long reqId, <a href="tizen.html#WebAPIError">WebAPIError</a> error)</div></td>
</tr>
<tr>
<td><a href="#DataControlInsertSuccessCallback">DataControlInsertSuccessCallback</a></td>
-<td>void <a href="#DataControlInsertSuccessCallback::onsuccess">onsuccess</a> (unsigned long reqId, long insertRowId)</td>
+<td><div>void <a href="#DataControlInsertSuccessCallback::onsuccess">onsuccess</a> (unsigned long reqId, long insertRowId)</div></td>
</tr>
<tr>
<td><a href="#DataControlSelectSuccessCallback">DataControlSelectSuccessCallback</a></td>
-<td>void <a href="#DataControlSelectSuccessCallback::onsuccess">onsuccess</a> (<a href="#RowData">RowData</a>[] rows, unsigned long reqId)</td>
+<td><div>void <a href="#DataControlSelectSuccessCallback::onsuccess">onsuccess</a> (<a href="#RowData">RowData</a>[] rows, unsigned long reqId)</div></td>
</tr>
<tr>
<td><a href="#DataControlGetValueSuccessCallback">DataControlGetValueSuccessCallback</a></td>
-<td>void <a href="#DataControlGetValueSuccessCallback::onsuccess">onsuccess</a> (DOMString[] values, unsigned long reqid)</td>
+<td><div>void <a href="#DataControlGetValueSuccessCallback::onsuccess">onsuccess</a> (DOMString[] values, unsigned long reqid)</div></td>
+</tr>
+<tr>
+<td><a href="#DataControlChangeCallback">DataControlChangeCallback</a></td>
+<td><div>void <a href="#DataControlChangeCallback::onsuccess">onsuccess</a> (<a href="#EventType">EventType</a> type, <a href="#RowData">RowData</a> data)</div></td>
</tr>
<tr>
<td><a href="#RowData">RowData</a></td>
2.1
</p>
</div>
+<div class="enum" id="EventType">
+<a class="backward-compatibility-anchor" name="::DataControl::EventType"></a><h3>1.2. EventType</h3>
+<div class="brief">
+ Specifies the data change event types. The possible values are:
+ </div>
+<pre class="webidl prettyprint"> enum EventType { "SQL_UPDATE", "SQL_INSERT", "SQL_DELETE", "MAP_SET", "MAP_ADD", "MAP_REMOVE"};</pre>
+<p><span class="version">
+ Since: </span>
+ 4.0
+ </p>
+<div class="description">
+ <ul>
+ <li>
+SQL_UPDATE - SQL update event </li>
+ <li>
+SQL_INSERT - SQL insert event </li>
+ <li>
+SQL_DELETE - SQL delete event </li>
+ <li>
+MAP_SET - Map update event </li>
+ <li>
+MAP_ADD - Map add event </li>
+ <li>
+MAP_REMOVE - Map remove event </li>
+ </ul>
+ </div>
+</div>
</div>
<div class="interfaces" id="interfaces-section">
<h2>2. Interfaces</h2>
<div class="interface" id="DataControlConsumerObject">
<a class="backward-compatibility-anchor" name="::DataControl::DataControlConsumerObject"></a><h3>2.3. DataControlConsumerObject</h3>
<div class="brief">
- This interface provides common attributes for other derived DataControlConsumerObject.
+ This interface provides common attributes and methods for other derived DataControlConsumerObject.
</div>
<pre class="webidl prettyprint"> [NoInterfaceObject] interface DataControlConsumerObject {
readonly attribute <a href="#DataType">DataType</a> type;
readonly attribute DOMString providerId;
readonly attribute DOMString dataId;
+
+ long addChangeListener(<a href="#DataControlChangeCallback">DataControlChangeCallback</a> dataChangeCallback,
+ optional <a href="tizen.html#ErrorCallback">ErrorCallback</a>? errorCallback) raises(<a href="tizen.html#WebAPIException">WebAPIException</a>);
+
+ void removeChangeListener(long watchId) raises(<a href="tizen.html#WebAPIException">WebAPIException</a>);
};</pre>
<p><span class="version">
Since: </span>
</li>
</ul>
</div>
+<div class="methods">
+<h4>Methods</h4>
+<dl>
+<dt class="method" id="DataControlConsumerObject::addChangeListener">
+<a class="backward-compatibility-anchor" name="::DataControl::DataControlConsumerObject::addChangeListener"></a><code><b><span class="methodName">addChangeListener</span></b></code>
+</dt>
+<dd>
+<div class="brief">
+ Adds a listener to receive notifications about provider data changes.
+ </div>
+<div class="synopsis"><pre class="signature prettyprint">long addChangeListener(<a href="#DataControlChangeCallback">DataControlChangeCallback</a> dataChangeCallback, optional <a href="tizen.html#ErrorCallback">ErrorCallback</a>? errorCallback);
+ </pre></div>
+<p><span class="version">
+ Since: </span>
+ 4.0
+ </p>
+<div class="description">
+ <p>
+The <em>ErrorCallback</em> method is launched with these error types:
+ </p>
+ <ul>
+ <li>
+IOError - If a DB operation has failed. </li>
+ </ul>
+ </div>
+<p><span class="privilegelevel">
+ Privilege level: </span>
+ public
+ </p>
+<p><span class="privilege">
+ Privilege: </span>
+ http://tizen.org/privilege/datasharing
+ </p>
+<p><span class="privilege">
+ Privilege: </span>
+ http://tizen.org/privilege/appmanager.launch
+ </p>
+<div class="parameters">
+<p><span class="param">Parameters:</span></p>
+<ul>
+ <li class="param">
+<span class="name">dataChangeCallback</span>:
+ Callback method to be invoked when received data changed notification from provider application.
+ </li>
+ <li class="param">
+<span class="name">errorCallback</span><span class="optional"> [optional]</span><span class="optional"> [nullable]</span>:
+ Callback method to be invoked if provider changes cannot be watched.
+ </li>
+ </ul>
+</div>
+<div class="returntype">
+<p><span class="return">Return value:</span></p>
+ long An identifier used to clear the watch subscription.
+ </div>
+<div class="exceptionlist">
+<p><span class="except">Exceptions:</span></p>
+ <ul class="exception"><li>WebAPIException<ul>
+<li class="list"><p>
+ with error type TypeMismatchError, if any input parameter
+is not compatible with the expected type for that parameter.
+ </p></li>
+<li class="list"><p>
+ with error type SecurityError, if the application does not have the privilege to call this method.
+ </p></li>
+</ul>
+</li></ul>
+ </div>
+<div class="example">
+<span class="example"><p>Code example:</p></span><pre name="code" class="examplecode prettyprint"> 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);
+ }
+ </pre>
+</div>
+<div class="output">
+<span class="title"><p>Output example:</p></span><pre> Change listener has been added with watchId = 1
+ Operation SQL_INSERT was performed
+ Data changed:
+ column WORD value 'tizen1'
+ column WORD_DESC value 'tizen2'
+ </pre>
+</div>
+</dd>
+<dt class="method" id="DataControlConsumerObject::removeChangeListener">
+<a class="backward-compatibility-anchor" name="::DataControl::DataControlConsumerObject::removeChangeListener"></a><code><b><span class="methodName">removeChangeListener</span></b></code>
+</dt>
+<dd>
+<div class="brief">
+ Removes data change listener.
+ </div>
+<div class="synopsis"><pre class="signature prettyprint">void removeChangeListener(long watchId);
+ </pre></div>
+<p><span class="version">
+ Since: </span>
+ 4.0
+ </p>
+<div class="description">
+ <p>
+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.
+ </p>
+ </div>
+<p><span class="privilegelevel">
+ Privilege level: </span>
+ public
+ </p>
+<p><span class="privilege">
+ Privilege: </span>
+ http://tizen.org/privilege/datasharing
+ </p>
+<p><span class="privilege">
+ Privilege: </span>
+ http://tizen.org/privilege/appmanager.launch
+ </p>
+<div class="parameters">
+<p><span class="param">Parameters:</span></p>
+<ul>
+ <li class="param">
+<span class="name">watchId</span>:
+ Subscription identifier.
+ </li>
+ </ul>
+</div>
+<div class="exceptionlist">
+<p><span class="except">Exceptions:</span></p>
+ <ul class="exception"><li>WebAPIException<ul>
+<li class="list"><p>
+ with error type SecurityError, if the application does not have the privilege to call this method.
+ </p></li>
+<li class="list"><p>
+ with error type IOError, if a DB operation has failed.
+ </p></li>
+</ul>
+</li></ul>
+ </div>
+<div class="example">
+<span class="example"><p>Code example:</p></span><pre name="code" class="examplecode prettyprint"> 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);
+ }
+ </pre>
+</div>
+<div class="output">
+<span class="title"><p>Output example:</p></span><pre> Change listener has been added with watchId = 1
+ removeChangeListener was invoked
+ </pre>
+</div>
+</dd>
+</dl>
+</div>
</div>
<div class="interface" id="SQLDataControlConsumer">
<a class="backward-compatibility-anchor" name="::DataControl::SQLDataControlConsumer"></a><h3>2.4. SQLDataControlConsumer</h3>
{
/* 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 -----");
</dl>
</div>
</div>
+<div class="interface" id="DataControlChangeCallback">
+<a class="backward-compatibility-anchor" name="::DataControl::DataControlChangeCallback"></a><h3>2.11. DataControlChangeCallback</h3>
+<div class="brief">
+ This interface provides a DataControlChangeCallback for addChangeListener method.
+ </div>
+<pre class="webidl prettyprint"> [Callback=FunctionOnly, NoInterfaceObject] interface DataControlChangeCallback {
+ void onsuccess(<a href="#EventType">EventType</a> type, <a href="#RowData">RowData</a> data);
+ };</pre>
+<p><span class="version">
+ Since: </span>
+ 4.0
+ </p>
+<div class="methods">
+<h4>Methods</h4>
+<dl>
+<dt class="method" id="DataControlChangeCallback::onsuccess">
+<a class="backward-compatibility-anchor" name="::DataControl::DataControlChangeCallback::onsuccess"></a><code><b><span class="methodName">onsuccess</span></b></code>
+</dt>
+<dd>
+<div class="brief">
+ Called when the data is modified.
+ </div>
+<div class="synopsis"><pre class="signature prettyprint">void onsuccess(<a href="#EventType">EventType</a> type, <a href="#RowData">RowData</a> data);
+ </pre></div>
+<p><span class="version">
+ Since: </span>
+ 4.0
+ </p>
+<div class="parameters">
+<p><span class="param">Parameters:</span></p>
+<ul>
+ <li class="param">
+<span class="name">type</span>:
+ A type of performed operation.
+ </li>
+ <li class="param">
+<span class="name">data</span>:
+ 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 <a href="https://developer.tizen.org/dev-guide/3.0.0/org.tizen.native.mobile.apireference/group__CAPI__DATA__CONTROL__PROVIDER__MODULE.html#ga319b58f16c7a2b007c64f218129e9042">native</a> documentation.
+ </li>
+ </ul>
+</div>
+</dd>
+</dl>
+</div>
+</div>
<div class="dictionary" id="RowData">
-<a class="backward-compatibility-anchor" name="::DataControl::RowData"></a><h3>2.11. RowData</h3>
+<a class="backward-compatibility-anchor" name="::DataControl::RowData"></a><h3>2.12. RowData</h3>
<div class="brief">
The dictionary represents RowData holding 1 row of SQL selection results from another application.
</div>
<pre class="webidl prettyprint">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 <a href="#DataControlManager">DataControlManager</a> datacontrol;
};
readonly attribute <a href="#DataType">DataType</a> type;
readonly attribute DOMString providerId;
readonly attribute DOMString dataId;
+
+ long addChangeListener(<a href="#DataControlChangeCallback">DataControlChangeCallback</a> dataChangeCallback,
+ optional <a href="tizen.html#ErrorCallback">ErrorCallback</a>? errorCallback) raises(<a href="tizen.html#WebAPIException">WebAPIException</a>);
+
+ void removeChangeListener(long watchId) raises(<a href="tizen.html#WebAPIException">WebAPIException</a>);
};
[NoInterfaceObject] interface SQLDataControlConsumer : <a href="#DataControlConsumerObject">DataControlConsumerObject</a> {
void onsuccess(DOMString[] values, unsigned long reqid);
};
+ [Callback=FunctionOnly, NoInterfaceObject] interface DataControlChangeCallback {
+ void onsuccess(<a href="#EventType">EventType</a> type, <a href="#RowData">RowData</a> data);
+ };
+
dictionary RowData {
DOMString[] columns;
<ul class="toc">
<li>1. <a href="#typedefs-section">Type Definitions</a><ul class="toc"><li>
1.1. <a href="#DataType">DataType</a>
-</li></ul>
+</li>
+<li>
+ 1.2. <a href="#EventType">EventType</a>
+</li>
+</ul>
</li>
<li>2. <a href="#interfaces-section">Interfaces</a><ul class="toc">
<li>2.1. <a href="#DataControlManagerObject">DataControlManagerObject</a>
</li>
<li>2.10. <a href="#DataControlGetValueSuccessCallback">DataControlGetValueSuccessCallback</a>
</li>
-<li>2.11. <a href="#RowData">RowData</a>
+<li>2.11. <a href="#DataControlChangeCallback">DataControlChangeCallback</a>
+</li>
+<li>2.12. <a href="#RowData">RowData</a>
</li>
</ul>
</li>
</tr>
<tr>
<td><a href="#DataControlConsumerObject">DataControlConsumerObject</a></td>
-<td></td>
+<td>
+<div>long <a href="#DataControlConsumerObject::addChangeListener">addChangeListener</a> (<a href="#DataControlChangeCallback">DataControlChangeCallback</a> dataChangeCallback, optional <a href="tizen.html#ErrorCallback">ErrorCallback</a>? errorCallback)</div>
+<div>void <a href="#DataControlConsumerObject::removeChangeListener">removeChangeListener</a> (long watchId)</div>
+</td>
</tr>
<tr>
<td><a href="#SQLDataControlConsumer">SQLDataControlConsumer</a></td>
<td><div>void <a href="#DataControlGetValueSuccessCallback::onsuccess">onsuccess</a> (DOMString[] values, unsigned long reqid)</div></td>
</tr>
<tr>
+<td><a href="#DataControlChangeCallback">DataControlChangeCallback</a></td>
+<td><div>void <a href="#DataControlChangeCallback::onsuccess">onsuccess</a> (<a href="#EventType">EventType</a> type, <a href="#RowData">RowData</a> data)</div></td>
+</tr>
+<tr>
<td><a href="#RowData">RowData</a></td>
<td></td>
</tr>
2.4
</p>
</div>
+<div class="enum" id="EventType">
+<a class="backward-compatibility-anchor" name="::DataControl::EventType"></a><h3>1.2. EventType</h3>
+<div class="brief">
+ Specifies the data change event types. The possible values are:
+ </div>
+<pre class="webidl prettyprint"> enum EventType { "SQL_UPDATE", "SQL_INSERT", "SQL_DELETE", "MAP_SET", "MAP_ADD", "MAP_REMOVE"};</pre>
+<p><span class="version">
+ Since: </span>
+ 4.0
+ </p>
+<div class="description">
+ <ul>
+ <li>
+SQL_UPDATE - SQL update event </li>
+ <li>
+SQL_INSERT - SQL insert event </li>
+ <li>
+SQL_DELETE - SQL delete event </li>
+ <li>
+MAP_SET - Map update event </li>
+ <li>
+MAP_ADD - Map add event </li>
+ <li>
+MAP_REMOVE - Map remove event </li>
+ </ul>
+ </div>
+</div>
</div>
<div class="interfaces" id="interfaces-section">
<h2>2. Interfaces</h2>
<div class="interface" id="DataControlConsumerObject">
<a class="backward-compatibility-anchor" name="::DataControl::DataControlConsumerObject"></a><h3>2.3. DataControlConsumerObject</h3>
<div class="brief">
- This interface provides common attributes for other derived DataControlConsumerObject.
+ This interface provides common attributes and methods for other derived DataControlConsumerObject.
</div>
<pre class="webidl prettyprint"> [NoInterfaceObject] interface DataControlConsumerObject {
readonly attribute <a href="#DataType">DataType</a> type;
readonly attribute DOMString providerId;
readonly attribute DOMString dataId;
+
+ long addChangeListener(<a href="#DataControlChangeCallback">DataControlChangeCallback</a> dataChangeCallback,
+ optional <a href="tizen.html#ErrorCallback">ErrorCallback</a>? errorCallback) raises(<a href="tizen.html#WebAPIException">WebAPIException</a>);
+
+ void removeChangeListener(long watchId) raises(<a href="tizen.html#WebAPIException">WebAPIException</a>);
};</pre>
<p><span class="version">
Since: </span>
</li>
</ul>
</div>
+<div class="methods">
+<h4>Methods</h4>
+<dl>
+<dt class="method" id="DataControlConsumerObject::addChangeListener">
+<a class="backward-compatibility-anchor" name="::DataControl::DataControlConsumerObject::addChangeListener"></a><code><b><span class="methodName">addChangeListener</span></b></code>
+</dt>
+<dd>
+<div class="brief">
+ Adds a listener to receive notifications about provider data changes.
+ </div>
+<div class="synopsis"><pre class="signature prettyprint">long addChangeListener(<a href="#DataControlChangeCallback">DataControlChangeCallback</a> dataChangeCallback, optional <a href="tizen.html#ErrorCallback">ErrorCallback</a>? errorCallback);
+ </pre></div>
+<p><span class="version">
+ Since: </span>
+ 4.0
+ </p>
+<div class="description">
+ <p>
+The <em>ErrorCallback</em> method is launched with these error types:
+ </p>
+ <ul>
+ <li>
+IOError - If a DB operation has failed. </li>
+ </ul>
+ </div>
+<p><span class="privilegelevel">
+ Privilege level: </span>
+ public
+ </p>
+<p><span class="privilege">
+ Privilege: </span>
+ http://tizen.org/privilege/datasharing
+ </p>
+<p><span class="privilege">
+ Privilege: </span>
+ http://tizen.org/privilege/appmanager.launch
+ </p>
+<div class="parameters">
+<p><span class="param">Parameters:</span></p>
+<ul>
+ <li class="param">
+<span class="name">dataChangeCallback</span>:
+ Callback method to be invoked when received data changed notification from provider application.
+ </li>
+ <li class="param">
+<span class="name">errorCallback</span><span class="optional"> [optional]</span><span class="optional"> [nullable]</span>:
+ Callback method to be invoked if provider changes cannot be watched.
+ </li>
+ </ul>
+</div>
+<div class="returntype">
+<p><span class="return">Return value:</span></p>
+ long An identifier used to clear the watch subscription.
+ </div>
+<div class="exceptionlist">
+<p><span class="except">Exceptions:</span></p>
+ <ul class="exception"><li>WebAPIException<ul>
+<li class="list"><p>
+ with error type TypeMismatchError, if any input parameter
+is not compatible with the expected type for that parameter.
+ </p></li>
+<li class="list"><p>
+ with error type SecurityError, if the application does not have the privilege to call this method.
+ </p></li>
+</ul>
+</li></ul>
+ </div>
+<div class="example">
+<span class="example"><p>Code example:</p></span><pre name="code" class="examplecode prettyprint"> 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);
+ }
+ </pre>
+</div>
+<div class="output">
+<span class="title"><p>Output example:</p></span><pre> Change listener has been added with watchId = 1
+ Operation SQL_INSERT was performed
+ Data changed:
+ column WORD value 'tizen1'
+ column WORD_DESC value 'tizen2'
+ </pre>
+</div>
+</dd>
+<dt class="method" id="DataControlConsumerObject::removeChangeListener">
+<a class="backward-compatibility-anchor" name="::DataControl::DataControlConsumerObject::removeChangeListener"></a><code><b><span class="methodName">removeChangeListener</span></b></code>
+</dt>
+<dd>
+<div class="brief">
+ Removes data change listener.
+ </div>
+<div class="synopsis"><pre class="signature prettyprint">void removeChangeListener(long watchId);
+ </pre></div>
+<p><span class="version">
+ Since: </span>
+ 4.0
+ </p>
+<div class="description">
+ <p>
+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.
+ </p>
+ </div>
+<p><span class="privilegelevel">
+ Privilege level: </span>
+ public
+ </p>
+<p><span class="privilege">
+ Privilege: </span>
+ http://tizen.org/privilege/datasharing
+ </p>
+<p><span class="privilege">
+ Privilege: </span>
+ http://tizen.org/privilege/appmanager.launch
+ </p>
+<div class="parameters">
+<p><span class="param">Parameters:</span></p>
+<ul>
+ <li class="param">
+<span class="name">watchId</span>:
+ Subscription identifier.
+ </li>
+ </ul>
+</div>
+<div class="exceptionlist">
+<p><span class="except">Exceptions:</span></p>
+ <ul class="exception"><li>WebAPIException<ul>
+<li class="list"><p>
+ with error type SecurityError, if the application does not have the privilege to call this method.
+ </p></li>
+<li class="list"><p>
+ with error type IOError, if a DB operation has failed.
+ </p></li>
+</ul>
+</li></ul>
+ </div>
+<div class="example">
+<span class="example"><p>Code example:</p></span><pre name="code" class="examplecode prettyprint"> 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);
+ }
+ </pre>
+</div>
+<div class="output">
+<span class="title"><p>Output example:</p></span><pre> Change listener has been added with watchId = 1
+ removeChangeListener was invoked
+ </pre>
+</div>
+</dd>
+</dl>
+</div>
</div>
<div class="interface" id="SQLDataControlConsumer">
<a class="backward-compatibility-anchor" name="::DataControl::SQLDataControlConsumer"></a><h3>2.4. SQLDataControlConsumer</h3>
with error type TypeMismatchError, if the parameter type is not compatible with the expected type for that parameter.
</p></li>
<li class="list"><p>
- 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.
- </p></li>
-<li class="list"><p>
with error type IOError, if a DB operation has failed.
</p></li>
<li class="list"><p>
with error type TypeMismatchError, if the parameter type is not compatible with the expected type for that parameter.
</p></li>
<li class="list"><p>
- 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.
- </p></li>
-<li class="list"><p>
with error type IOError, if a DB operation has failed.
</p></li>
<li class="list"><p>
with error type TypeMismatchError, if the parameter type is not compatible with the expected type for that parameter.
</p></li>
<li class="list"><p>
- 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.
- </p></li>
-<li class="list"><p>
with error type IOError, if a DB operation has failed.
</p></li>
<li class="list"><p>
Since: </span>
2.4
</p>
-<div class="description">
- <p>
-If either of the <em>page</em> or <em>maxNumberPerPage</em> parameters are set to <var>null</var> or are not set, only the first 20 rows are included in the result set.
- </p>
- </div>
<p><span class="privilegelevel">
Privilege level: </span>
public
with error type TypeMismatchError, if the parameter type is not compatible with the expected type for that parameter.
</p></li>
<li class="list"><p>
- 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.
- </p></li>
-<li class="list"><p>
with error type IOError, if a DB operation has failed.
</p></li>
<li class="list"><p>
with error type TypeMismatchError, if the parameter type is not compatible with the expected type for that parameter.
</p></li>
<li class="list"><p>
- with error type InvalidValuesError, if the passed parameter is not available on the data provider side or platform.
- </p></li>
-<li class="list"><p>
with error type IOError, if a DB operation has failed.
</p></li>
<li class="list"><p>
with error type TypeMismatchError, if the parameter type is not compatible with the expected type for that parameter.
</p></li>
<li class="list"><p>
- with error type InvalidValuesError, if the passed parameter is not available on the data provider side or platform.
- </p></li>
-<li class="list"><p>
with error type IOError, if a DB operation has failed.
</p></li>
<li class="list"><p>
with error type TypeMismatchError, if the parameter type is not compatible with the expected type for that parameter.
</p></li>
<li class="list"><p>
- with error type InvalidValuesError, if the passed parameter is not available on the data provider side or platform.
- </p></li>
-<li class="list"><p>
with error type IOError, if a DB operation has failed.
</p></li>
<li class="list"><p>
with error type TypeMismatchError, if the parameter type is not compatible with the expected type for that parameter.
</p></li>
<li class="list"><p>
- with error type InvalidValuesError, if the passed parameter is not available on the data provider side or platform.
- </p></li>
-<li class="list"><p>
with error type IOError, if a DB operation has failed.
</p></li>
<li class="list"><p>
</dl>
</div>
</div>
+<div class="interface" id="DataControlChangeCallback">
+<a class="backward-compatibility-anchor" name="::DataControl::DataControlChangeCallback"></a><h3>2.11. DataControlChangeCallback</h3>
+<div class="brief">
+ This interface provides a DataControlChangeCallback for addChangeListener method.
+ </div>
+<pre class="webidl prettyprint"> [Callback=FunctionOnly, NoInterfaceObject] interface DataControlChangeCallback {
+ void onsuccess(<a href="#EventType">EventType</a> type, <a href="#RowData">RowData</a> data);
+ };</pre>
+<p><span class="version">
+ Since: </span>
+ 4.0
+ </p>
+<div class="methods">
+<h4>Methods</h4>
+<dl>
+<dt class="method" id="DataControlChangeCallback::onsuccess">
+<a class="backward-compatibility-anchor" name="::DataControl::DataControlChangeCallback::onsuccess"></a><code><b><span class="methodName">onsuccess</span></b></code>
+</dt>
+<dd>
+<div class="brief">
+ Called when the data is modified.
+ </div>
+<div class="synopsis"><pre class="signature prettyprint">void onsuccess(<a href="#EventType">EventType</a> type, <a href="#RowData">RowData</a> data);
+ </pre></div>
+<p><span class="version">
+ Since: </span>
+ 4.0
+ </p>
+<div class="parameters">
+<p><span class="param">Parameters:</span></p>
+<ul>
+ <li class="param">
+<span class="name">type</span>:
+ A type of performed operation.
+ </li>
+ <li class="param">
+<span class="name">data</span>:
+ 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 <a href="https://developer.tizen.org/dev-guide/3.0.0/org.tizen.native.mobile.apireference/group__CAPI__DATA__CONTROL__PROVIDER__MODULE.html#ga319b58f16c7a2b007c64f218129e9042">native</a> documentation.
+ </li>
+ </ul>
+</div>
+</dd>
+</dl>
+</div>
+</div>
<div class="dictionary" id="RowData">
-<a class="backward-compatibility-anchor" name="::DataControl::RowData"></a><h3>2.11. RowData</h3>
+<a class="backward-compatibility-anchor" name="::DataControl::RowData"></a><h3>2.12. RowData</h3>
<div class="brief">
The dictionary represents RowData holding 1 row of SQL selection results from another application.
</div>
<pre class="webidl prettyprint">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 <a href="#DataControlManager">DataControlManager</a> datacontrol;
};
readonly attribute <a href="#DataType">DataType</a> type;
readonly attribute DOMString providerId;
readonly attribute DOMString dataId;
+
+ long addChangeListener(<a href="#DataControlChangeCallback">DataControlChangeCallback</a> dataChangeCallback,
+ optional <a href="tizen.html#ErrorCallback">ErrorCallback</a>? errorCallback) raises(<a href="tizen.html#WebAPIException">WebAPIException</a>);
+
+ void removeChangeListener(long watchId) raises(<a href="tizen.html#WebAPIException">WebAPIException</a>);
};
[NoInterfaceObject] interface SQLDataControlConsumer : <a href="#DataControlConsumerObject">DataControlConsumerObject</a> {
void onsuccess(DOMString[] values, unsigned long reqid);
};
+ [Callback=FunctionOnly, NoInterfaceObject] interface DataControlChangeCallback {
+ void onsuccess(<a href="#EventType">EventType</a> type, <a href="#RowData">RowData</a> data);
+ };
+
dictionary RowData {
DOMString[] columns;
</p>
<h2>Table of Contents</h2>
<ul class="toc">
-<li>1. <a href="#typedefs-section">Type Definitions</a><ul class="toc"><li>
+<li>1. <a href="#typedefs-section">Type Definitions</a><ul class="toc">
+<li>
1.1. <a href="#DataType">DataType</a>
-</li></ul>
+</li>
+<li>
+ 1.2. <a href="#EventType">EventType</a>
+</li>
+</ul>
</li>
<li>2. <a href="#interfaces-section">Interfaces</a><ul class="toc">
<li>2.1. <a href="#DataControlManagerObject">DataControlManagerObject</a>
</li>
<li>2.10. <a href="#DataControlGetValueSuccessCallback">DataControlGetValueSuccessCallback</a>
</li>
-<li>2.11. <a href="#RowData">RowData</a>
+<li>2.11. <a href="#DataControlChangeCallback">DataControlChangeCallback</a>
+</li>
+<li>2.12. <a href="#RowData">RowData</a>
</li>
</ul>
</li>
</tr>
<tr>
<td><a href="#DataControlConsumerObject">DataControlConsumerObject</a></td>
-<td></td>
+<td>
+<div>long <a href="#DataControlConsumerObject::addChangeListener">addChangeListener</a> (<a href="#DataControlChangeCallback">DataControlChangeCallback</a> dataChangeCallback, optional <a href="tizen.html#ErrorCallback">ErrorCallback</a>? errorCallback)</div>
+<div>void <a href="#DataControlConsumerObject::removeChangeListener">removeChangeListener</a> (long watchId)</div>
+</td>
</tr>
<tr>
<td><a href="#SQLDataControlConsumer">SQLDataControlConsumer</a></td>
<td><div>void <a href="#DataControlGetValueSuccessCallback::onsuccess">onsuccess</a> (DOMString[] values, unsigned long reqid)</div></td>
</tr>
<tr>
+<td><a href="#DataControlChangeCallback">DataControlChangeCallback</a></td>
+<td><div>void <a href="#DataControlChangeCallback::onsuccess">onsuccess</a> (<a href="#EventType">EventType</a> type, <a href="#RowData">RowData</a> data)</div></td>
+</tr>
+<tr>
<td><a href="#RowData">RowData</a></td>
<td></td>
</tr>
3.0
</p>
</div>
+<div class="enum" id="EventType">
+<a class="backward-compatibility-anchor" name="::DataControl::EventType"></a><h3>1.2. EventType</h3>
+<div class="brief">
+ Specifies the data change event types. The possible values are:
+ </div>
+<pre class="webidl prettyprint"> enum EventType { "SQL_UPDATE", "SQL_INSERT", "SQL_DELETE", "MAP_SET", "MAP_ADD", "MAP_REMOVE"};</pre>
+<p><span class="version">
+ Since: </span>
+ 4.0
+ </p>
+<div class="description">
+ <ul>
+ <li>
+SQL_UPDATE - SQL update event </li>
+ <li>
+SQL_INSERT - SQL insert event </li>
+ <li>
+SQL_DELETE - SQL delete event </li>
+ <li>
+MAP_SET - Map update event </li>
+ <li>
+MAP_ADD - Map add event </li>
+ <li>
+MAP_REMOVE - Map remove event </li>
+ </ul>
+ </div>
+</div>
</div>
<div class="interfaces" id="interfaces-section">
<h2>2. Interfaces</h2>
<div class="interface" id="DataControlConsumerObject">
<a class="backward-compatibility-anchor" name="::DataControl::DataControlConsumerObject"></a><h3>2.3. DataControlConsumerObject</h3>
<div class="brief">
- This interface provides common attributes for other derived DataControlConsumerObject.
+ This interface provides common attributes and methods for other derived DataControlConsumerObject.
</div>
<pre class="webidl prettyprint"> [NoInterfaceObject] interface DataControlConsumerObject {
readonly attribute <a href="#DataType">DataType</a> type;
readonly attribute DOMString providerId;
readonly attribute DOMString dataId;
+
+ long addChangeListener(<a href="#DataControlChangeCallback">DataControlChangeCallback</a> dataChangeCallback,
+ optional <a href="tizen.html#ErrorCallback">ErrorCallback</a>? errorCallback) raises(<a href="tizen.html#WebAPIException">WebAPIException</a>);
+
+ void removeChangeListener(long watchId) raises(<a href="tizen.html#WebAPIException">WebAPIException</a>);
};</pre>
<p><span class="version">
Since: </span>
</li>
</ul>
</div>
+<div class="methods">
+<h4>Methods</h4>
+<dl>
+<dt class="method" id="DataControlConsumerObject::addChangeListener">
+<a class="backward-compatibility-anchor" name="::DataControl::DataControlConsumerObject::addChangeListener"></a><code><b><span class="methodName">addChangeListener</span></b></code>
+</dt>
+<dd>
+<div class="brief">
+ Adds a listener to receive notifications about provider data changes.
+ </div>
+<div class="synopsis"><pre class="signature prettyprint">long addChangeListener(<a href="#DataControlChangeCallback">DataControlChangeCallback</a> dataChangeCallback, optional <a href="tizen.html#ErrorCallback">ErrorCallback</a>? errorCallback);
+ </pre></div>
+<p><span class="version">
+ Since: </span>
+ 4.0
+ </p>
+<div class="description">
+ <p>
+The <em>ErrorCallback</em> method is launched with these error types:
+ </p>
+ <ul>
+ <li>
+IOError - If a DB operation has failed. </li>
+ </ul>
+ </div>
+<p><span class="privilegelevel">
+ Privilege level: </span>
+ public
+ </p>
+<p><span class="privilege">
+ Privilege: </span>
+ http://tizen.org/privilege/datasharing
+ </p>
+<p><span class="privilege">
+ Privilege: </span>
+ http://tizen.org/privilege/appmanager.launch
+ </p>
+<div class="parameters">
+<p><span class="param">Parameters:</span></p>
+<ul>
+ <li class="param">
+<span class="name">dataChangeCallback</span>:
+ Callback method to be invoked when received data changed notification from provider application.
+ </li>
+ <li class="param">
+<span class="name">errorCallback</span><span class="optional"> [optional]</span><span class="optional"> [nullable]</span>:
+ Callback method to be invoked if provider changes cannot be watched.
+ </li>
+ </ul>
+</div>
+<div class="returntype">
+<p><span class="return">Return value:</span></p>
+ long An identifier used to clear the watch subscription.
+ </div>
+<div class="exceptionlist">
+<p><span class="except">Exceptions:</span></p>
+ <ul class="exception"><li>WebAPIException<ul>
+<li class="list"><p>
+ with error type TypeMismatchError, if any input parameter
+is not compatible with the expected type for that parameter.
+ </p></li>
+<li class="list"><p>
+ with error type SecurityError, if the application does not have the privilege to call this method.
+ </p></li>
+</ul>
+</li></ul>
+ </div>
+<div class="example">
+<span class="example"><p>Code example:</p></span><pre name="code" class="examplecode prettyprint"> 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);
+ }
+ </pre>
+</div>
+<div class="output">
+<span class="title"><p>Output example:</p></span><pre> Change listener has been added with watchId = 1
+ Operation SQL_INSERT was performed
+ Data changed:
+ column WORD value 'tizen1'
+ column WORD_DESC value 'tizen2'
+ </pre>
+</div>
+</dd>
+<dt class="method" id="DataControlConsumerObject::removeChangeListener">
+<a class="backward-compatibility-anchor" name="::DataControl::DataControlConsumerObject::removeChangeListener"></a><code><b><span class="methodName">removeChangeListener</span></b></code>
+</dt>
+<dd>
+<div class="brief">
+ Removes data change listener.
+ </div>
+<div class="synopsis"><pre class="signature prettyprint">void removeChangeListener(long watchId);
+ </pre></div>
+<p><span class="version">
+ Since: </span>
+ 4.0
+ </p>
+<div class="description">
+ <p>
+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.
+ </p>
+ </div>
+<p><span class="privilegelevel">
+ Privilege level: </span>
+ public
+ </p>
+<p><span class="privilege">
+ Privilege: </span>
+ http://tizen.org/privilege/datasharing
+ </p>
+<p><span class="privilege">
+ Privilege: </span>
+ http://tizen.org/privilege/appmanager.launch
+ </p>
+<div class="parameters">
+<p><span class="param">Parameters:</span></p>
+<ul>
+ <li class="param">
+<span class="name">watchId</span>:
+ Subscription identifier.
+ </li>
+ </ul>
+</div>
+<div class="exceptionlist">
+<p><span class="except">Exceptions:</span></p>
+ <ul class="exception"><li>WebAPIException<ul>
+<li class="list"><p>
+ with error type SecurityError, if the application does not have the privilege to call this method.
+ </p></li>
+<li class="list"><p>
+ with error type IOError, if a DB operation has failed.
+ </p></li>
+</ul>
+</li></ul>
+ </div>
+<div class="example">
+<span class="example"><p>Code example:</p></span><pre name="code" class="examplecode prettyprint"> 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);
+ }
+ </pre>
+</div>
+<div class="output">
+<span class="title"><p>Output example:</p></span><pre> Change listener has been added with watchId = 1
+ removeChangeListener was invoked
+ </pre>
+</div>
+</dd>
+</dl>
+</div>
</div>
<div class="interface" id="SQLDataControlConsumer">
<a class="backward-compatibility-anchor" name="::DataControl::SQLDataControlConsumer"></a><h3>2.4. SQLDataControlConsumer</h3>
Privilege: </span>
http://tizen.org/privilege/datacontrol.consumer
</p>
+<p><span class="remark"> Remark : </span>
+ <em>order</em> is supported since Tizen 3.0
+ </p>
<div class="parameters">
<p><span class="param">Parameters:</span></p>
<ul>
</dl>
</div>
</div>
+<div class="interface" id="DataControlChangeCallback">
+<a class="backward-compatibility-anchor" name="::DataControl::DataControlChangeCallback"></a><h3>2.11. DataControlChangeCallback</h3>
+<div class="brief">
+ This interface provides a DataControlChangeCallback for addChangeListener method.
+ </div>
+<pre class="webidl prettyprint"> [Callback=FunctionOnly, NoInterfaceObject] interface DataControlChangeCallback {
+ void onsuccess(<a href="#EventType">EventType</a> type, <a href="#RowData">RowData</a> data);
+ };</pre>
+<p><span class="version">
+ Since: </span>
+ 4.0
+ </p>
+<div class="methods">
+<h4>Methods</h4>
+<dl>
+<dt class="method" id="DataControlChangeCallback::onsuccess">
+<a class="backward-compatibility-anchor" name="::DataControl::DataControlChangeCallback::onsuccess"></a><code><b><span class="methodName">onsuccess</span></b></code>
+</dt>
+<dd>
+<div class="brief">
+ Called when the data is modified.
+ </div>
+<div class="synopsis"><pre class="signature prettyprint">void onsuccess(<a href="#EventType">EventType</a> type, <a href="#RowData">RowData</a> data);
+ </pre></div>
+<p><span class="version">
+ Since: </span>
+ 4.0
+ </p>
+<div class="parameters">
+<p><span class="param">Parameters:</span></p>
+<ul>
+ <li class="param">
+<span class="name">type</span>:
+ A type of performed operation.
+ </li>
+ <li class="param">
+<span class="name">data</span>:
+ 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 <a href="https://developer.tizen.org/dev-guide/3.0.0/org.tizen.native.mobile.apireference/group__CAPI__DATA__CONTROL__PROVIDER__MODULE.html#ga319b58f16c7a2b007c64f218129e9042">native</a> documentation.
+ </li>
+ </ul>
+</div>
+</dd>
+</dl>
+</div>
+</div>
<div class="dictionary" id="RowData">
-<a class="backward-compatibility-anchor" name="::DataControl::RowData"></a><h3>2.11. RowData</h3>
+<a class="backward-compatibility-anchor" name="::DataControl::RowData"></a><h3>2.12. RowData</h3>
<div class="brief">
The dictionary represents RowData holding 1 row of SQL selection results from another application.
</div>
<pre class="webidl prettyprint">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 <a href="#DataControlManager">DataControlManager</a> datacontrol;
};
readonly attribute <a href="#DataType">DataType</a> type;
readonly attribute DOMString providerId;
readonly attribute DOMString dataId;
+
+ long addChangeListener(<a href="#DataControlChangeCallback">DataControlChangeCallback</a> dataChangeCallback,
+ optional <a href="tizen.html#ErrorCallback">ErrorCallback</a>? errorCallback) raises(<a href="tizen.html#WebAPIException">WebAPIException</a>);
+
+ void removeChangeListener(long watchId) raises(<a href="tizen.html#WebAPIException">WebAPIException</a>);
};
[NoInterfaceObject] interface SQLDataControlConsumer : <a href="#DataControlConsumerObject">DataControlConsumerObject</a> {
};
[Callback=FunctionOnly, NoInterfaceObject] interface DataControlInsertSuccessCallback {
- void onsuccess(unsigned long reqId, long insertRowId);
+ void onsuccess(unsigned long reqId, long insertRowId);
};
void onsuccess(DOMString[] values, unsigned long reqid);
};
+ [Callback=FunctionOnly, NoInterfaceObject] interface DataControlChangeCallback {
+ void onsuccess(<a href="#EventType">EventType</a> type, <a href="#RowData">RowData</a> data);
+ };
+
dictionary RowData {
DOMString[] columns;
projects / sdk / online-doc.git / commitdiff