The DataControl functionality provides a way to access specific data that is exported by other applications.
Please read the Data Control Guide to know how to share own application data with other applications.
Since: 2.4
enum DataType { "MAP", "SQL"};
enum EventType { "SQL_UPDATE", "SQL_INSERT", "SQL_DELETE", "MAP_SET", "MAP_ADD", "MAP_REMOVE"};
Since: 4.0
[NoInterfaceObject] interface DataControlManagerObject { readonly attribute DataControlManager datacontrol; };
Tizen implements DataControlManagerObject;
The tizen.datacontrol object allows access to the DataControl API.
[NoInterfaceObject] interface DataControlManager { DataControlConsumerObject getDataControlConsumer(DOMString providerId, DOMString dataId, DataType type) raises(WebAPIException); };
getDataControlConsumer
DataControlConsumerObject getDataControlConsumer(DOMString providerId, DOMString dataId, DataType type);
Privilege level: public
Privilege: http://tizen.org/privilege/datacontrol.consumer
Parameters:
Return value:
Exceptions:
with error type TypeMismatchError, if the parameter type 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.
with error type UnknownError, if any other error occurs.
Code example:
//The data provider, a native application, should be pre-installed and launched. //The same provider ID should be defined for the use of this API between a native application(provider) and a web application(consumer). //In this example, the DictionaryDataControlProvider native sample application is used as a data control provider. //Gets SQL type DataControlConsumerObject try { var globalSQLConsumer = tizen.datacontrol.getDataControlConsumer( "http://tizen.org/datacontrol/provider/DictionaryDataControlProvider", "Dictionary", "SQL"); } catch (err) { console.log (err.name +": " + err.message); } // Gets MAP type DataControlConsumerObject try { globalMappedConsumer = tizen.datacontrol.getDataControlConsumer( "http://tizen.org/datacontrol/provider/DictionaryDataControlProvider", "Dictionary", "MAP"); } catch (err) { console.log (err.name +": " + err.message); }
[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); };
addChangeListener
long addChangeListener(DataControlChangeCallback dataChangeCallback, optional ErrorCallback? errorCallback);
The ErrorCallback method is launched with these error types:
Privilege: http://tizen.org/privilege/datasharing
Privilege: http://tizen.org/privilege/appmanager.launch
Remark : 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.
with error type TypeMismatchError, if any input parameter is not compatible with the expected type for that parameter.
with error type ServiceNotAvailableError, if the application could not connect with the provider.
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
void removeChangeListener(long watchId);
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.
with error type IOError, if a DB operation has failed.
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); }
Change listener has been added with watchId = 1 removeChangeListener was invoked
[NoInterfaceObject] interface SQLDataControlConsumer : DataControlConsumerObject { void insert(unsigned long reqId, RowData insertionData, optional DataControlInsertSuccessCallback? successCallback, optional DataControlErrorCallback? errorCallback) raises(WebAPIException); void update(unsigned long reqId, RowData updateData, DOMString where, optional DataControlSuccessCallback? successCallback, optional DataControlErrorCallback? errorCallback) raises(WebAPIException); void remove(unsigned long reqId, DOMString where, optional DataControlSuccessCallback? successCallback, optional DataControlErrorCallback? errorCallback) raises(WebAPIException); 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) raises(WebAPIException); };
insert
void insert(unsigned long reqId, RowData insertionData, optional DataControlInsertSuccessCallback? successCallback, optional DataControlErrorCallback? errorCallback);
function successcb(id, insertRowId) { console.log("ok : reqid " + id); } function errorcb(id, error) { console.log("error id : " + id + ", error msg : " + error.message); } try { var rowData = { columns : ["WORD", "WORD_DESC"] , values : ["'tizen1'", "'tizen2'"] }; // Defines globalReqId before // Increases globalReqId for uniqueness globalReqId++; globalSQLConsumer.insert(globalReqId, rowData, successcb, errorcb); } catch (err) { console.log (err.name +": " + err.message); }
update
void update(unsigned long reqId, RowData updateData, DOMString where, optional DataControlSuccessCallback? successCallback, optional DataControlErrorCallback? errorCallback);
function successcb(id) { console.log("ok : reqid " + id); } function errorcb(id, error) { console.log("error id : " + id + ", error msg : " + error.message); } try { var rowData = { columns : ["WORD", "WORD_DESC"] , values : ["'tizen1'", "'Web apps platform!'"] }; // Defines globalReqId before // Increases globalReqId for uniqueness globalReqId++; globalSQLConsumer.update(globalReqId, rowData, "WORD='tizen1'", successcb, errorcb); } catch (err) { console.log (err.name +": " + err.message); }
remove
void remove(unsigned long reqId, DOMString where, optional DataControlSuccessCallback? successCallback, optional DataControlErrorCallback? errorCallback);
function successcb(id) { console.log("ok : reqid " + id); } function errorcb(id, error) { console.log("error id : " + id + ", error msg : " + error.message); } try { // Defines globalReqId before // Increases globalReqId for uniqueness globalReqId++; globalSQLConsumer.remove(globalReqId, "WORD='tizen1'", successcb, errorcb); } catch (err) { console.log (err.name +": " + err.message); }
select
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);
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.
Remark : order is supported since Tizen 3.0
function getValueSuccessCB(result, id) { console.log("getValueSuccessCB result.length: " + result.length); var length = result.length; for (var i = 0; i < length; i++) { var rowData = "| "; var j = 0; for (j = 0; j < result[i].columns.length; j++) { rowData += "column: " + result[i].columns[j] + ", value: " + result[i].values[j] + " | "; } console.log(rowData); } } function errorcb(id, error) { console.log("error id : " + id + ", error msg : " + error.message); } 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 -----"); globalSQLConsumer.select(globalReqId, columns, whereClause, getValueSuccessCB, errorcb, null, null, "WORD_DESC ASC"); setTimeout( function() { console.log("----- Calling descending order -----"); globalSQLConsumer.select(globalReqId, columns, whereClause, getValueSuccessCB, errorcb, null, null, "WORD_DESC DESC"); }, 1000); } catch (err) { console.log (err.name +": " + err.message); }
[NoInterfaceObject] interface MappedDataControlConsumer : DataControlConsumerObject { void addValue(unsigned long reqId, DOMString key, DOMString value, optional DataControlSuccessCallback? successCallback, optional DataControlErrorCallback? errorCallback) raises(WebAPIException); void removeValue(unsigned long reqId, DOMString key, DOMString value, DataControlSuccessCallback successCallback, optional DataControlErrorCallback? errorCallback) raises(WebAPIException); void getValue(unsigned long reqId, DOMString key, DataControlGetValueSuccessCallback successCallback, optional DataControlErrorCallback? errorCallback) raises(WebAPIException); void updateValue(unsigned long reqId, DOMString key, DOMString oldValue, DOMString newValue, DataControlSuccessCallback successCallback, optional DataControlErrorCallback? errorCallback) raises(WebAPIException); };
addValue
void addValue(unsigned long reqId, DOMString key, DOMString value, optional DataControlSuccessCallback? successCallback, optional DataControlErrorCallback? errorCallback);
function successcb(id) { console.log("ok : reqid " + id); } function errorcb(id, error) { console.log("error id : " + id + ", error msg : " + error.message); } try { // Defines globalReqId before // Increases globalReqId for uniqueness globalReqId++; globalMappedConsumer.addValue(globalReqId, "tizen", "Foo", successcb, errorcb); } catch (err) { console.log (err.name +": " + err.message); }
removeValue
void removeValue(unsigned long reqId, DOMString key, DOMString value, DataControlSuccessCallback successCallback, optional DataControlErrorCallback? errorCallback);
with error type NotFoundError, if the key cannot be found.
function successcb(id) { console.log("ok : reqid " + id); } function errorcb(id, error) { console.log("error id : " + id + ", error msg : " + error.message); } try { // Defines globalReqId before // Increases globalReqId for uniqueness globalReqId++; globalMappedConsumer.removeValue(globalReqId, "tizen", "Foo", successcb, errorcb); } catch (err) { console.log (err.name +": " + err.message); }
getValue
void getValue(unsigned long reqId, DOMString key, DataControlGetValueSuccessCallback successCallback, optional DataControlErrorCallback? errorCallback);
function getValueSuccessCB(result, id) { console.log(result.length + ":" + result[0]); } function errorcb(id, error) { console.log("error id : " + id + ", error msg : " + error.message); } try { // Defines globalReqId before // Increases globalReqId for uniqueness globalReqId++; globalMappedConsumer.getValue(globalReqId, "tizen", getValueSuccessCB, errorcb); } catch (err) { console.log (err.name +": " + err.message); }
updateValue
void updateValue(unsigned long reqId, DOMString key, DOMString oldValue, DOMString newValue, DataControlSuccessCallback successCallback, optional DataControlErrorCallback? errorCallback);
function successcb(id) { console.log("ok : reqid " + id); } function errorcb(id, error) { console.log("error id : " + id + ", error msg : " + error.message); } try { // Defines globalReqId before // Increases globalReqId for uniqueness globalReqId++; globalMappedConsumer.updateValue(globalReqId, "tizen", "Foo", "Bar", successcb, errorcb); } catch (err) { console.log (err.name +": " + err.message); }
[Callback=FunctionOnly, NoInterfaceObject] interface DataControlSuccessCallback { void onsuccess(unsigned long reqId); };
onsuccess
void onsuccess(unsigned long reqId);
[Callback=FunctionOnly, NoInterfaceObject] interface DataControlErrorCallback { void onerror(unsigned long reqId, WebAPIError error); };
onerror
void onerror(unsigned long reqId, WebAPIError error);
[Callback=FunctionOnly, NoInterfaceObject] interface DataControlInsertSuccessCallback { void onsuccess(unsigned long reqId, long insertRowId); };
void onsuccess(unsigned long reqId, long insertRowId);
[Callback=FunctionOnly, NoInterfaceObject] interface DataControlSelectSuccessCallback { void onsuccess(RowData[] rows, unsigned long reqId); };
void onsuccess(RowData[] rows, unsigned long reqId);
[Callback=FunctionOnly, NoInterfaceObject] interface DataControlGetValueSuccessCallback { void onsuccess(DOMString[] values, unsigned long reqid); };
void onsuccess(DOMString[] values, unsigned long reqid);
[Callback=FunctionOnly, NoInterfaceObject] interface DataControlChangeCallback { void onsuccess(EventType type, RowData data); };
void onsuccess(EventType type, RowData data);
dictionary RowData { DOMString[] columns; DOMString[] values; };
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; }; Tizen implements DataControlManagerObject; [NoInterfaceObject] interface DataControlManager { DataControlConsumerObject getDataControlConsumer(DOMString providerId, DOMString dataId, DataType type) raises(WebAPIException); }; [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); }; [NoInterfaceObject] interface SQLDataControlConsumer : DataControlConsumerObject { void insert(unsigned long reqId, RowData insertionData, optional DataControlInsertSuccessCallback? successCallback, optional DataControlErrorCallback? errorCallback) raises(WebAPIException); void update(unsigned long reqId, RowData updateData, DOMString where, optional DataControlSuccessCallback? successCallback, optional DataControlErrorCallback? errorCallback) raises(WebAPIException); void remove(unsigned long reqId, DOMString where, optional DataControlSuccessCallback? successCallback, optional DataControlErrorCallback? errorCallback) raises(WebAPIException); 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) raises(WebAPIException); }; [NoInterfaceObject] interface MappedDataControlConsumer : DataControlConsumerObject { void addValue(unsigned long reqId, DOMString key, DOMString value, optional DataControlSuccessCallback? successCallback, optional DataControlErrorCallback? errorCallback) raises(WebAPIException); void removeValue(unsigned long reqId, DOMString key, DOMString value, DataControlSuccessCallback successCallback, optional DataControlErrorCallback? errorCallback) raises(WebAPIException); void getValue(unsigned long reqId, DOMString key, DataControlGetValueSuccessCallback successCallback, optional DataControlErrorCallback? errorCallback) raises(WebAPIException); void updateValue(unsigned long reqId, DOMString key, DOMString oldValue, DOMString newValue, DataControlSuccessCallback successCallback, optional DataControlErrorCallback? errorCallback) raises(WebAPIException); }; [Callback=FunctionOnly, NoInterfaceObject] interface DataControlSuccessCallback { void onsuccess(unsigned long reqId); }; [Callback=FunctionOnly, NoInterfaceObject] interface DataControlErrorCallback { void onerror(unsigned long reqId, WebAPIError error); }; [Callback=FunctionOnly, NoInterfaceObject] interface DataControlInsertSuccessCallback { void onsuccess(unsigned long reqId, long insertRowId); }; [Callback=FunctionOnly, NoInterfaceObject] interface DataControlSelectSuccessCallback { void onsuccess(RowData[] rows, unsigned long reqId); }; [Callback=FunctionOnly, NoInterfaceObject] interface DataControlGetValueSuccessCallback { void onsuccess(DOMString[] values, unsigned long reqid); }; [Callback=FunctionOnly, NoInterfaceObject] interface DataControlChangeCallback { void onsuccess(EventType type, RowData data); }; dictionary RowData { DOMString[] columns; DOMString[] values; }; };