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 message 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 to the data control provider manager. @n
  66         * The listener gets notified when a data control request is received from the 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 must be 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 in App::OnAppInitializing() 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 to the data control provider manager. @n
  85         * The listener gets notified when a data control request is received from the 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 must be 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 in App::OnAppInitializing() 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 SELECT request to the application requesting 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         *                                                                       - This method cannot send result for the specified @c reqId of INSERT, UPDATE, or DELETE requests.
 117         *                                                                       - 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 with the @c reqId does not exist.
 119         * @exception    E_OBJECT_LOCKED         The database instance associated to the specified @c pDbEnum is locked.
 120         * @exception    E_INVALID_FORMAT        The database file associated to the specified @c pDbEnum is malformed.
 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 is detected.
 124         * @exception    E_MAX_EXCEEDED          The size of 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         * @see                  Tizen::App::ISqlDataControlProviderEventListener
 130         */
 131         result SendSqlDataControlSelectResult(RequestId reqId, Tizen::Io::IDbEnumerator* pDbEnum);
 132
 133         /**
 134         * Sends the success result of INSERT request and the last inserted row ID to the application requesting
 135         * the SQL-friendly interface based data control. @n
 136         * The data control provider must call the %SendSqlDataControlInsertResult() method to notify success to the requesting application.
 137         * The application requesting the data control can get the success result and the last inserted row ID
 138         * by implementing Tizen::App::ISqlDataControlResponseListener.
 139         *
 140         * @since        2.0
 141         *
 142         * @return               An error code
 143         * @param[in]    reqId                           The request ID
 144         * @param[in]    insertRowId                     The row ID of database changed by INSERT request
 145         * @exception    E_SUCCESS                       The method is successful.
 146         * @exception    E_INVALID_ARG           This method cannot send result for the specified @c reqId of SELECT, UPDATE, or DELETE request.
 147         * @exception    E_OBJ_NOT_FOUND         The data control request specified with the @c reqId does not exist.
 148         * @exception    E_SYSTEM                        The method cannot proceed due to a severe system error.
 149         * @see                  Tizen::App::DataControlProviderManager::SendSqlDataControlSelectResult()
 150         * @see                  Tizen::App::DataControlProviderManager::SendSqlDataControlUpdateDeleteResult()
 151         * @see                  Tizen::App::DataControlProviderManager::SendDataControlError()
 152         * @see                  Tizen::App::ISqlDataControlProviderEventListener
 153         * @see                  Tizen::Io::Database::GetLastInsertRowId()
 154         */
 155         result SendSqlDataControlInsertResult(RequestId reqId, long long insertRowId);
 156
 157         /**
 158         * Sends the success result of UPDATE / DELETE request to the application requesting the SQL-friendly interface based data control. @n
 159         * The data control provider must call the %SendSqlDataControlUpdateDeleteResult() method to notify success to the requesting application.
 160         * The application requesting the data control can get the success result by implementing Tizen::App::ISqlDataControlResponseListener.
 161         *
 162         * @since        2.0
 163         *
 164         * @return               An error code
 165         * @param[in]    reqId                           The request ID
 166         * @exception    E_SUCCESS                       The method is successful.
 167         * @exception    E_INVALID_ARG           This method cannot send result for the specified @c reqId of SELECT or INSERT request.
 168         * @exception    E_OBJ_NOT_FOUND         The data control request specified with the @c reqId does not exist.
 169         * @exception    E_SYSTEM                        The method cannot proceed due to a severe system error.
 170         * @see                  Tizen::App::DataControlProviderManager::SendSqlDataControlSelectResult()
 171         * @see                  Tizen::App::DataControlProviderManager::SendSqlDataControlInsertResult()
 172         * @see                  Tizen::App::DataControlProviderManager::SendDataControlError()
 173         * @see                  Tizen::App::ISqlDataControlProviderEventListener
 174         */
 175         result SendSqlDataControlUpdateDeleteResult(RequestId reqId);
 176
 177         /**
 178         * Sends the success result and the result list of the provider to the application requesting the key-value structured
 179         * data control. @n
 180         * The data control provider must call the %SendMapDataControlResult() method to notify success to the requesting application.
 181         * The application requesting the data control can get the success result and the result set
 182         * by implementing Tizen::App::IMapDataControlResponseListener.
 183         *
 184         * @since        2.0
 185         *
 186         * @return               An error code
 187         * @param[in]    reqId                           The request ID
 188         * @param[in]    pResultValueList        The result list to request @n
 189         *                                                                       The type of objects contained in the specified @c pResultValueList must be
 190         *                                                                       Tizen::Base::String class.
 191         * @exception    E_SUCCESS                       The method is successful.
 192         * @exception    E_INVALID_ARG           Either of the following conditions has occurred:
 193         *                                                                       - The specified @c pResultValueList must be @c null if the request is one of
 194         *                                                                         AddValue, SetValue, RemoveValue queries.
 195         *                                                                       - The specified @c pResultValueList must not be @c null if the request is
 196         *                                                                         GetValue() query.
 197         * @exception    E_OBJ_NOT_FOUND         The data control request specified with the @c reqId does not exist.
 198         * @exception    E_MAX_EXCEEDED          The size of sending buffer has exceeded the maximum limit.
 199         * @exception    E_SYSTEM                        The method cannot proceed due to a severe system error.
 200         * @see                  Tizen::App::DataControlProviderManager::SendDataControlError()
 201         * @see                  Tizen::App::IMapDataControlProviderEventListener
 202         */
 203         result SendMapDataControlResult(RequestId reqId, Tizen::Base::Collection::IList* pResultValueList = null);
 204
 205         /**
 206         * Sends the provider error message to the application requesting the data control. @n
 207         * The data control provider must call the %SendDataControlError() method to notify failure to the requesting application.
 208         * The application requesting the data control can get the failure result and the error message
 209         * by implementing Tizen::App::ISqlDataControlResponseListener.
 210         *
 211         * @since        2.0
 212         *
 213         * @return               An error code
 214         * @param[in]    reqId                           The request ID
 215         * @param[in]    errorMsg                        The provider-defined error message
 216         * @exception    E_SUCCESS                       The method is successful.
 217         * @exception    E_OBJ_NOT_FOUND         The data control request specified with the @c reqId does not exist.
 218         * @exception    E_MAX_EXCEEDED          The size of sending buffer has exceeded the maximum limit.
 219         * @exception    E_SYSTEM                        The method cannot proceed due to a severe system error.
 220         * @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.
 221         * @see                  Tizen::App::DataControlProviderManager::SendSqlDataControlSelectResult()
 222         * @see                  Tizen::App::DataControlProviderManager::SendSqlDataControlInsertResult()
 223         * @see                  Tizen::App::DataControlProviderManager::SendSqlDataControlUpdateDeleteResult()
 224         * @see                  Tizen::App::DataControlProviderManager::SendMapDataControlResult()
 225         * @see                  Tizen::App::ISqlDataControlProviderEventListener
 226         * @see                  Tizen::App::IMapDataControlProviderEventListener
 227         */
 228         result SendDataControlError(RequestId reqId, const Tizen::Base::String& errorMsg);
 229
 230         /**
 231         * Gets the data control provider manager instance.
 232         *
 233         * @since        2.0
 234         *
 235         * @return       A pointer to the %DataControlProviderManager instance if it succeeds, @n
 236         *                       else @c null
 237         */
 238         static DataControlProviderManager* GetInstance(void);
 239
 240 private:
 241         /**
 242          * This default constructor is intentionally declared as private to implement the %Singleton semantic.
 243          *
 244          * @since       2.0
 245          */
 246         DataControlProviderManager(void);
 247
 248         /**
 249          * This destructor is intentionally declared as private to implement the %Singleton semantic.
 250          *
 251          * @since       2.0
 252          */
 253         virtual ~DataControlProviderManager(void);
 254
 255         /**
 256          * The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
 257          *
 258          * @since       2.0
 259          */
 260         DataControlProviderManager(const DataControlProviderManager& rhs);
 261
 262         /**
 263          * The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
 264          *
 265          * @since       2.0
 266          */
 267         DataControlProviderManager& operator =(const DataControlProviderManager& rhs);
 268
 269 private:
 270         class _DataControlProviderManagerImpl* __pDataControlProviderManagerImpl;
 271
 272         friend class _DataControlProviderManagerImpl;
 273
 274 }; // DataControlProviderManager
 275
 276 }} // Tizen::App
 277
 278 #endif // _FAPP_DATA_CONTROL_PROVIDER_MANAGER_H_
 279