inc/FAppSqlDataControl.h

   1 //
   2 // Open Service Platform
   3 // Copyright (c) 2012 Samsung Electronics Co., Ltd.
   4 //
   5 // Licensed under the Apache License, Version 2.0 (the License);
   6 // you may not use this file except in compliance with the License.
   7 // You may obtain a copy of the License at
   8 //
   9 //     http://www.apache.org/licenses/LICENSE-2.0
  10 //
  11 // Unless required by applicable law or agreed to in writing, software
  12 // distributed under the License is distributed on an "AS IS" BASIS,
  13 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  14 // See the License for the specific language governing permissions and
  15 // limitations under the License.
  16 //
  17
  18 /**
  19 * @file       FAppSqlDataControl.h
  20 * @brief      This is the header file for the %SqlDataControl class.
  21 *
  22 * This header file contains the declarations of the %SqlDataControl class.
  23 */
  24
  25 #ifndef _FAPP_SQL_DATA_CONTROL_H_
  26 #define _FAPP_SQL_DATA_CONTROL_H_
  27
  28 #include <FOspConfig.h>
  29 #include <FBaseDataType.h>
  30 #include <FBaseObject.h>
  31
  32 namespace Tizen { namespace Base
  33 {
  34 class String;
  35 namespace Collection {
  36 class IList;
  37 class IMap;
  38 }
  39 }}
  40
  41 namespace Tizen { namespace App
  42 {
  43
  44 class _SqlDataControlImpl;
  45 class ISqlDataControlResponseListener;
  46
  47 /**
  48  * @class   SqlDataControl
  49  * @brief   This class represents the SQL-type data control behavior.
  50  *
  51  * @since       2.0
  52  *
  53  * @final   This class is not intended for extension.
  54  *
  55  * The %SqlDataControl class represents the data control behavior, that provides a standard mechanism
  56  * for accessing specific data exported by other applications.
  57  * Data control provider can share its own data to data control consumers.
  58  *
  59  * For more information on the class features, see <a href="../org.tizen.native.appprogramming/html/guide/app/data_controls.htm">Data Controls</a>.
  60  *
  61  * @see Tizen::App::AppManager
  62  */
  63
  64 class _OSP_EXPORT_ SqlDataControl
  65         : public Tizen::Base::Object
  66 {
  67
  68 public:
  69         /**
  70         * This destructor overrides Tizen::Base::Object::~Object().
  71         *
  72         * @since        2.0
  73         */
  74         virtual ~SqlDataControl(void);
  75
  76         /**
  77         * Selects the specified columns to be queried. @n
  78         * The result set of the specified columns is retrieved from a table owned by an SQL-type data control provider. @n
  79         * The %Select() method is asynchronous.
  80         * For receiving the response from the data control provider, set the listener with
  81         * SqlDataControl::SetSqlDataControlResponseListener(). @n
  82         * When the requested result set has been received from the data control provider,
  83         * the ISqlDataControlResponseListener::OnSqlDataControlSelectResponseReceived() method is called.
  84         *
  85         * @since        2.0
  86         *
  87         * @return               An error code
  88         * @param[in]    dataId                          A string for identifying specific data, usually a database table to query from @n
  89         *                                                                       The string consists of one or more components, separated by a slash('/').
  90         * @param[in]    pColumnList                     A list of column names to query @n
  91         *                                                                       The type of objects contained in the specified @c pColumnList must be
  92         *                                                                       Tizen::Base::String class.
  93         *                                                                       If the specified @c pColumnList is @c null, all columns are selected.
  94         * @param[in]    pWhere                          A filter to select desired rows to query @n
  95         *                                                                       It is an SQL 'WHERE' clause excluding the 'WHERE' itself such as
  96         *                                                                       column1 = 'stringValue' AND column2 = numericValue.
  97         * @param[in]    pOrder                          The sorting order of rows to query @n
  98         *                                                                       It is an SQL 'ORDER BY' clause excluding the 'ORDER BY' itself.
  99         * @param[out]   reqId                           The request ID
 100         * @param[in]    pageNo                          The page number of the result set @n It starts from @c 1.
 101         * @param[in]    countPerPage            The desired maximum count of rows on a page
 102         * @exception    E_SUCCESS                       The method is successful.
 103         * @exception    E_INVALID_STATE         This instance has not been properly constructed.
 104         * @exception    E_INVALID_ARG           Either of the following conditions has occurred: @n
 105         *                                                                       - The specified @c pColumnList is empty.
 106         *                                                                       - The specified @c pageNo parameter is less than @c 1.
 107         *                                                                       - The specified @c countPerPage parameter is less than @c 1.
 108         * @exception    E_ILLEGAL_ACCESS        Either of the following conditions has occurred: @n
 109         *                                                                       - Access is denied due to insufficient permission.
 110         *                                                                       - The application using this method is not signed with the same certificate of provider application. @b Since: @b 2.1
 111         * @exception    E_MAX_EXCEEDED          Either of the following conditions has occurred: @n
 112         *                                                                       - The size of sending buffer has exceeded the maximum limit.
 113         *                                                                       - The number of sending requests has exceeded the maximum limit.
 114         * @exception    E_SYSTEM                        A system error has occurred.
 115         * @remarks              If the value specified in the @c pWhere is string, the value must be wrapped in
 116         *                               single quotes. Otherwise it is not needed to wrap the numeric value in single quotes.
 117         *                               For more information on the SQL statement, see SQLite SQL documents.
 118         * @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.
 119         */
 120         result Select(const Tizen::Base::String& dataId, const Tizen::Base::Collection::IList* pColumnList,
 121                         const Tizen::Base::String* pWhere, const Tizen::Base::String *pOrder, RequestId& reqId,
 122                         int pageNo = 1, int countPerPage = 20);
 123
 124         /**
 125         * Inserts new rows into a table owned by an SQL-type data control provider. @n
 126         * The %Insert() method is asynchronous.
 127         * For receiving the response from the data control provider, set the listener with
 128         * SqlDataControl::SetSqlDataControlResponseListener(). @n
 129         * When the response has been received from the data control provider,
 130         * the ISqlDataControlResponseListener::OnSqlDataControlInsertResponseReceived() method is called.
 131         *
 132         * @since        2.0
 133         *
 134         * @return               An error code
 135         * @param[in]    dataId                          A string for identifying specific data, usually a database table to insert into @n
 136         *                                                                       The string consists of one or more components, separated by a slash('/').
 137         * @param[in]    insertMap                       The column-value pairs to insert @n
 138         *                                                                       The type of objects contained in the specified @c insertMap must be
 139         *                                                                       Tizen::Base::String class.
 140         * @param[out]   reqId                           The request ID
 141         * @exception    E_SUCCESS                       The method is successful.
 142         * @exception    E_INVALID_STATE         This instance has not been properly constructed.
 143         * @exception    E_INVALID_ARG           The specified @c insertMap is empty.
 144         * @exception    E_ILLEGAL_ACCESS        Either of the following conditions has occurred: @n
 145         *                                                                       - Access is denied due to insufficient permission.
 146         *                                                                       - The application using this method is not signed with the same certificate of provider application. @b Since: @b 2.1
 147         * @exception    E_MAX_EXCEEDED          Either of the following conditions has occurred: @n
 148         *                                                                       - The size of sending buffer has exceeded the maximum limit.
 149         *                                                                       - The number of sending requests has exceeded the maximum limit.
 150         * @exception    E_SYSTEM                        A system error has occurred.
 151         * @remarks              If the value specified in the @c insertMap is string, the value must be wrapped in
 152         *                               single quotes. Otherwise it is not needed to wrap the numeric value in single quotes.
 153         *                               For more information on the SQL statement, see SQLite SQL documents.
 154         * @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.
 155         */
 156         result Insert(const Tizen::Base::String& dataId, const Tizen::Base::Collection::IMap& insertMap, RequestId& reqId);
 157
 158         /**
 159         * Updates values of a table owned by an SQL-type data control provider. @n
 160         * The %Update() method is asynchronous.
 161         * For receiving the response from the data control provider, set the listener with
 162         * SqlDataControl::SetSqlDataControlResponseListener(). @n
 163         * When the response has been received from the data control provider,
 164         * the ISqlDataControlResponseListener::OnSqlDataControlUpdateResponseReceived() method is called.
 165         *
 166         * @since        2.0
 167         *
 168         * @return               An error code
 169         * @param[in]    dataId                          A string for identifying specific data, usually a database table to update @n
 170         *                                                                       The string consists of one or more components, separated by a slash('/').
 171         * @param[in]    updateMap                       The column-value pairs to update @n
 172         *                                                                       The type of objects contained in the specified @c updateMap must be
 173         *                                                                       Tizen::Base::String class. @n
 174         * @param[in]    pWhere                          A filter to select desired rows to update @n
 175         *                                                                       It is an SQL 'WHERE' clause excluding the 'WHERE' itself such as
 176         *                                                                       column1 = 'stringValue' AND column2 = numericValue.
 177         * @param[out]   reqId                           The request ID
 178         * @exception    E_SUCCESS                       The method is successful.
 179         * @exception    E_INVALID_STATE         This instance has not been properly constructed.
 180         * @exception    E_INVALID_ARG           The specified @c updateMap is empty.
 181         * @exception    E_ILLEGAL_ACCESS        Either of the following conditions has occurred: @n
 182         *                                                                       - Access is denied due to insufficient permission.
 183         *                                                                       - The application using this method is not signed with the same certificate of provider application. @b Since: @b 2.1
 184         * @exception    E_MAX_EXCEEDED          Either of the following conditions has occurred: @n
 185         *                                                                       - The size of sending buffer has exceeded the maximum limit.
 186         *                                                                       - The number of sending requests has exceeded the maximum limit.
 187         * @exception    E_SYSTEM                        A system error has occurred.
 188         * @remarks              If the value specified in the @c pWhere or @c updateMap is string, the value must be wrapped in
 189         *                               single quotes. Otherwise it is not needed to wrap the numeric value in single quotes.
 190         *                               For more information on the SQL statement, see SQLITE SQL documents.
 191         * @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.
 192         */
 193         result Update(const Tizen::Base::String& dataId, const Tizen::Base::Collection::IMap& updateMap,
 194                         const Tizen::Base::String* pWhere, RequestId& reqId);
 195
 196         /**
 197         * Deletes rows of a table owned by an SQL-type data control provider. @n
 198         * The %Delete() method is asynchronous.
 199         * For receiving the response from the data control provider, set the listener with
 200         * SqlDataControl::SetSqlDataControlResponseListener(). @n
 201         * When the response has been received from the data control provider,
 202         * the ISqlDataControlResponseListener::OnSqlDataControlDeleteResponseReceived() method is called.
 203         *
 204         * @since        2.0
 205         *
 206         * @return               An error code
 207         * @param[in]    dataId                          A string for identifying specific data, usually a database table to delete from @n
 208         *                                                                       The string consists of one or more components, separated by a slash('/').
 209         * @param[in]    pWhere                          A filter to select desired rows to delete @n
 210         *                                                                       It is an SQL 'WHERE' clause excluding the 'WHERE' itself such as
 211         *                                                                       column1 = 'stringValue' AND column2 = numericValue.
 212         *                                                                       If it is @c null, all rows are deleted.
 213         * @param[out]   reqId                           The request ID
 214         * @exception    E_SUCCESS                       The method is successful.
 215         * @exception    E_INVALID_STATE         This instance has not been properly constructed.
 216         * @exception    E_INVALID_ARG           A specified parameter is invalid.
 217         * @exception    E_ILLEGAL_ACCESS        Either of the following conditions has occurred: @n
 218         *                                                                       - Access is denied due to insufficient permission.
 219         *                                                                       - The application using this method is not signed with the same certificate of provider application. @b Since: @b 2.1
 220         * @exception    E_MAX_EXCEEDED          Either of the following conditions has occurred: @n
 221         *                                                                       - The size of sending buffer has exceeded the maximum limit.
 222         *                                                                       - The number of sending requests has exceeded the maximum limit.
 223         * @exception    E_SYSTEM                        A system error has occurred.
 224         * @remarks              If the value specified in the @c pWhere is string, the value must be wrapped in
 225         *                               single quotes. Otherwise it is not needed to wrap the numeric value in single quotes.
 226         *                               For more information on the SQL statement, see SQLITE SQL documents.
 227         * @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.
 228         */
 229         result Delete(const Tizen::Base::String& dataId, const Tizen::Base::String* pWhere, RequestId& reqId);
 230
 231         /**
 232         * Sets an SQL-type data control listener to this instance.
 233         *
 234         * @since        2.0
 235         *
 236         * @return               An error code
 237         * @param[in]    pListener                       The data control callback listener @n
 238         *                                                                       Some data controls need to get the callback result by implementing
 239         *                                                                       the ISqlDataControlResponseListener interface.
 240         * @exception    E_SUCCESS                       The method is successful.
 241         * @exception    E_INVALID_STATE         This instance has not been properly constructed.
 242         * @exception    E_SYSTEM                        A system error has occurred.
 243         */
 244         result SetSqlDataControlResponseListener(ISqlDataControlResponseListener* pListener);
 245
 246 private:
 247         /**
 248         * This default constructor is intentionally declared as private so that only the platform can create an instance.
 249         *
 250         * @since        2.0
 251         */
 252         SqlDataControl(void);
 253
 254         /**
 255         * The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
 256         *
 257         * @since        2.0
 258         * @remarks      This constructor is hidden.
 259         */
 260         SqlDataControl(const SqlDataControl& rhs);
 261
 262         /**
 263         * The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
 264         *
 265         * @since        2.0
 266         * @remarks      This operator is hidden.
 267         */
 268         SqlDataControl& operator =(const SqlDataControl& rhs);
 269
 270         class _SqlDataControlImpl* __pSqlDataControlImpl;
 271
 272         friend class _SqlDataControlImpl;
 273
 274 }; // SqlDataControl
 275
 276 }} // Tizen::App
 277
 278 #endif // _FAPP_SQL_DATA_CONTROL_H_
 279