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  * @code
  64  *
  65  * #include <FBase.h>
  66  * #include <FIo.h>
  67  *
  68  * using namespace Tizen::Base;
  69  * using namespace Tizen::Io;
  70  *
  71  * class MySqlDataControlResponseListener:
  72  *      : public Tizen::App::ISqlDataControlResponseListener
  73  * {
  74  * public:
  75  *      void OnSqlDataControlInsertResponseReceived(RequestId reqId, const String& providerId, const String& dataId, long long insertRowId, bool providerResult, const String* pErrorMsg)
  76  *      {
  77  *              AppLog("Row Id = %d", insertRowId);
  78  *      }
  79  * };
  80  *
  81  * void
  82  * MyClass::Execute(void)
  83  * {
  84  *              String providerId(L"http://tizen.org/datacontrol/provider/example");
  85  *              SqlDataControl* pDc = AppManager::GetSqlDataControlN(providerId);
  86  *
  87  *              MySqlDataControlResponseListener* pResponseListener = new MySqlDataControlResponseListener();
  88  *
  89  *              pDc->SetSqlDataControlResponseListener(pResponseListener);
  90  *
  91  *              String dataId(L"test");
  92  *              String person(L"person");
  93  *              String number(L"number");
  94  *              RequestId reqId;
  95  *
  96  *              ArrayList columnList(SingleObjectDeleter);
  97  *              columnList.Construct();
  98  *
  99  *              columnList.Add(person);
 100  *              columnList.Add(number);
 101  *
 102  *              String where(L"group = 'friend'");
 103  *              String order(L"person ASC");
 104  *
 105  *              pDc->Select(dataId, &columnList, &where, &order, reqId);
 106  * }
 107  *
 108  * @endcode
 109
 110  */
 111
 112 class _OSP_EXPORT_ SqlDataControl
 113         : public Tizen::Base::Object
 114 {
 115
 116 public:
 117         /**
 118         * This destructor overrides Tizen::Base::Object::~Object().
 119         *
 120         * @since        2.0
 121         */
 122         virtual ~SqlDataControl(void);
 123
 124         /**
 125         * Selects the specified columns to be queried. @n
 126         * The result set of the specified columns is retrieved from a table owned by an SQL-type data control provider. @n
 127         * The %Select() method is asynchronous.
 128         * For receiving the response from the data control provider, set the listener with
 129         * SqlDataControl::SetSqlDataControlResponseListener(). @n
 130         * When the requested result set has been received from the data control provider,
 131         * the ISqlDataControlResponseListener::OnSqlDataControlSelectResponseReceived() method is called.
 132         *
 133         * @since        2.0
 134         *
 135         * @return               An error code
 136         * @param[in]    dataId                          A string for identifying specific data, usually a database table to query from @n
 137         *                                                                       The string consists of one or more components, separated by a slash('/').
 138         * @param[in]    pColumnList                     A list of column names to query @n
 139         *                                                                       The type of objects contained in the specified @c pColumnList must be
 140         *                                                                       Tizen::Base::String class.
 141         *                                                                       If the specified @c pColumnList is @c null, all columns are selected.
 142         * @param[in]    pWhere                          A filter to select desired rows to query @n
 143         *                                                                       It is an SQL 'WHERE' clause excluding the 'WHERE' itself such as
 144         *                                                                       column1 = 'stringValue' AND column2 = numericValue.
 145         * @param[in]    pOrder                          The sorting order of rows to query @n
 146         *                                                                       It is an SQL 'ORDER BY' clause excluding the 'ORDER BY' itself.
 147         * @param[out]   reqId                           The request ID
 148         * @param[in]    pageNo                          The page number of the result set @n It starts from @c 1.
 149         * @param[in]    countPerPage            The desired maximum count of rows on a page
 150         * @exception    E_SUCCESS                       The method is successful.
 151         * @exception    E_INVALID_STATE         This instance has not been properly constructed.
 152         * @exception    E_INVALID_ARG           Either of the following conditions has occurred: @n
 153         *                                                                       - The specified @c pColumnList is empty.
 154         *                                                                       - The specified @c pageNo parameter is less than @c 1.
 155         *                                                                       - The specified @c countPerPage parameter is less than @c 1.
 156         * @exception    E_ILLEGAL_ACCESS        Either of the following conditions has occurred: @n
 157         *                                                                       - Access is denied due to insufficient permission.
 158         *                                                                       - The application using this method is not signed with the same certificate of provider application. @b Since: @b 2.1
 159         * @exception    E_MAX_EXCEEDED          Either of the following conditions has occurred:
 160         *                                                                       - The size of sending buffer has exceeded the maximum limit.
 161         *                                                                       - The number of sending requests has exceeded the maximum limit.
 162         * @exception    E_SYSTEM                        A system error has occurred.
 163         * @remarks              If the value specified in the @c pWhere is string, the value must be wrapped in
 164         *                               single quotes. Otherwise it is not needed to wrap the numeric value in single quotes.
 165         *                               For more information on the SQL statement, see SQLite SQL documents.
 166         * @remarks              The recommended data size is under 16KB because severe system performance degradation may occur for large messages. @c E_MAX_EXCEEDED may be returned for messages over 16KB size.
 167         */
 168         result Select(const Tizen::Base::String& dataId, const Tizen::Base::Collection::IList* pColumnList,
 169                         const Tizen::Base::String* pWhere, const Tizen::Base::String *pOrder, RequestId& reqId,
 170                         int pageNo = 1, int countPerPage = 20);
 171
 172         /**
 173         * Inserts new rows into a table owned by an SQL-type data control provider. @n
 174         * The %Insert() method is asynchronous.
 175         * For receiving the response from the data control provider, set the listener with
 176         * SqlDataControl::SetSqlDataControlResponseListener(). @n
 177         * When the response has been received from the data control provider,
 178         * the ISqlDataControlResponseListener::OnSqlDataControlInsertResponseReceived() method is called.
 179         *
 180         * @since        2.0
 181         *
 182         * @return               An error code
 183         * @param[in]    dataId                          A string for identifying specific data, usually a database table to insert into @n
 184         *                                                                       The string consists of one or more components, separated by a slash('/').
 185         * @param[in]    insertMap                       The column-value pairs to insert @n
 186         *                                                                       The type of objects contained in the specified @c insertMap must be
 187         *                                                                       Tizen::Base::String class.
 188         * @param[out]   reqId                           The request ID
 189         * @exception    E_SUCCESS                       The method is successful.
 190         * @exception    E_INVALID_STATE         This instance has not been properly constructed.
 191         * @exception    E_INVALID_ARG           The specified @c insertMap is empty.
 192         * @exception    E_ILLEGAL_ACCESS        Either of the following conditions has occurred: @n
 193         *                                                                       - Access is denied due to insufficient permission.
 194         *                                                                       - The application using this method is not signed with the same certificate of provider application. @b Since: @b 2.1
 195         * @exception    E_MAX_EXCEEDED          Either of the following conditions has occurred:
 196         *                                                                       - The size of sending buffer has exceeded the maximum limit.
 197         *                                                                       - The number of sending requests has exceeded the maximum limit.
 198         * @exception    E_SYSTEM                        A system error has occurred.
 199         * @remarks              If the value specified in the @c insertMap is string, the value must be wrapped in
 200         *                               single quotes. Otherwise it is not needed to wrap the numeric value in single quotes.
 201         *                               For more information on the SQL statement, see SQLite SQL documents.
 202         * @remarks              The recommended data size is under 1MB because severe system performance degradation may occur for large messages. @c E_MAX_EXCEEDED may be returned for messages over 1MB size.
 203         */
 204         result Insert(const Tizen::Base::String& dataId, const Tizen::Base::Collection::IMap& insertMap, RequestId& reqId);
 205
 206         /**
 207         * Updates values of a table owned by an SQL-type data control provider. @n
 208         * The %Update() method is asynchronous.
 209         * For receiving the response from the data control provider, set the listener with
 210         * SqlDataControl::SetSqlDataControlResponseListener(). @n
 211         * When the response has been received from the data control provider,
 212         * the ISqlDataControlResponseListener::OnSqlDataControlUpdateResponseReceived() method is called.
 213         *
 214         * @since        2.0
 215         *
 216         * @return               An error code
 217         * @param[in]    dataId                          A string for identifying specific data, usually a database table to update @n
 218         *                                                                       The string consists of one or more components, separated by a slash('/').
 219         * @param[in]    updateMap                       The column-value pairs to update @n
 220         *                                                                       The type of objects contained in the specified @c updateMap must be
 221         *                                                                       Tizen::Base::String class.
 222         * @param[in]    pWhere                          A filter to select desired rows to update @n
 223         *                                                                       It is an SQL 'WHERE' clause excluding the 'WHERE' itself such as
 224         *                                                                       column1 = 'stringValue' AND column2 = numericValue.
 225         * @param[out]   reqId                           The request ID
 226         * @exception    E_SUCCESS                       The method is successful.
 227         * @exception    E_INVALID_STATE         This instance has not been properly constructed.
 228         * @exception    E_INVALID_ARG           The specified @c updateMap is empty.
 229         * @exception    E_ILLEGAL_ACCESS        Either of the following conditions has occurred: @n
 230         *                                                                       - Access is denied due to insufficient permission.
 231         *                                                                       - The application using this method is not signed with the same certificate of provider application. @b Since: @b 2.1
 232         * @exception    E_MAX_EXCEEDED          Either of the following conditions has occurred:
 233         *                                                                       - The size of sending buffer has exceeded the maximum limit.
 234         *                                                                       - The number of sending requests has exceeded the maximum limit.
 235         * @exception    E_SYSTEM                        A system error has occurred.
 236         * @remarks              If the value specified in the @c pWhere or @c updateMap is string, the value must be wrapped in
 237         *                               single quotes. Otherwise it is not needed to wrap the numeric value in single quotes.
 238         *                               For more information on the SQL statement, see SQLITE SQL documents.
 239         * @remarks              The recommended data size is under 1MB because severe system performance degradation may occur for large messages. @c E_MAX_EXCEEDED may be returned for messages over 1MB size.
 240         */
 241         result Update(const Tizen::Base::String& dataId, const Tizen::Base::Collection::IMap& updateMap,
 242                         const Tizen::Base::String* pWhere, RequestId& reqId);
 243
 244         /**
 245         * Deletes rows of a table owned by an SQL-type data control provider. @n
 246         * The %Delete() method is asynchronous.
 247         * For receiving the response from the data control provider, set the listener with
 248         * SqlDataControl::SetSqlDataControlResponseListener(). @n
 249         * When the response has been received from the data control provider,
 250         * the ISqlDataControlResponseListener::OnSqlDataControlDeleteResponseReceived() method is called.
 251         *
 252         * @since        2.0
 253         *
 254         * @return               An error code
 255         * @param[in]    dataId                          A string for identifying specific data, usually a database table to delete from @n
 256         *                                                                       The string consists of one or more components, separated by a slash('/').
 257         * @param[in]    pWhere                          A filter to select desired rows to delete @n
 258         *                                                                       It is an SQL 'WHERE' clause excluding the 'WHERE' itself such as
 259         *                                                                       column1 = 'stringValue' AND column2 = numericValue.
 260         *                                                                       If it is @c null, all rows are deleted.
 261         * @param[out]   reqId                           The request ID
 262         * @exception    E_SUCCESS                       The method is successful.
 263         * @exception    E_INVALID_STATE         This instance has not been properly constructed.
 264         * @exception    E_INVALID_ARG           A specified parameter is invalid.
 265         * @exception    E_ILLEGAL_ACCESS        Either of the following conditions has occurred: @n
 266         *                                                                       - Access is denied due to insufficient permission.
 267         *                                                                       - The application using this method is not signed with the same certificate of provider application. @b Since: @b 2.1
 268         * @exception    E_MAX_EXCEEDED          Either of the following conditions has occurred:
 269         *                                                                       - The size of sending buffer has exceeded the maximum limit.
 270         *                                                                       - The number of sending requests has exceeded the maximum limit.
 271         * @exception    E_SYSTEM                        A system error has occurred.
 272         * @remarks              If the value specified in the @c pWhere is string, the value must be wrapped in
 273         *                               single quotes. Otherwise it is not needed to wrap the numeric value in single quotes.
 274         *                               For more information on the SQL statement, see SQLITE SQL documents.
 275         * @remarks              The recommended data size is under 16KB because severe system performance degradation may occur for large messages. @c E_MAX_EXCEEDED may be returned for messages over 16KB size.
 276         */
 277         result Delete(const Tizen::Base::String& dataId, const Tizen::Base::String* pWhere, RequestId& reqId);
 278
 279         /**
 280         * Sets an SQL-type data control listener to this instance.
 281         *
 282         * @since        2.0
 283         *
 284         * @return               An error code
 285         * @param[in]    pListener                       The data control callback listener @n
 286         *                                                                       Some data controls need to get the callback result by implementing
 287         *                                                                       the ISqlDataControlResponseListener interface.
 288         * @exception    E_SUCCESS                       The method is successful.
 289         * @exception    E_INVALID_STATE         This instance has not been properly constructed.
 290         * @exception    E_SYSTEM                        A system error has occurred.
 291         */
 292         result SetSqlDataControlResponseListener(ISqlDataControlResponseListener* pListener);
 293
 294 private:
 295         /**
 296         * This default constructor is intentionally declared as private so that only the platform can create an instance.
 297         *
 298         * @since        2.0
 299         */
 300         SqlDataControl(void);
 301
 302         /**
 303         * The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
 304         *
 305         * @since        2.0
 306         * @remarks      This constructor is hidden.
 307         */
 308         SqlDataControl(const SqlDataControl& rhs);
 309
 310         /**
 311         * The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
 312         *
 313         * @since        2.0
 314         * @remarks      This operator is hidden.
 315         */
 316         SqlDataControl& operator =(const SqlDataControl& rhs);
 317
 318         class _SqlDataControlImpl* __pSqlDataControlImpl;
 319
 320         friend class _SqlDataControlImpl;
 321
 322 }; // SqlDataControl
 323
 324 }} // Tizen::App
 325
 326 #endif // _FAPP_SQL_DATA_CONTROL_H_
 327