inc/FAppDataControlProviderManager.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        FAppDataControlProviderManager.h
  19  * @brief       This is the header file for the %DataControlProviderManager class.
  20  *
  21  * This header file contains the declarations of the %DataControlProviderManager class.
  22  */
  23
  24 #ifndef _FAPP_DATA_CONTROL_PROVIDER_MANAGER_H_
  25 #define _FAPP_DATA_CONTROL_PROVIDER_MANAGER_H_
  26
  27 #include <FBaseDataType.h>
  28 #include <FBaseObject.h>
  29 #include <FBaseColIList.h>
  30 #include <FIoIDbEnumerator.h>
  31
  32 namespace Tizen { namespace Base
  33 {
  34 class String;
  35 class ByteBuffer;
  36 }}
  37 namespace Tizen { namespace Io
  38 {
  39 class DbEnumerator;
  40 class DataControlResultSet;
  41 }}
  42
  43 namespace Tizen { namespace App
  44 {
  45
  46 class ISqlDataControlProviderEventListener;
  47 class IMapDataControlProviderEventListener;
  48
  49 /**
  50  * @class       DataControlProviderManager
  51  * @brief       This class manages the data control provider.
  52  *
  53  * @since       2.0
  54  *
  55  * @final       This class is not intended for extension.
  56  *
  57  * The %DataControlProviderManager class helps a data control provider application to handle data control requests from other applications, and to send results or error messages for each data control operation.
  58  */
  59 class _OSP_EXPORT_ DataControlProviderManager
  60         : public Tizen::Base::Object
  61 {
  62
  63 public:
  64         /**
  65         * Sets an SQL-friendly interface based data control provider listener for the data control provider manager. @n
  66         * The listener gets notified when a data control request is received from other applications.
  67         * To unset the listener, pass a @c null value to the listener parameter.
  68         *
  69         * @since        2.0
  70         *
  71         * @return               An error code
  72         * @param[in]    pListener                       The SQL-friendly interface based data control provider listener @n
  73         *                                                                       The listener must implement the ISqlDataControlProviderEventListener interface.
  74         * @exception    E_SUCCESS                       The method is successful.
  75         * @exception    E_INVALID_STATE         This instance has not been properly constructed.
  76         * @exception    E_INVALID_OPERATION     The listener has not been set for a service application.
  77         * @exception    E_SYSTEM                        The method cannot proceed due to a severe system error.
  78         * @remarks              This method must be called by the App::OnAppInitializing() method for setting the data control provider listener
  79         *                               before receiving the data control request.
  80         */
  81         result SetSqlDataControlProviderEventListener(ISqlDataControlProviderEventListener* pListener);
  82
  83         /**
  84         * Sets a key-value structured data control provider listener for the data control provider manager. @n
  85         * The listener gets notified when a data control request is received from other applications.
  86         * To unset the listener, pass a @c null value to the listener parameter.
  87         *
  88         * @since        2.0
  89         *
  90         * @return               An error code
  91         * @param[in]    pListener                       The key-value structured data control provider listener @n
  92         *                                                                       The listener must implement the IMapDataControlProviderEventListener interface.
  93         * @exception    E_SUCCESS                       The method is successful.
  94         * @exception    E_INVALID_STATE         This instance has not been properly constructed.
  95         * @exception    E_INVALID_OPERATION     The listener has not been set for a service application.
  96         * @exception    E_SYSTEM                        The method cannot proceed due to a severe system error.
  97         * @remarks              This method must be called by the App::OnAppInitializing() method for setting the data control provider listener
  98         *                               before receiving the data control request.
  99         */
 100         result SetMapDataControlProviderEventListener(IMapDataControlProviderEventListener* pListener);
 101
 102         /**
 103         * Sends the success result and the result set of the SELECT request to the application requesting for the SQL-friendly interface based
 104         * data control. @n
 105         * The data control provider must call the %SendSqlDataControlSelectResult() method to notify success to the requesting application.
 106         * The application requesting the data control can get the success result and the result set
 107         * by implementing Tizen::App::ISqlDataControlResponseListener.
 108         *
 109         * @since        2.0
 110         *
 111         * @return               An error code
 112         * @param[in]    reqId                           The request ID
 113         * @param[in]    pDbEnum                         The Tizen::Io::DbEnumerator instance to obtain the result set
 114         * @exception    E_SUCCESS                       The method is successful.
 115         * @exception    E_INVALID_ARG           Either of the following conditions has occurred:
 116         *                                                               - The result for the specified @c reqId of the INSERT, UPDATE, or DELETE request cannot be sent.
 117         *                                                               - The Tizen::Io::Database or Tizen::Io::DbStatement instance associated with the specified @c pDbEnum is deleted.
 118         * @exception    E_OBJ_NOT_FOUND         The data control request specified by the @c reqId does not exist.
 119         * @exception    E_OBJECT_LOCKED         The database instance associated with the specified @c pDbEnum is locked.
 120         * @exception    E_INVALID_FORMAT        The database file associated with the specified @c pDbEnum is in an invalid format.
 121         * @exception    E_IO                            Either of the following conditions has occurred:
 122         *                                                       - An unexpected device failure has occurred as the media ejected suddenly.
 123         *                                                       - %File corruption has been detected.
 124         * @exception    E_MAX_EXCEEDED          The size of the sending buffer has exceeded the maximum limit.
 125         * @exception    E_SYSTEM                        The method cannot proceed due to a severe system error.
 126         * @see                  Tizen::App::DataControlProviderManager::SendSqlDataControlInsertResult()
 127         * @see                  Tizen::App::DataControlProviderManager::SendSqlDataControlUpdateDeleteResult()
 128         * @see                  Tizen::App::DataControlProviderManager::SendDataControlError()
 129         */
 130         result SendSqlDataControlSelectResult(RequestId reqId, Tizen::Io::IDbEnumerator* pDbEnum);
 131
 132         /**
 133         * Sends the success result of the INSERT request and the last inserted row ID to the application requesting for
 134         * the SQL-friendly interface based data control. @n
 135         * The data control provider must call the %SendSqlDataControlInsertResult() method to notify success to the requesting application.
 136         * The application requesting the data control can get the success result and the last inserted row ID
 137         * by implementing Tizen::App::ISqlDataControlResponseListener.
 138         *
 139         * @since        2.0
 140         *
 141         * @return               An error code
 142         * @param[in]    reqId                           The request ID
 143         * @param[in]    insertRowId                     The row ID of the database changed by the INSERT request
 144         * @exception    E_SUCCESS                       The method is successful.
 145         * @exception    E_INVALID_ARG           The result for the specified @c reqId of the SELECT, UPDATE, or DELETE request cannot be sent.
 146         * @exception    E_OBJ_NOT_FOUND         The data control request specified by the @c reqId does not exist.
 147         * @exception    E_SYSTEM                        The method cannot proceed due to a severe system error.
 148         * @see                  Tizen::App::DataControlProviderManager::SendSqlDataControlSelectResult()
 149         * @see                  Tizen::App::DataControlProviderManager::SendSqlDataControlUpdateDeleteResult()
 150         * @see                  Tizen::App::DataControlProviderManager::SendDataControlError()
 151         * @see                  Tizen::Io::Database::GetLastInsertRowId()
 152         */
 153         result SendSqlDataControlInsertResult(RequestId reqId, long long insertRowId);
 154
 155         /**
 156         * Sends the success result of the UPDATE or DELETE request to the application requesting for the SQL-friendly interface based data control. @n
 157         * The data control provider must call the %SendSqlDataControlUpdateDeleteResult() method to notify success to the requesting application.
 158         * The application requesting the data control can get the success result by implementing Tizen::App::ISqlDataControlResponseListener.
 159         *
 160         * @since        2.0
 161         *
 162         * @return               An error code
 163         * @param[in]    reqId                           The request ID
 164         * @exception    E_SUCCESS                       The method is successful.
 165         * @exception    E_INVALID_ARG           The result for the specified @c reqId of the SELECT or INSERT request cannot be sent.
 166         * @exception    E_OBJ_NOT_FOUND         The data control request specified by the @c reqId does not exist.
 167         * @exception    E_SYSTEM                        The method cannot proceed due to a severe system error.
 168         * @see                  Tizen::App::DataControlProviderManager::SendSqlDataControlSelectResult()
 169         * @see                  Tizen::App::DataControlProviderManager::SendSqlDataControlInsertResult()
 170         * @see                  Tizen::App::DataControlProviderManager::SendDataControlError()
 171         * @see                  Tizen::App::ISqlDataControlProviderEventListener
 172         */
 173         result SendSqlDataControlUpdateDeleteResult(RequestId reqId);
 174
 175         /**
 176         * Sends the success result and the result list of the provider to the application requesting for the key-value structured
 177         * data control. @n
 178         * The data control provider must call the %SendMapDataControlResult() method to notify success to the requesting application.
 179         * The application requesting the data control can get the success result and the result set
 180         * by implementing Tizen::App::IMapDataControlResponseListener.
 181         *
 182         * @since        2.0
 183         *
 184         * @return               An error code
 185         * @param[in]    reqId                           The request ID
 186         * @param[in]    pResultValueList        The result list to request @n
 187         *                                                                       The type of objects contained in the specified @c pResultValueList must be
 188         *                                                                       Tizen::Base::String.
 189         * @exception    E_SUCCESS                       The method is successful.
 190         * @exception    E_INVALID_ARG           Either of the following conditions has occurred:
 191         *                                                               - The specified @c pResultValueList must be @c null if the request is an
 192         *                                                               AddValue(), SetValue(), or RemoveValue() query.
 193         *                                                               - The specified @c pResultValueList must not be @c null if the request is
 194         *                                                               a GetValue() query.
 195         * @exception    E_OBJ_NOT_FOUND         The data control request specified by the @c reqId does not exist.
 196         * @exception    E_MAX_EXCEEDED          The size of the sending buffer has exceeded the maximum limit.
 197         * @exception    E_SYSTEM                        The method cannot proceed due to a severe system error.
 198         * @see                  Tizen::App::DataControlProviderManager::SendDataControlError()
 199         */
 200         result SendMapDataControlResult(RequestId reqId, Tizen::Base::Collection::IList* pResultValueList = null);
 201
 202         /**
 203         * Sends the provider error message to the application requesting for the data control. @n
 204         * The data control provider must call the %SendDataControlError() method to notify failure to the requesting application.
 205         * The application requesting the data control can get the failure result and the error message
 206         * by implementing Tizen::App::ISqlDataControlResponseListener.
 207         *
 208         * @since        2.0
 209         *
 210         * @return               An error code
 211         * @param[in]    reqId                           The request ID
 212         * @param[in]    errorMsg                        The provider-defined error message
 213         * @exception    E_SUCCESS                       The method is successful.
 214         * @exception    E_OBJ_NOT_FOUND         The data control request specified by the @c reqId does not exist.
 215         * @exception    E_MAX_EXCEEDED          The size of the sending buffer has exceeded the maximum limit.
 216         * @exception    E_SYSTEM                        The method cannot proceed due to a severe system error.
 217         * @remarks      The recommended data size is under 16KB because a severe system performance degradation may occur for larger messages. @n
 218         *                       @c E_MAX_EXCEEDED may be returned for messages over 16KB size.
 219         * @see                  Tizen::App::DataControlProviderManager::SendSqlDataControlSelectResult()
 220         * @see                  Tizen::App::DataControlProviderManager::SendSqlDataControlInsertResult()
 221         * @see                  Tizen::App::DataControlProviderManager::SendSqlDataControlUpdateDeleteResult()
 222         * @see                  Tizen::App::DataControlProviderManager::SendMapDataControlResult()
 223         * @see                  Tizen::App::IMapDataControlProviderEventListener
 224         */
 225         result SendDataControlError(RequestId reqId, const Tizen::Base::String& errorMsg);
 226
 227         /**
 228         * Gets a pointer to the %DataControlProviderManager instance.
 229         *
 230         * @since        2.0
 231         *
 232         * @return       A pointer to the %DataControlProviderManager instance, @n
 233         *                       else @c null if it fails
 234         */
 235         static DataControlProviderManager* GetInstance(void);
 236
 237 private:
 238         /**
 239          * This default constructor is intentionally declared as private to implement the %Singleton semantic.
 240          *
 241          * @since       2.0
 242          */
 243         DataControlProviderManager(void);
 244
 245         /**
 246          * This destructor is intentionally declared as private to implement the %Singleton semantic.
 247          *
 248          * @since       2.0
 249          */
 250         virtual ~DataControlProviderManager(void);
 251
 252         /**
 253          * The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
 254          *
 255          * @since       2.0
 256          */
 257         DataControlProviderManager(const DataControlProviderManager& rhs);
 258
 259         /**
 260          * The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
 261          *
 262          * @since       2.0
 263          */
 264         DataControlProviderManager& operator =(const DataControlProviderManager& rhs);
 265
 266 private:
 267         class _DataControlProviderManagerImpl* __pDataControlProviderManagerImpl;
 268
 269         friend class _DataControlProviderManagerImpl;
 270
 271 }; // DataControlProviderManager
 272
 273 }} // Tizen::App
 274
 275 #endif // _FAPP_DATA_CONTROL_PROVIDER_MANAGER_H_
 276