2 // Open Service Platform
3 // Copyright (c) 2012 Samsung Electronics Co., Ltd.
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
9 // http://www.apache.org/licenses/LICENSE-2.0
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.
19 * @file FAppSqlDataControl.h
20 * @brief This is the header file for the %SqlDataControl class.
22 * This header file contains the declarations of the %SqlDataControl class.
25 #ifndef _FAPP_SQL_DATA_CONTROL_H_
26 #define _FAPP_SQL_DATA_CONTROL_H_
28 #include <FOspConfig.h>
29 #include <FBaseDataType.h>
30 #include <FBaseObject.h>
32 namespace Tizen { namespace Base
35 namespace Collection {
41 namespace Tizen { namespace App
44 class _SqlDataControlImpl;
45 class ISqlDataControlResponseListener;
48 * @class SqlDataControl
49 * @brief This class represents the SQL-type data control behavior.
53 * @final This class is not intended for extension.
55 * The %SqlDataControl class represents the data control behavior, that provides a standard mechanism
56 * for accessing specific data exported by other applications.
57 * Data control provider can share its own data to data control consumers.
59 * For more information on the class features, see <a href="../org.tizen.native.appprogramming/html/guide/app/data_controls.htm">Data Controls</a>.
61 * @see Tizen::App::AppManager
64 class _OSP_EXPORT_ SqlDataControl
65 : public Tizen::Base::Object
70 * This destructor overrides Tizen::Base::Object::~Object().
74 virtual ~SqlDataControl(void);
77 * Selects the specified columns to be queried. @n
78 * The result set of the specified columns is retrieved from a table owned by an SQL-type data control provider. @n
79 * The %Select() method is asynchronous.
80 * For receiving the response from the data control provider, set the listener with
81 * SqlDataControl::SetSqlDataControlResponseListener(). @n
82 * When the requested result set has been received from the data control provider,
83 * the ISqlDataControlResponseListener::OnSqlDataControlSelectResponseReceived() method is called.
87 * @return An error code
88 * @param[in] dataId A string for identifying specific data, usually a database table to query from @n
89 * The string consists of one or more components, separated by a slash('/').
90 * @param[in] pColumnList A list of column names to query @n
91 * The type of objects contained in the specified @c pColumnList must be
92 * Tizen::Base::String class.
93 * If the specified @c pColumnList is @c null, all columns are selected.
94 * @param[in] pWhere A filter to select desired rows to query @n
95 * It is an SQL 'WHERE' clause excluding the 'WHERE' itself such as
96 * column1 = 'stringValue' AND column2 = numericValue.
97 * @param[in] pOrder The sorting order of rows to query @n
98 * It is an SQL 'ORDER BY' clause excluding the 'ORDER BY' itself.
99 * @param[out] reqId The request ID
100 * @param[in] pageNo The page number of the result set @n It starts from @c 1.
101 * @param[in] countPerPage The desired maximum count of rows on a page
102 * @exception E_SUCCESS The method is successful.
103 * @exception E_INVALID_STATE This instance has not been properly constructed.
104 * @exception E_INVALID_ARG Either of the following conditions has occurred:
105 * - The specified @c pColumnList is empty.
106 * - The specified @c pageNo parameter is less than @c 1.
107 * - The specified @c countPerPage parameter is less than @c 1.
108 * @exception E_ILLEGAL_ACCESS Either of the following conditions has occurred: @n
109 * - Access is denied due to insufficient permission.
110 * - The application using this method is not signed with the same certificate of provider application. @b Since: @b 2.1
111 * @exception E_MAX_EXCEEDED The size of sending buffer has exceeded the maximum limit.
112 * @exception E_SYSTEM A system error has occurred.
113 * @remarks If the value specified in the @c pWhere is string, the value must be wrapped in
114 * single quotes. Otherwise it is not needed to wrap the numeric value in single quotes.
115 * For more information on the SQL statement, see SQLite SQL documents.
116 * @remarks The recommended data size is under 16KB because severe system performance degradation may occur for large messages. E_MAX_EXCEED may be returned for messages over 16KB size.
118 result Select(const Tizen::Base::String& dataId, const Tizen::Base::Collection::IList* pColumnList,
119 const Tizen::Base::String* pWhere, const Tizen::Base::String *pOrder, RequestId& reqId,
120 int pageNo = 1, int countPerPage = 20);
123 * Inserts new rows into a table owned by an SQL-type data control provider. @n
124 * The %Insert() method is asynchronous.
125 * For receiving the response from the data control provider, set the listener with
126 * SqlDataControl::SetSqlDataControlResponseListener(). @n
127 * When the response has been received from the data control provider,
128 * the ISqlDataControlResponseListener::OnSqlDataControlInsertResponseReceived() method is called.
132 * @return An error code
133 * @param[in] dataId A string for identifying specific data, usually a database table to insert into @n
134 * The string consists of one or more components, separated by a slash('/').
135 * @param[in] insertMap The column-value pairs to insert @n
136 * The type of objects contained in the specified @c insertMap must be
137 * Tizen::Base::String class.
138 * @param[out] reqId The request ID
139 * @exception E_SUCCESS The method is successful.
140 * @exception E_INVALID_STATE This instance has not been properly constructed.
141 * @exception E_INVALID_ARG The specified @c insertMap is empty.
142 * @exception E_ILLEGAL_ACCESS Either of the following conditions has occurred: @n
143 * - Access is denied due to insufficient permission.
144 * - The application using this method is not signed with the same certificate of provider application. @b Since: @b 2.1
145 * @exception E_MAX_EXCEEDED The size of sending buffer has exceeded the maximum limit.
146 * @exception E_SYSTEM A system error has occurred.
147 * @remarks If the value specified in the @c insertMap is string, the value must be wrapped in
148 * single quotes. Otherwise it is not needed to wrap the numeric value in single quotes.
149 * For more information on the SQL statement, see SQLite SQL documents.
150 * @remarks The recommended data size is under 16KB because severe system performance degradation may occur for large messages. E_MAX_EXCEED may be returned for messages over 16KB size.
152 result Insert(const Tizen::Base::String& dataId, const Tizen::Base::Collection::IMap& insertMap, RequestId& reqId);
155 * Updates values of a table owned by an SQL-type data control provider. @n
156 * The %Update() method is asynchronous.
157 * For receiving the response from the data control provider, set the listener with
158 * SqlDataControl::SetSqlDataControlResponseListener(). @n
159 * When the response has been received from the data control provider,
160 * the ISqlDataControlResponseListener::OnSqlDataControlUpdateResponseReceived() method is called.
164 * @return An error code
165 * @param[in] dataId A string for identifying specific data, usually a database table to update @n
166 * The string consists of one or more components, separated by a slash('/').
167 * @param[in] updateMap The column-value pairs to update @n
168 * The type of objects contained in the specified @c updateMap must be
169 * Tizen::Base::String class. @n
170 * @param[in] pWhere A filter to select desired rows to update @n
171 * It is an SQL 'WHERE' clause excluding the 'WHERE' itself such as
172 * column1 = 'stringValue' AND column2 = numericValue.
173 * @param[out] reqId The request ID
174 * @exception E_SUCCESS The method is successful.
175 * @exception E_INVALID_STATE This instance has not been properly constructed.
176 * @exception E_INVALID_ARG The specified @c updateMap is empty.
177 * @exception E_ILLEGAL_ACCESS Either of the following conditions has occurred: @n
178 * - Access is denied due to insufficient permission.
179 * - The application using this method is not signed with the same certificate of provider application. @b Since: @b 2.1
180 * @exception E_MAX_EXCEEDED The size of sending buffer has exceeded the maximum limit.
181 * @exception E_SYSTEM A system error has occurred.
182 * @remarks If the value specified in the @c pWhere or @c updateMap is string, the value must be wrapped in
183 * single quotes. Otherwise it is not needed to wrap the numeric value in single quotes.
184 * For more information on the SQL statement, see SQLITE SQL documents.
185 * @remarks The recommended data size is under 16KB because severe system performance degradation may occur for large messages. E_MAX_EXCEED may be returned for messages over 16KB size.
187 result Update(const Tizen::Base::String& dataId, const Tizen::Base::Collection::IMap& updateMap,
188 const Tizen::Base::String* pWhere, RequestId& reqId);
191 * Deletes rows of a table owned by an SQL-type data control provider. @n
192 * The %Delete() method is asynchronous.
193 * For receiving the response from the data control provider, set the listener with
194 * SqlDataControl::SetSqlDataControlResponseListener(). @n
195 * When the response has been received from the data control provider,
196 * the ISqlDataControlResponseListener::OnSqlDataControlDeleteResponseReceived() method is called.
200 * @return An error code
201 * @param[in] dataId A string for identifying specific data, usually a database table to delete from @n
202 * The string consists of one or more components, separated by a slash('/').
203 * @param[in] pWhere A filter to select desired rows to delete @n
204 * It is an SQL 'WHERE' clause excluding the 'WHERE' itself such as
205 * column1 = 'stringValue' AND column2 = numericValue.
206 * If it is @c null, all rows are deleted.
207 * @param[out] reqId The request ID
208 * @exception E_SUCCESS The method is successful.
209 * @exception E_INVALID_STATE This instance has not been properly constructed.
210 * @exception E_INVALID_ARG A specified parameter is invalid.
211 * @exception E_ILLEGAL_ACCESS Either of the following conditions has occurred: @n
212 * - Access is denied due to insufficient permission.
213 * - The application using this method is not signed with the same certificate of provider application. @b Since: @b 2.1
214 * @exception E_MAX_EXCEEDED The size of sending buffer has exceeded the maximum limit.
215 * @exception E_SYSTEM A system error has occurred.
216 * @remarks If the value specified in the @c pWhere is string, the value must be wrapped in
217 * single quotes. Otherwise it is not needed to wrap the numeric value in single quotes.
218 * For more information on the SQL statement, see SQLITE SQL documents.
219 * @remarks The recommended data size is under 16KB because severe system performance degradation may occur for large messages. E_MAX_EXCEED may be returned for messages over 16KB size.
221 result Delete(const Tizen::Base::String& dataId, const Tizen::Base::String* pWhere, RequestId& reqId);
224 * Sets an SQL-type data control listener to this instance.
228 * @return An error code
229 * @param[in] pListener The data control callback listener @n
230 * Some data controls need to get the callback result by implementing
231 * the ISqlDataControlResponseListener interface.
232 * @exception E_SUCCESS The method is successful.
233 * @exception E_INVALID_STATE This instance has not been properly constructed.
234 * @exception E_SYSTEM A system error has occurred.
236 result SetSqlDataControlResponseListener(ISqlDataControlResponseListener* pListener);
240 * This default constructor is intentionally declared as private so that only the platform can create an instance.
244 SqlDataControl(void);
247 * The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
250 * @remarks This constructor is hidden.
252 SqlDataControl(const SqlDataControl& rhs);
255 * The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
258 * @remarks This operator is hidden.
260 SqlDataControl& operator =(const SqlDataControl& rhs);
262 class _SqlDataControlImpl* __pSqlDataControlImpl;
264 friend class _SqlDataControlImpl;
270 #endif // _FAPP_SQL_DATA_CONTROL_H_