2 // Copyright (c) 2012 Samsung Electronics Co., Ltd.
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
8 // http://www.apache.org/licenses/LICENSE-2.0
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.
18 * @file FAppDataControlProviderManager.h
19 * @brief This is the header file for the %DataControlProviderManager class.
21 * This header file contains the declarations of the %DataControlProviderManager class.
24 #ifndef _FAPP_DATA_CONTROL_PROVIDER_MANAGER_H_
25 #define _FAPP_DATA_CONTROL_PROVIDER_MANAGER_H_
27 #include <FBaseDataType.h>
28 #include <FBaseObject.h>
29 #include <FBaseColIList.h>
30 #include <FIoIDbEnumerator.h>
32 namespace Tizen { namespace Base
37 namespace Tizen { namespace Io
40 class DataControlResultSet;
43 namespace Tizen { namespace App
46 class ISqlDataControlProviderEventListener;
47 class IMapDataControlProviderEventListener;
50 * @class DataControlProviderManager
51 * @brief This class manages the data control provider.
55 * @final This class is not intended for extension.
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.
59 class _OSP_EXPORT_ DataControlProviderManager
60 : public Tizen::Base::Object
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.
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.
81 result SetSqlDataControlProviderEventListener(ISqlDataControlProviderEventListener* pListener);
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.
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.
100 result SetMapDataControlProviderEventListener(IMapDataControlProviderEventListener* pListener);
103 * Sends the success result and the result set of the SELECT request to the application requesting for the SQL-friendly interface based
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.
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()
130 result SendSqlDataControlSelectResult(RequestId reqId, Tizen::Io::IDbEnumerator* pDbEnum);
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.
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()
153 result SendSqlDataControlInsertResult(RequestId reqId, long long insertRowId);
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.
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
173 result SendSqlDataControlUpdateDeleteResult(RequestId reqId);
176 * Sends the success result and the result list of the provider to the application requesting for the key-value structured
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.
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()
200 result SendMapDataControlResult(RequestId reqId, Tizen::Base::Collection::IList* pResultValueList = null);
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.
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
225 result SendDataControlError(RequestId reqId, const Tizen::Base::String& errorMsg);
228 * Gets a pointer to the %DataControlProviderManager instance.
232 * @return A pointer to the %DataControlProviderManager instance, @n
233 * else @c null if it fails
235 static DataControlProviderManager* GetInstance(void);
239 * This default constructor is intentionally declared as private to implement the %Singleton semantic.
243 DataControlProviderManager(void);
246 * This destructor is intentionally declared as private to implement the %Singleton semantic.
250 virtual ~DataControlProviderManager(void);
253 * The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
257 DataControlProviderManager(const DataControlProviderManager& rhs);
260 * The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
264 DataControlProviderManager& operator =(const DataControlProviderManager& rhs);
267 class _DataControlProviderManagerImpl* __pDataControlProviderManagerImpl;
269 friend class _DataControlProviderManagerImpl;
271 }; // DataControlProviderManager
275 #endif // _FAPP_DATA_CONTROL_PROVIDER_MANAGER_H_