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