inc/FAppDataControlProviderManager.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        FAppDataControlProviderManager.h
  20  * @brief       This is the header file for the %DataControlProviderManager class.
  21  *
  22  * This header file contains the declarations of the %DataControlProviderManager class.
  23  */
  24
  25 #ifndef _FAPP_DATA_CONTROL_PROVIDER_MANAGER_H_
  26 #define _FAPP_DATA_CONTROL_PROVIDER_MANAGER_H_
  27
  28 #include <FBaseDataType.h>
  29 #include <FBaseObject.h>
  30 #include <FBaseColIList.h>
  31 #include <FIoIDbEnumerator.h>
  32
  33 namespace Tizen { namespace Base
  34 {
  35 class String;
  36 class ByteBuffer;
  37 }}
  38 namespace Tizen { namespace Io
  39 {
  40 class DbEnumerator;
  41 class DataControlResultSet;
  42 }}
  43
  44 namespace Tizen { namespace App
  45 {
  46
  47 class ISqlDataControlProviderEventListener;
  48 class IMapDataControlProviderEventListener;
  49
  50 /**
  51  * @class       DataControlProviderManager
  52  * @brief       This class manages the data control provider.
  53  *
  54  * @since       2.0
  55  *
  56  * @final       This class is not intended for extension.
  57  *
  58  * The %DataControlProviderManager class manages the data control provider.
  59  */
  60 class _OSP_EXPORT_ DataControlProviderManager
  61         : public Tizen::Base::Object
  62 {
  63
  64 public:
  65         /**
  66         * Sets a SQL-type data control provider listener to the data control provider manager. @n
  67         * The listener gets notified when a data control request is received from the other applications.
  68         * To unset the listener, pass a @c null value to the listener parameter.
  69         *
  70         * @since        2.0
  71         *
  72         * @return               An error code
  73         * @param[in]    pListener                       The SQL-type data control provider listener @n
  74         *                                                                       The listener must implement the ISqlDataControlProviderEventListener interface.
  75         * @exception    E_SUCCESS                       The method is successful.
  76         * @exception    E_INVALID_STATE         This instance has not been properly constructed.
  77         * @exception    E_INVALID_OPERATION     The listener must be set for a service application.
  78         * @exception    E_SYSTEM                        The method cannot proceed due to a severe system error.
  79         * @remarks              This method must be called in App::OnAppInitializing() for setting the data control provider listener
  80         *                               before receiving the data control request.
  81         */
  82         result SetSqlDataControlProviderEventListener(ISqlDataControlProviderEventListener* pListener);
  83
  84         /**
  85         * Sets a MAP-type data control provider listener to the data control provider manager. @n
  86         * The listener gets notified when a data control request is received from the other applications.
  87         * To unset the listener, pass a @c null value to the listener parameter.
  88         *
  89         * @since        2.0
  90         *
  91         * @return               An error code
  92         * @param[in]    pListener                       The MAP-type data control provider listener @n
  93         *                                                                       The listener must implement the IMapDataControlProviderEventListener interface.
  94         * @exception    E_SUCCESS                       The method is successful.
  95         * @exception    E_INVALID_STATE         This instance has not been properly constructed.
  96         * @exception    E_INVALID_OPERATION     The listener must be set for a service application.
  97         * @exception    E_SYSTEM                        The method cannot proceed due to a severe system error.
  98         * @remarks              This method must be called in App::OnAppInitializing() for setting the data control provider listener
  99         *                               before receiving the data control request.
 100         */
 101         result SetMapDataControlProviderEventListener(IMapDataControlProviderEventListener* pListener);
 102
 103         /**
 104         * Sends the success result and the result set of SELECT request to the application requesting the SQL-type
 105         * data control. @n
 106         * The data control provider must call the %SendSqlDataControlSelectResult() method to notify success to the requesting application.
 107         * The application requesting the data control can get the success result and the result set
 108         * by implementing Tizen::App::ISqlDataControlResponseListener.
 109         *
 110         * @since        2.0
 111         *
 112         * @return               An error code
 113         * @param[in]    reqId                           The request ID
 114         * @param[in]    pDbEnum                         The Tizen::Io::DbEnumerator instance to obtain the result set
 115         * @exception    E_SUCCESS                       The method is successful.
 116         * @exception    E_INVALID_ARG           Either of the following conditions has occurred:
 117         *                                                                       - This method cannot send result for the specified @c reqId of INSERT, UPDATE, or DELETE requests.
 118         *                                                                       - Tizen::Io::Database or Tizen::Io::DbStatement instance associated with the specified @c pDbEnum is deleted.
 119         * @exception    E_OBJ_NOT_FOUND         The data control request specified with the @c reqId did not exist.
 120         * @exception    E_OBJECT_LOCKED         The database instance associated to the specified @c pDbEnum is locked.
 121         * @exception    E_INVALID_FORMAT        The database file associated to the specified @c pDbEnum is malformed.
 122         * @exception    E_IO                            Either of the following conditions has occurred:
 123         *                                                                       - An unexpected device failure has occurred as the media ejected suddenly.
 124         *                                                                       - %File corruption is detected.
 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-type 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 did 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-type 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 did 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 MAP-type
 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_OUT_OF_MEMORY         The memory is insufficient.
 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 did not exist.
 218         * @exception    E_OUT_OF_MEMORY         The memory is insufficient.
 219         * @exception    E_SYSTEM                        The method cannot proceed due to a severe system error.
 220         * @see                  Tizen::App::DataControlProviderManager::SendSqlDataControlSelectResult()
 221         * @see                  Tizen::App::DataControlProviderManager::SendSqlDataControlInsertResult()
 222         * @see                  Tizen::App::DataControlProviderManager::SendSqlDataControlUpdateDeleteResult()
 223         * @see                  Tizen::App::DataControlProviderManager::SendMapDataControlResult()
 224         * @see                  Tizen::App::ISqlDataControlProviderEventListener
 225         * @see                  Tizen::App::IMapDataControlProviderEventListener
 226         */
 227         result SendDataControlError(RequestId reqId, const Tizen::Base::String& errorMsg);
 228
 229         /**
 230         * Gets the data control provider manager instance.
 231         *
 232         * @since        2.0
 233         *
 234         * @return       A pointer to the %DataControlProviderManager instance if it succeeds, @n
 235         *                       else @c null
 236         */
 237         static DataControlProviderManager* GetInstance(void);
 238
 239 private:
 240         /**
 241          * This default constructor is intentionally declared as private to implement the %Singleton semantic.
 242          *
 243          * @since       2.0
 244          */
 245         DataControlProviderManager(void);
 246
 247         /**
 248          * This destructor is intentionally declared as private to implement the %Singleton semantic.
 249          *
 250          * @since       2.0
 251          */
 252         virtual ~DataControlProviderManager(void);
 253
 254         /**
 255          * The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
 256          *
 257          * @since       2.0
 258          */
 259         DataControlProviderManager(const DataControlProviderManager& rhs);
 260
 261         /**
 262          * The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
 263          *
 264          * @since       2.0
 265          */
 266         DataControlProviderManager& operator =(const DataControlProviderManager& rhs);
 267
 268 private:
 269         class _DataControlProviderManagerImpl* __pDataControlProviderManagerImpl;
 270
 271         friend class _DataControlProviderManagerImpl;
 272
 273 }; // DataControlProviderManager
 274
 275 }} // Tizen::App
 276
 277 #endif // _FAPP_DATA_CONTROL_PROVIDER_MANAGER_H_
 278