//
-// Open Service Platform
// Copyright (c) 2012 Samsung Electronics Co., Ltd.
//
// Licensed under the Apache License, Version 2.0 (the License);
/**
* @class SqlDataControl
- * @brief This class represents the SQL-type data control behavior.
+ * @brief This class represents the SQL-friendly interface based data control's behavior.
*
* @since 2.0
*
* @final This class is not intended for extension.
*
- * The %SqlDataControl class represents the data control behavior, that provides a standard mechanism
- * for accessing specific data exported by other applications.
- * Data control provider can share its own data to data control consumers.
+ * The %SqlDataControl class represents the data control's behavior that provides a standard mechanism
+ * for accessing the specific data exported by other applications.
+ * A data control provider can share its data with data control consumers.
*
* For more information on the class features, see <a href="../org.tizen.native.appprogramming/html/guide/app/data_controls.htm">Data Controls</a>.
*
* @see Tizen::App::AppManager
+ *
+ * @code
+ *
+ * #include <FBase.h>
+ * #include <FIo.h>
+ *
+ * using namespace Tizen::Base;
+ * using namespace Tizen::Io;
+ *
+ * class MySqlDataControlResponseListener:
+ * : public Tizen::App::ISqlDataControlResponseListener
+ * {
+ * public:
+ * void OnSqlDataControlInsertResponseReceived(RequestId reqId, const String& providerId, const String& dataId, long long insertRowId, bool providerResult, const String* pErrorMsg)
+ * {
+ * AppLog("Row Id = %d", insertRowId);
+ * }
+ * };
+ *
+ * void
+ * MyClass::Execute(void)
+ * {
+ * String providerId(L"http://tizen.org/datacontrol/provider/example");
+ * SqlDataControl* pDc = AppManager::GetSqlDataControlN(providerId);
+ *
+ * MySqlDataControlResponseListener* pResponseListener = new MySqlDataControlResponseListener();
+ *
+ * pDc->SetSqlDataControlResponseListener(pResponseListener);
+ *
+ * String dataId(L"test");
+ * String person(L"person");
+ * String number(L"number");
+ * RequestId reqId;
+ *
+ * ArrayList columnList(SingleObjectDeleter);
+ * columnList.Construct();
+ *
+ * columnList.Add(person);
+ * columnList.Add(number);
+ *
+ * String where(L"group = 'friend'");
+ * String order(L"person ASC");
+ *
+ * pDc->Select(dataId, &columnList, &where, &order, reqId);
+ * }
+ *
+ * @endcode
+
*/
class _OSP_EXPORT_ SqlDataControl
/**
* Selects the specified columns to be queried. @n
- * The result set of the specified columns is retrieved from a table owned by an SQL-type data control provider. @n
+ * The result set of the specified columns is retrieved from a table owned by the SQL-friendly interface based data control provider. @n
* The %Select() method is asynchronous.
- * For receiving the response from the data control provider, set the listener with
- * SqlDataControl::SetSqlDataControlResponseListener(). @n
+ * For receiving the response from the data control provider, set the listener using
+ * the SqlDataControl::SetSqlDataControlResponseListener() method. @n
* When the requested result set has been received from the data control provider,
* the ISqlDataControlResponseListener::OnSqlDataControlSelectResponseReceived() method is called.
*
* @since 2.0
+ * @privlevel public
+ * @privilege %http://tizen.org/privilege/datacontrol.consumer
*
* @return An error code
- * @param[in] dataId A string for identifying specific data, usually a database table to query from @n
+ * @param[in] dataId The string that identifies the specific data, usually a database table to query from @n
* The string consists of one or more components, separated by a slash('/').
- * @param[in] pColumnList A list of column names to query @n
+ * @param[in] pColumnList The list of column names to query @n
* The type of objects contained in the specified @c pColumnList must be
- * Tizen::Base::String class.
- * If the specified @c pColumnList is @c null, all columns are selected.
- * @param[in] pWhere A filter to select desired rows to query @n
+ * Tizen::Base::String @n
+ * If the specified @c pColumnList is @c null, all the columns are selected.
+ * @param[in] pWhere The filter to select the desired rows to query @n
* It is an SQL 'WHERE' clause excluding the 'WHERE' itself such as
- * column1 = 'stringValue' AND column2 = numericValue.
- * @param[in] pOrder The sorting order of rows to query @n
+ * column1 = 'stringValue' AND column2 = numericValue @n
+ * If the value is a string, the value must be wrapped in single quotes,
+ * otherwise it need not be wrapped in single quotes @n
+ * For more information on the SQL statement, see SQLite SQL documents.
+ * @param[in] pOrder The sorting order of the rows to query @n
* It is an SQL 'ORDER BY' clause excluding the 'ORDER BY' itself.
* @param[out] reqId The request ID
- * @param[in] pageNo The page number of the result set @n It starts from @c 1.
- * @param[in] countPerPage The desired maximum count of rows on a page
+ * @param[in] pageNo The page number of the result set @n
+ * It starts from @c 1.
+ * @param[in] countPerPage The desired maximum count of the rows per page
* @exception E_SUCCESS The method is successful.
- * @exception E_INVALID_STATE This instance has not been properly constructed.
- * @exception E_INVALID_ARG Either of the following conditions has occurred: @n
+ * @exception E_INVALID_STATE This instance has not been constructed properly.
+ * @exception E_INVALID_ARG Either of the following conditions has occurred:
* - The specified @c pColumnList is empty.
- * - The specified @c pageNo parameter is less than @c 1.
- * - The specified @c countPerPage parameter is less than @c 1.
- * @exception E_ILLEGAL_ACCESS Either of the following conditions has occurred: @n
- * - Access is denied due to insufficient permission.
- * - The application using this method is not signed with the same certificate of provider application. @b Since: @b 2.1
- * @exception E_MAX_EXCEEDED Either of the following conditions has occurred: @n
- * - The size of sending buffer has exceeded the maximum limit.
- * - The number of sending requests has exceeded the maximum limit.
+ * - The specified @c pageNo is less than @c 1.
+ * - The specified @c countPerPage is less than @c 1.
+ * @exception E_ILLEGAL_ACCESS Either of the following conditions has occurred:
+ * - The access is denied due to insufficient permission.
+ * - The application using this method is not signed with the same certificate as that of the provider application. @b Since: @b 2.1
+ * @exception E_MAX_EXCEEDED Either of the following conditions has occurred:
+ * - The size of the sending buffer has exceeded the maximum limit.
+ * - The number of sending requests have exceeded the maximum limit.
+ * @exception E_PRIVILEGE_DENIED The application does not have the privilege to call this method.
* @exception E_SYSTEM A system error has occurred.
- * @remarks If the value specified in the @c pWhere is string, the value must be wrapped in
- * single quotes. Otherwise it is not needed to wrap the numeric value in single quotes.
- * For more information on the SQL statement, see SQLite SQL documents.
- * @remarks The recommended data size is under 16KB because severe system performance degradation may occur for large messages. E_MAX_EXCEEDED may be returned for messages over 16KB size.
+ * @remarks The recommended data size is under 16KB because a severe system performance degradation may occur for larger messages. @n
+ * @c E_MAX_EXCEEDED may be returned for messages over 16KB.
*/
result Select(const Tizen::Base::String& dataId, const Tizen::Base::Collection::IList* pColumnList,
const Tizen::Base::String* pWhere, const Tizen::Base::String *pOrder, RequestId& reqId,
int pageNo = 1, int countPerPage = 20);
/**
- * Inserts new rows into a table owned by an SQL-type data control provider. @n
+ * Inserts new rows into a table owned by the SQL-friendly interface based data control provider. @n
* The %Insert() method is asynchronous.
- * For receiving the response from the data control provider, set the listener with
- * SqlDataControl::SetSqlDataControlResponseListener(). @n
+ * For receiving the response from the data control provider, set the listener using
+ * the SqlDataControl::SetSqlDataControlResponseListener() method. @n
* When the response has been received from the data control provider,
* the ISqlDataControlResponseListener::OnSqlDataControlInsertResponseReceived() method is called.
*
* @since 2.0
+ * @privlevel public
+ * @privilege %http://tizen.org/privilege/datacontrol.consumer
*
* @return An error code
- * @param[in] dataId A string for identifying specific data, usually a database table to insert into @n
+ * @param[in] dataId The string that identifies the specific data, usually a database table to insert into @n
* The string consists of one or more components, separated by a slash('/').
* @param[in] insertMap The column-value pairs to insert @n
- * The type of objects contained in the specified @c insertMap must be
- * Tizen::Base::String class.
+ * The type of objects must be Tizen::Base::String @n
+ * If the value is a string, the value must be wrapped in single quotes,
+ * else it need not be wrapped in single quotes @n
+ * For more information on the SQL statement, see SQLite SQL documents.
* @param[out] reqId The request ID
* @exception E_SUCCESS The method is successful.
- * @exception E_INVALID_STATE This instance has not been properly constructed.
+ * @exception E_INVALID_STATE This instance has not been constructed properly.
* @exception E_INVALID_ARG The specified @c insertMap is empty.
- * @exception E_ILLEGAL_ACCESS Either of the following conditions has occurred: @n
- * - Access is denied due to insufficient permission.
- * - The application using this method is not signed with the same certificate of provider application. @b Since: @b 2.1
- * @exception E_MAX_EXCEEDED Either of the following conditions has occurred: @n
- * - The size of sending buffer has exceeded the maximum limit.
- * - The number of sending requests has exceeded the maximum limit.
+ * @exception E_ILLEGAL_ACCESS Either of the following conditions has occurred:
+ * - The access is denied due to insufficient permission.
+ * - The application using this method is not signed with the same certificate as that of the provider application. @b Since: @b 2.1
+ * @exception E_MAX_EXCEEDED Either of the following conditions has occurred:
+ * - The size of the sending buffer has exceeded the maximum limit.
+ * - The number of sending requests have exceeded the maximum limit.
+ * @exception E_PRIVILEGE_DENIED The application does not have the privilege to call this method.
* @exception E_SYSTEM A system error has occurred.
- * @remarks If the value specified in the @c insertMap is string, the value must be wrapped in
- * single quotes. Otherwise it is not needed to wrap the numeric value in single quotes.
- * For more information on the SQL statement, see SQLite SQL documents.
- * @remarks The recommended data size is under 16KB because severe system performance degradation may occur for large messages. E_MAX_EXCEEDED may be returned for messages over 16KB size.
+ * @remarks The recommended data size is under 1MB because a severe system performance degradation may occur for larger messages. @n
+ * @c E_MAX_EXCEEDED may be returned for messages over 1MB.
*/
result Insert(const Tizen::Base::String& dataId, const Tizen::Base::Collection::IMap& insertMap, RequestId& reqId);
/**
- * Updates values of a table owned by an SQL-type data control provider. @n
+ * Updates values of a table owned by the SQL-friendly interface based data control provider. @n
* The %Update() method is asynchronous.
- * For receiving the response from the data control provider, set the listener with
- * SqlDataControl::SetSqlDataControlResponseListener(). @n
+ * For receiving the response from the data control provider, set the listener using
+ * the SqlDataControl::SetSqlDataControlResponseListener() method. @n
* When the response has been received from the data control provider,
* the ISqlDataControlResponseListener::OnSqlDataControlUpdateResponseReceived() method is called.
*
* @since 2.0
+ * @privlevel public
+ * @privilege %http://tizen.org/privilege/datacontrol.consumer
*
* @return An error code
- * @param[in] dataId A string for identifying specific data, usually a database table to update @n
+ * @param[in] dataId The string that identifies the specific data, usually a database table to update @n
* The string consists of one or more components, separated by a slash('/').
* @param[in] updateMap The column-value pairs to update @n
- * The type of objects contained in the specified @c updateMap must be
- * Tizen::Base::String class. @n
- * @param[in] pWhere A filter to select desired rows to update @n
+ * The type of objects must be Tizen::Base::String @n
+ * If the value is a string, the value must be wrapped in single quotes,
+ * else it need not be wrapped in single quotes @n
+ * For more information on the SQL statement, see SQLITE SQL documents.
+ * @param[in] pWhere The filter to select the desired rows to update @n
* It is an SQL 'WHERE' clause excluding the 'WHERE' itself such as
- * column1 = 'stringValue' AND column2 = numericValue.
+ * column1 = 'stringValue' AND column2 = numericValue @n
+ * If the value is a string, the value must be wrapped in single quotes,
+ * else it is not wrapped in single quotes @n
+ * For more information on the SQL statement, see SQLITE SQL documents.
* @param[out] reqId The request ID
* @exception E_SUCCESS The method is successful.
- * @exception E_INVALID_STATE This instance has not been properly constructed.
+ * @exception E_INVALID_STATE This instance has not been constructed properly.
* @exception E_INVALID_ARG The specified @c updateMap is empty.
- * @exception E_ILLEGAL_ACCESS Either of the following conditions has occurred: @n
- * - Access is denied due to insufficient permission.
- * - The application using this method is not signed with the same certificate of provider application. @b Since: @b 2.1
- * @exception E_MAX_EXCEEDED Either of the following conditions has occurred: @n
- * - The size of sending buffer has exceeded the maximum limit.
- * - The number of sending requests has exceeded the maximum limit.
+ * @exception E_ILLEGAL_ACCESS Either of the following conditions has occurred:
+ * - The access is denied due to insufficient permission.
+ * - The application using this method is not signed with the same certificate as that of the provider application. @b Since: @b 2.1
+ * @exception E_MAX_EXCEEDED Either of the following conditions has occurred:
+ * - The size of the sending buffer has exceeded the maximum limit.
+ * - The number of sending requests have exceeded the maximum limit.
+ * @exception E_PRIVILEGE_DENIED The application does not have the privilege to call this method.
* @exception E_SYSTEM A system error has occurred.
- * @remarks If the value specified in the @c pWhere or @c updateMap is string, the value must be wrapped in
- * single quotes. Otherwise it is not needed to wrap the numeric value in single quotes.
- * For more information on the SQL statement, see SQLITE SQL documents.
- * @remarks The recommended data size is under 16KB because severe system performance degradation may occur for large messages. E_MAX_EXCEEDED may be returned for messages over 16KB size.
+ * @remarks The recommended data size is under 1MB because a severe system performance degradation may occur for larger messages. @n
+ * @c E_MAX_EXCEEDED may be returned for messages over 1MB.
*/
result Update(const Tizen::Base::String& dataId, const Tizen::Base::Collection::IMap& updateMap,
const Tizen::Base::String* pWhere, RequestId& reqId);
/**
- * Deletes rows of a table owned by an SQL-type data control provider. @n
+ * Deletes rows of a table owned by the SQL-friendly interface based data control provider. @n
* The %Delete() method is asynchronous.
- * For receiving the response from the data control provider, set the listener with
- * SqlDataControl::SetSqlDataControlResponseListener(). @n
+ * For receiving the response from the data control provider, set the listener using
+ * the SqlDataControl::SetSqlDataControlResponseListener() method. @n
* When the response has been received from the data control provider,
* the ISqlDataControlResponseListener::OnSqlDataControlDeleteResponseReceived() method is called.
*
* @since 2.0
+ * @privlevel public
+ * @privilege %http://tizen.org/privilege/datacontrol.consumer
*
* @return An error code
- * @param[in] dataId A string for identifying specific data, usually a database table to delete from @n
+ * @param[in] dataId The string that identifies the specific data, usually a database table to delete from @n
* The string consists of one or more components, separated by a slash('/').
- * @param[in] pWhere A filter to select desired rows to delete @n
+ * @param[in] pWhere The filter to select the desired rows to delete @n
* It is an SQL 'WHERE' clause excluding the 'WHERE' itself such as
- * column1 = 'stringValue' AND column2 = numericValue.
- * If it is @c null, all rows are deleted.
+ * column1 = 'stringValue' AND column2 = numericValue @n
+ * If it is @c null, all the rows are deleted @n
+ * If the value is a string, the value must be wrapped in single quotes,
+ * else it need not be wrapped in single quotes @n
+ * For more information on the SQL statement, see SQLITE SQL documents.
* @param[out] reqId The request ID
* @exception E_SUCCESS The method is successful.
- * @exception E_INVALID_STATE This instance has not been properly constructed.
- * @exception E_INVALID_ARG A specified parameter is invalid.
- * @exception E_ILLEGAL_ACCESS Either of the following conditions has occurred: @n
- * - Access is denied due to insufficient permission.
- * - The application using this method is not signed with the same certificate of provider application. @b Since: @b 2.1
- * @exception E_MAX_EXCEEDED Either of the following conditions has occurred: @n
- * - The size of sending buffer has exceeded the maximum limit.
- * - The number of sending requests has exceeded the maximum limit.
+ * @exception E_INVALID_STATE This instance has not been constructed properly.
+ * @exception E_INVALID_ARG A specified input parameter is invalid.
+ * @exception E_ILLEGAL_ACCESS Either of the following conditions has occurred:
+ * - The access is denied due to insufficient permission.
+ * - The application using this method is not signed with the same certificate as that of the provider application. @b Since: @b 2.1
+ * @exception E_MAX_EXCEEDED Either of the following conditions has occurred:
+ * - The size of the sending buffer has exceeded the maximum limit.
+ * - The number of sending requests have exceeded the maximum limit.
+ * @exception E_PRIVILEGE_DENIED The application does not have the privilege to call this method.
* @exception E_SYSTEM A system error has occurred.
- * @remarks If the value specified in the @c pWhere is string, the value must be wrapped in
- * single quotes. Otherwise it is not needed to wrap the numeric value in single quotes.
- * For more information on the SQL statement, see SQLITE SQL documents.
- * @remarks The recommended data size is under 16KB because severe system performance degradation may occur for large messages. E_MAX_EXCEEDED may be returned for messages over 16KB size.
+ * @remarks The recommended data size is under 16KB because a severe system performance degradation may occur for larger messages. @n
+ * @c E_MAX_EXCEEDED may be returned for messages over 16KB.
*/
result Delete(const Tizen::Base::String& dataId, const Tizen::Base::String* pWhere, RequestId& reqId);
/**
- * Sets an SQL-type data control listener to this instance.
+ * Sets an SQL-friendly interface based data control listener to this instance.
*
* @since 2.0
*
* @return An error code
* @param[in] pListener The data control callback listener @n
- * Some data controls need to get the callback result by implementing
+ * Some data controls get the callback result by implementing
* the ISqlDataControlResponseListener interface.
* @exception E_SUCCESS The method is successful.
- * @exception E_INVALID_STATE This instance has not been properly constructed.
+ * @exception E_INVALID_STATE This instance has not been constructed properly.
* @exception E_SYSTEM A system error has occurred.
*/
result SetSqlDataControlResponseListener(ISqlDataControlResponseListener* pListener);
projects / platform / framework / native / appfw.git / blobdiff