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 FAppSqlDataControl.h
19 * @brief This is the header file for the %SqlDataControl class.
21 * This header file contains the declarations of the %SqlDataControl class.
24 #ifndef _FAPP_SQL_DATA_CONTROL_H_
25 #define _FAPP_SQL_DATA_CONTROL_H_
27 #include <FOspConfig.h>
28 #include <FBaseDataType.h>
29 #include <FBaseObject.h>
31 namespace Tizen { namespace Base
34 namespace Collection {
40 namespace Tizen { namespace App
43 class _SqlDataControlImpl;
44 class ISqlDataControlResponseListener;
47 * @class SqlDataControl
48 * @brief This class represents the SQL-friendly interface based data control's behavior.
52 * @final This class is not intended for extension.
54 * The %SqlDataControl class represents the data control's behavior that provides a standard mechanism
55 * for accessing the specific data exported by other applications.
56 * A data control provider can share its data with data control consumers.
58 * For more information on the class features, see <a href="../org.tizen.native.appprogramming/html/guide/app/data_controls.htm">Data Controls</a>.
60 * @see Tizen::App::AppManager
67 * using namespace Tizen::Base;
68 * using namespace Tizen::Io;
70 * class MySqlDataControlResponseListener:
71 * : public Tizen::App::ISqlDataControlResponseListener
74 * void OnSqlDataControlInsertResponseReceived(RequestId reqId, const String& providerId, const String& dataId, long long insertRowId, bool providerResult, const String* pErrorMsg)
76 * AppLog("Row Id = %d", insertRowId);
81 * MyClass::Execute(void)
83 * String providerId(L"http://tizen.org/datacontrol/provider/example");
84 * SqlDataControl* pDc = AppManager::GetSqlDataControlN(providerId);
86 * MySqlDataControlResponseListener* pResponseListener = new MySqlDataControlResponseListener();
88 * pDc->SetSqlDataControlResponseListener(pResponseListener);
90 * String dataId(L"test");
91 * String person(L"person");
92 * String number(L"number");
95 * ArrayList columnList(SingleObjectDeleter);
96 * columnList.Construct();
98 * columnList.Add(person);
99 * columnList.Add(number);
101 * String where(L"group = 'friend'");
102 * String order(L"person ASC");
104 * pDc->Select(dataId, &columnList, &where, &order, reqId);
111 class _OSP_EXPORT_ SqlDataControl
112 : public Tizen::Base::Object
117 * This destructor overrides Tizen::Base::Object::~Object().
121 virtual ~SqlDataControl(void);
124 * Selects the specified columns to be queried. @n
125 * The result set of the specified columns is retrieved from a table owned by the SQL-friendly interface based data control provider. @n
126 * The %Select() method is asynchronous.
127 * For receiving the response from the data control provider, set the listener using
128 * the SqlDataControl::SetSqlDataControlResponseListener() method. @n
129 * When the requested result set has been received from the data control provider,
130 * the ISqlDataControlResponseListener::OnSqlDataControlSelectResponseReceived() method is called.
134 * @privilege %http://tizen.org/privilege/datacontrol.consumer
136 * @return An error code
137 * @param[in] dataId The string that identifies the specific data, usually a database table to query from @n
138 * The string consists of one or more components, separated by a slash('/').
139 * @param[in] pColumnList The list of column names to query @n
140 * The type of objects contained in the specified @c pColumnList must be
141 * Tizen::Base::String @n
142 * If the specified @c pColumnList is @c null, all the columns are selected.
143 * @param[in] pWhere The filter to select the desired rows to query @n
144 * It is an SQL 'WHERE' clause excluding the 'WHERE' itself such as
145 * column1 = 'stringValue' AND column2 = numericValue @n
146 * If the value is a string, the value must be wrapped in single quotes,
147 * otherwise it need not be wrapped in single quotes @n
148 * For more information on the SQL statement, see SQLite SQL documents.
149 * @param[in] pOrder The sorting order of the rows to query @n
150 * It is an SQL 'ORDER BY' clause excluding the 'ORDER BY' itself.
151 * @param[out] reqId The request ID
152 * @param[in] pageNo The page number of the result set @n
153 * It starts from @c 1.
154 * @param[in] countPerPage The desired maximum count of the rows per page
155 * @exception E_SUCCESS The method is successful.
156 * @exception E_INVALID_STATE This instance has not been constructed properly.
157 * @exception E_INVALID_ARG Either of the following conditions has occurred:
158 * - The specified @c pColumnList is empty.
159 * - The specified @c pageNo is less than @c 1.
160 * - The specified @c countPerPage is less than @c 1.
161 * @exception E_ILLEGAL_ACCESS Either of the following conditions has occurred:
162 * - The access is denied due to insufficient permission.
163 * - The application using this method is not signed with the same certificate as that of the provider application. @b Since: @b 2.1
164 * @exception E_MAX_EXCEEDED Either of the following conditions has occurred:
165 * - The size of the sending buffer has exceeded the maximum limit.
166 * - The number of sending requests have exceeded the maximum limit.
167 * @exception E_PRIVILEGE_DENIED The application does not have the privilege to call this method.
168 * @exception E_SYSTEM A system error has occurred.
169 * @remarks The recommended data size is under 16KB because a severe system performance degradation may occur for larger messages. @n
170 * @c E_MAX_EXCEEDED may be returned for messages over 16KB.
172 result Select(const Tizen::Base::String& dataId, const Tizen::Base::Collection::IList* pColumnList,
173 const Tizen::Base::String* pWhere, const Tizen::Base::String *pOrder, RequestId& reqId,
174 int pageNo = 1, int countPerPage = 20);
177 * Inserts new rows into a table owned by the SQL-friendly interface based data control provider. @n
178 * The %Insert() method is asynchronous.
179 * For receiving the response from the data control provider, set the listener using
180 * the SqlDataControl::SetSqlDataControlResponseListener() method. @n
181 * When the response has been received from the data control provider,
182 * the ISqlDataControlResponseListener::OnSqlDataControlInsertResponseReceived() method is called.
186 * @privilege %http://tizen.org/privilege/datacontrol.consumer
188 * @return An error code
189 * @param[in] dataId The string that identifies the specific data, usually a database table to insert into @n
190 * The string consists of one or more components, separated by a slash('/').
191 * @param[in] insertMap The column-value pairs to insert @n
192 * The type of objects must be Tizen::Base::String @n
193 * If the value is a string, the value must be wrapped in single quotes,
194 * else it need not be wrapped in single quotes @n
195 * For more information on the SQL statement, see SQLite SQL documents.
196 * @param[out] reqId The request ID
197 * @exception E_SUCCESS The method is successful.
198 * @exception E_INVALID_STATE This instance has not been constructed properly.
199 * @exception E_INVALID_ARG The specified @c insertMap is empty.
200 * @exception E_ILLEGAL_ACCESS Either of the following conditions has occurred:
201 * - The access is denied due to insufficient permission.
202 * - The application using this method is not signed with the same certificate as that of the provider application. @b Since: @b 2.1
203 * @exception E_MAX_EXCEEDED Either of the following conditions has occurred:
204 * - The size of the sending buffer has exceeded the maximum limit.
205 * - The number of sending requests have exceeded the maximum limit.
206 * @exception E_PRIVILEGE_DENIED The application does not have the privilege to call this method.
207 * @exception E_SYSTEM A system error has occurred.
208 * @remarks The recommended data size is under 1MB because a severe system performance degradation may occur for larger messages. @n
209 * @c E_MAX_EXCEEDED may be returned for messages over 1MB.
211 result Insert(const Tizen::Base::String& dataId, const Tizen::Base::Collection::IMap& insertMap, RequestId& reqId);
214 * Updates values of a table owned by the SQL-friendly interface based data control provider. @n
215 * The %Update() method is asynchronous.
216 * For receiving the response from the data control provider, set the listener using
217 * the SqlDataControl::SetSqlDataControlResponseListener() method. @n
218 * When the response has been received from the data control provider,
219 * the ISqlDataControlResponseListener::OnSqlDataControlUpdateResponseReceived() method is called.
223 * @privilege %http://tizen.org/privilege/datacontrol.consumer
225 * @return An error code
226 * @param[in] dataId The string that identifies the specific data, usually a database table to update @n
227 * The string consists of one or more components, separated by a slash('/').
228 * @param[in] updateMap The column-value pairs to update @n
229 * The type of objects must be Tizen::Base::String @n
230 * If the value is a string, the value must be wrapped in single quotes,
231 * else it need not be wrapped in single quotes @n
232 * For more information on the SQL statement, see SQLITE SQL documents.
233 * @param[in] pWhere The filter to select the desired rows to update @n
234 * It is an SQL 'WHERE' clause excluding the 'WHERE' itself such as
235 * column1 = 'stringValue' AND column2 = numericValue @n
236 * If the value is a string, the value must be wrapped in single quotes,
237 * else it is not wrapped in single quotes @n
238 * For more information on the SQL statement, see SQLITE SQL documents.
239 * @param[out] reqId The request ID
240 * @exception E_SUCCESS The method is successful.
241 * @exception E_INVALID_STATE This instance has not been constructed properly.
242 * @exception E_INVALID_ARG The specified @c updateMap is empty.
243 * @exception E_ILLEGAL_ACCESS Either of the following conditions has occurred:
244 * - The access is denied due to insufficient permission.
245 * - The application using this method is not signed with the same certificate as that of the provider application. @b Since: @b 2.1
246 * @exception E_MAX_EXCEEDED Either of the following conditions has occurred:
247 * - The size of the sending buffer has exceeded the maximum limit.
248 * - The number of sending requests have exceeded the maximum limit.
249 * @exception E_PRIVILEGE_DENIED The application does not have the privilege to call this method.
250 * @exception E_SYSTEM A system error has occurred.
251 * @remarks The recommended data size is under 1MB because a severe system performance degradation may occur for larger messages. @n
252 * @c E_MAX_EXCEEDED may be returned for messages over 1MB.
254 result Update(const Tizen::Base::String& dataId, const Tizen::Base::Collection::IMap& updateMap,
255 const Tizen::Base::String* pWhere, RequestId& reqId);
258 * Deletes rows of a table owned by the SQL-friendly interface based data control provider. @n
259 * The %Delete() method is asynchronous.
260 * For receiving the response from the data control provider, set the listener using
261 * the SqlDataControl::SetSqlDataControlResponseListener() method. @n
262 * When the response has been received from the data control provider,
263 * the ISqlDataControlResponseListener::OnSqlDataControlDeleteResponseReceived() method is called.
267 * @privilege %http://tizen.org/privilege/datacontrol.consumer
269 * @return An error code
270 * @param[in] dataId The string that identifies the specific data, usually a database table to delete from @n
271 * The string consists of one or more components, separated by a slash('/').
272 * @param[in] pWhere The filter to select the desired rows to delete @n
273 * It is an SQL 'WHERE' clause excluding the 'WHERE' itself such as
274 * column1 = 'stringValue' AND column2 = numericValue @n
275 * If it is @c null, all the rows are deleted @n
276 * If the value is a string, the value must be wrapped in single quotes,
277 * else it need not be wrapped in single quotes @n
278 * For more information on the SQL statement, see SQLITE SQL documents.
279 * @param[out] reqId The request ID
280 * @exception E_SUCCESS The method is successful.
281 * @exception E_INVALID_STATE This instance has not been constructed properly.
282 * @exception E_INVALID_ARG A specified input parameter is invalid.
283 * @exception E_ILLEGAL_ACCESS Either of the following conditions has occurred:
284 * - The access is denied due to insufficient permission.
285 * - The application using this method is not signed with the same certificate as that of the provider application. @b Since: @b 2.1
286 * @exception E_MAX_EXCEEDED Either of the following conditions has occurred:
287 * - The size of the sending buffer has exceeded the maximum limit.
288 * - The number of sending requests have exceeded the maximum limit.
289 * @exception E_PRIVILEGE_DENIED The application does not have the privilege to call this method.
290 * @exception E_SYSTEM A system error has occurred.
291 * @remarks The recommended data size is under 16KB because a severe system performance degradation may occur for larger messages. @n
292 * @c E_MAX_EXCEEDED may be returned for messages over 16KB.
294 result Delete(const Tizen::Base::String& dataId, const Tizen::Base::String* pWhere, RequestId& reqId);
297 * Sets an SQL-friendly interface based data control listener to this instance.
301 * @return An error code
302 * @param[in] pListener The data control callback listener @n
303 * Some data controls get the callback result by implementing
304 * the ISqlDataControlResponseListener interface.
305 * @exception E_SUCCESS The method is successful.
306 * @exception E_INVALID_STATE This instance has not been constructed properly.
307 * @exception E_SYSTEM A system error has occurred.
309 result SetSqlDataControlResponseListener(ISqlDataControlResponseListener* pListener);
313 * This default constructor is intentionally declared as private so that only the platform can create an instance.
317 SqlDataControl(void);
320 * The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
323 * @remarks This constructor is hidden.
325 SqlDataControl(const SqlDataControl& rhs);
328 * The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
331 * @remarks This operator is hidden.
333 SqlDataControl& operator =(const SqlDataControl& rhs);
335 class _SqlDataControlImpl* __pSqlDataControlImpl;
337 friend class _SqlDataControlImpl;
343 #endif // _FAPP_SQL_DATA_CONTROL_H_