X-Git-Url: http://review.tizen.org/git/?a=blobdiff_plain;f=inc%2FFAppSqlDataControl.h;h=b792a5064fd5613b65fa689101b28223502fa4a9;hb=20597a73bc3098301ba91a48378f3ef009c3be96;hp=fbc4a61c259b59137b4f1b807a262b0abb3e42af;hpb=e0e3240114c08edf7a996573ad75a533b7d14ecb;p=platform%2Fframework%2Fnative%2Fappfw.git diff --git a/inc/FAppSqlDataControl.h b/inc/FAppSqlDataControl.h index fbc4a61..b792a50 100755 --- a/inc/FAppSqlDataControl.h +++ b/inc/FAppSqlDataControl.h @@ -1,5 +1,4 @@ // -// Open Service Platform // Copyright (c) 2012 Samsung Electronics Co., Ltd. // // Licensed under the Apache License, Version 2.0 (the License); @@ -46,19 +45,67 @@ class ISqlDataControlResponseListener; /** * @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 Data Controls. * * @see Tizen::App::AppManager + * + * @code + * + * #include + * #include + * + * 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 @@ -75,162 +122,176 @@ public: /** * 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 * * @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 The size of sending buffer 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_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 * * @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 The size of sending buffer 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_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 * * @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 The size of sending buffer 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_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 * * @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 The size of sending buffer 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_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);