inc/FAppSqlDataControl.h

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