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