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          The size of sending buffer has exceeded the maximum limit.
 112         * @exception    E_SYSTEM                        A system error has occurred.
 113         * @remarks              If the value specified in the @c pWhere is string, the value must be wrapped in
 114         *                               single quotes. Otherwise it is not needed to wrap the numeric value in single quotes.
 115         *                               For more information on the SQL statement, see SQLite SQL documents.
 116         * @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.
 117         */
 118         result Select(const Tizen::Base::String& dataId, const Tizen::Base::Collection::IList* pColumnList,
 119                         const Tizen::Base::String* pWhere, const Tizen::Base::String *pOrder, RequestId& reqId,
 120                         int pageNo = 1, int countPerPage = 20);
 121
 122         /**
 123         * Inserts new rows into a table owned by an SQL-type data control provider. @n
 124         * The %Insert() method is asynchronous.
 125         * For receiving the response from the data control provider, set the listener with
 126         * SqlDataControl::SetSqlDataControlResponseListener(). @n
 127         * When the response has been received from the data control provider,
 128         * the ISqlDataControlResponseListener::OnSqlDataControlInsertResponseReceived() method is called.
 129         *
 130         * @since        2.0
 131         *
 132         * @return               An error code
 133         * @param[in]    dataId                          A string for identifying specific data, usually a database table to insert into @n
 134         *                                                                       The string consists of one or more components, separated by a slash('/').
 135         * @param[in]    insertMap                       The column-value pairs to insert @n
 136         *                                                                       The type of objects contained in the specified @c insertMap must be
 137         *                                                                       Tizen::Base::String class.
 138         * @param[out]   reqId                           The request ID
 139         * @exception    E_SUCCESS                       The method is successful.
 140         * @exception    E_INVALID_STATE         This instance has not been properly constructed.
 141         * @exception    E_INVALID_ARG           The specified @c insertMap is empty.
 142         * @exception    E_ILLEGAL_ACCESS        Either of the following conditions has occurred: @n
 143         *                                                                       - Access is denied due to insufficient permission.
 144         *                                                                       - The application using this method is not signed with the same certificate of provider application. @b Since: @b 2.1
 145         * @exception    E_MAX_EXCEEDED          The size of sending buffer has exceeded the maximum limit.
 146         * @exception    E_SYSTEM                        A system error has occurred.
 147         * @remarks              If the value specified in the @c insertMap is string, the value must be wrapped in
 148         *                               single quotes. Otherwise it is not needed to wrap the numeric value in single quotes.
 149         *                               For more information on the SQL statement, see SQLite SQL documents.
 150         * @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.
 151         */
 152         result Insert(const Tizen::Base::String& dataId, const Tizen::Base::Collection::IMap& insertMap, RequestId& reqId);
 153
 154         /**
 155         * Updates values of a table owned by an SQL-type data control provider. @n
 156         * The %Update() method is asynchronous.
 157         * For receiving the response from the data control provider, set the listener with
 158         * SqlDataControl::SetSqlDataControlResponseListener(). @n
 159         * When the response has been received from the data control provider,
 160         * the ISqlDataControlResponseListener::OnSqlDataControlUpdateResponseReceived() method is called.
 161         *
 162         * @since        2.0
 163         *
 164         * @return               An error code
 165         * @param[in]    dataId                          A string for identifying specific data, usually a database table to update @n
 166         *                                                                       The string consists of one or more components, separated by a slash('/').
 167         * @param[in]    updateMap                       The column-value pairs to update @n
 168         *                                                                       The type of objects contained in the specified @c updateMap must be
 169         *                                                                       Tizen::Base::String class. @n
 170         * @param[in]    pWhere                          A filter to select desired rows to update @n
 171         *                                                                       It is an SQL 'WHERE' clause excluding the 'WHERE' itself such as
 172         *                                                                       column1 = 'stringValue' AND column2 = numericValue.
 173         * @param[out]   reqId                           The request ID
 174         * @exception    E_SUCCESS                       The method is successful.
 175         * @exception    E_INVALID_STATE         This instance has not been properly constructed.
 176         * @exception    E_INVALID_ARG           The specified @c updateMap is empty.
 177         * @exception    E_ILLEGAL_ACCESS        Either of the following conditions has occurred: @n
 178         *                                                                       - Access is denied due to insufficient permission.
 179         *                                                                       - The application using this method is not signed with the same certificate of provider application. @b Since: @b 2.1
 180         * @exception    E_MAX_EXCEEDED          The size of sending buffer has exceeded the maximum limit.
 181         * @exception    E_SYSTEM                        A system error has occurred.
 182         * @remarks              If the value specified in the @c pWhere or @c updateMap is string, the value must be wrapped in
 183         *                               single quotes. Otherwise it is not needed to wrap the numeric value in single quotes.
 184         *                               For more information on the SQL statement, see SQLITE SQL documents.
 185         * @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.
 186         */
 187         result Update(const Tizen::Base::String& dataId, const Tizen::Base::Collection::IMap& updateMap,
 188                         const Tizen::Base::String* pWhere, RequestId& reqId);
 189
 190         /**
 191         * Deletes rows of a table owned by an SQL-type data control provider. @n
 192         * The %Delete() method is asynchronous.
 193         * For receiving the response from the data control provider, set the listener with
 194         * SqlDataControl::SetSqlDataControlResponseListener(). @n
 195         * When the response has been received from the data control provider,
 196         * the ISqlDataControlResponseListener::OnSqlDataControlDeleteResponseReceived() method is called.
 197         *
 198         * @since        2.0
 199         *
 200         * @return               An error code
 201         * @param[in]    dataId                          A string for identifying specific data, usually a database table to delete from @n
 202         *                                                                       The string consists of one or more components, separated by a slash('/').
 203         * @param[in]    pWhere                          A filter to select desired rows to delete @n
 204         *                                                                       It is an SQL 'WHERE' clause excluding the 'WHERE' itself such as
 205         *                                                                       column1 = 'stringValue' AND column2 = numericValue.
 206         *                                                                       If it is @c null, all rows are deleted.
 207         * @param[out]   reqId                           The request ID
 208         * @exception    E_SUCCESS                       The method is successful.
 209         * @exception    E_INVALID_STATE         This instance has not been properly constructed.
 210         * @exception    E_INVALID_ARG           A specified parameter is invalid.
 211         * @exception    E_ILLEGAL_ACCESS        Either of the following conditions has occurred: @n
 212         *                                                                       - Access is denied due to insufficient permission.
 213         *                                                                       - The application using this method is not signed with the same certificate of provider application. @b Since: @b 2.1
 214         * @exception    E_MAX_EXCEEDED          The size of sending buffer has exceeded the maximum limit.
 215         * @exception    E_SYSTEM                        A system error has occurred.
 216         * @remarks              If the value specified in the @c pWhere is string, the value must be wrapped in
 217         *                               single quotes. Otherwise it is not needed to wrap the numeric value in single quotes.
 218         *                               For more information on the SQL statement, see SQLITE SQL documents.
 219         * @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.
 220         */
 221         result Delete(const Tizen::Base::String& dataId, const Tizen::Base::String* pWhere, RequestId& reqId);
 222
 223         /**
 224         * Sets an SQL-type data control listener to this instance.
 225         *
 226         * @since        2.0
 227         *
 228         * @return               An error code
 229         * @param[in]    pListener                       The data control callback listener @n
 230         *                                                                       Some data controls need to get the callback result by implementing
 231         *                                                                       the ISqlDataControlResponseListener interface.
 232         * @exception    E_SUCCESS                       The method is successful.
 233         * @exception    E_INVALID_STATE         This instance has not been properly constructed.
 234         * @exception    E_SYSTEM                        A system error has occurred.
 235         */
 236         result SetSqlDataControlResponseListener(ISqlDataControlResponseListener* pListener);
 237
 238 private:
 239         /**
 240         * This default constructor is intentionally declared as private so that only the platform can create an instance.
 241         *
 242         * @since        2.0
 243         */
 244         SqlDataControl(void);
 245
 246         /**
 247         * The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
 248         *
 249         * @since        2.0
 250         * @remarks      This constructor is hidden.
 251         */
 252         SqlDataControl(const SqlDataControl& rhs);
 253
 254         /**
 255         * The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
 256         *
 257         * @since        2.0
 258         * @remarks      This operator is hidden.
 259         */
 260         SqlDataControl& operator =(const SqlDataControl& rhs);
 261
 262         class _SqlDataControlImpl* __pSqlDataControlImpl;
 263
 264         friend class _SqlDataControlImpl;
 265
 266 }; // SqlDataControl
 267
 268 }} // Tizen::App
 269
 270 #endif // _FAPP_SQL_DATA_CONTROL_H_
 271