Merge "Modify Scanner class" into tizen_2.1
[platform/framework/native/appfw.git] / 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