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 FAppMapDataControl.h
19 * @brief This is the header file for the %MapDataControl class.
21 * This header file contains the declarations of the %MapDataControl class.
24 #ifndef _FAPP_MAP_DATA_CONTROL_H_
25 #define _FAPP_MAP_DATA_CONTROL_H_
27 #include <FBaseDataType.h>
28 #include <FBaseObject.h>
30 namespace Tizen { namespace Base
35 namespace Tizen { namespace App
38 class IMapDataControlResponseListener;
41 * @class MapDataControl
42 * @brief This class represents the key-value structured data control behavior.
46 * @final This class is not intended for extension.
48 * The %MapDataControl class represents the key-value structured data control behavior, that provides a standard mechanism
49 * for accessing specific data exported by other applications.
50 * A data control provider can share its data with data control consumers.
52 * For more information on the class features, see <a href="../org.tizen.native.appprogramming/html/guide/app/data_controls.htm">Data Controls</a>.
54 * @see Tizen::App::AppManager
56 * The following example demonstrates how to use the %MapDataControl class.
63 * using namespace Tizen::Base;
64 * using namespace Tizen::App;
66 * class MyMapDataControlResponseListener:
67 * : public Tizen::App::IMapDataControlResponseListener
70 * void OnMapDataControlGetValueResponseReceived(RequestId reqId, const String& providerId, const String& dataId, IList& resultValueList, bool providerResult, const String* pErrorMsg)
72 * int count = resultValueList.GetCount();
73 * for (int i = 0; i < count; i++)
75 * String pPerson = static_cast< String* >(resultValueList.GetAt(i));
76 * AppLog("%dth person: %ls", i, pPerson->GetPointer());
82 * MyClass::Execute(void)
84 * String providerId(L"http://tizen.org/datacontrol/provider/example");
85 * MapDataControl* pDc = AppManager::GetMapDataControlN(providerId);
87 * MyMapDataControlResponseListener* pResponseListener = new MyMapDataControlResponseListener();
89 * pDc->SetMapDataControlResponseListener(pResponseListener);
91 * String dataId(L"test");
92 * String person(L"person");
95 * pDc->GetValue(dataId, person, reqId);
101 class _OSP_EXPORT_ MapDataControl
102 : public Tizen::Base::Object
107 * This destructor overrides Tizen::Base::Object::~Object().
111 virtual ~MapDataControl(void);
114 * Gets the value list associated with the specified @c key, from the key-values map owned by the key-value structured data control provider. @n
115 * The %GetValue() method is asynchronous.
116 * For receiving the response from the data control provider, set the listener
117 * using the MapDataControl::SetMapDataControlResponseListener() method. @n
118 * When the requested value list has been received from the data control provider,
119 * the IMapDataControlResponseListener::OnMapDataControlGetValueResponseReceived() method is called.
123 * @privilege %http://tizen.org/privilege/datacontrol.consumer
125 * @return An error code
126 * @param[in] dataId The string that identifies the specific data, usually a registry section to get from @n
127 * The string consists of one or more components, separated by a slash('/').
128 * @param[in] key The key of the value list to obtain
129 * @param[out] reqId The ID of the request
130 * @param[in] pageNo The page number of the value set @n
131 * It starts from @c 1.
132 * @param[in] countPerPage The desired maximum count of the data items per page
133 * @exception E_SUCCESS The method is successful.
134 * @exception E_INVALID_STATE This instance has not been constructed properly as yet.
135 * @exception E_INVALID_ARG Either of the following conditions has occurred:
136 * - The specified @c pageNo is less than @c 1.
137 * - The specified @c countPerPage is less than @c 1.
138 * @exception E_ILLEGAL_ACCESS Either of the following conditions has occurred:
139 * - The access is denied due to insufficient permission.
140 * - The application using this method is not signed with the same certificate as that of the provider application. @b Since: @b 2.1
141 * @exception E_MAX_EXCEEDED Either of the following conditions has occurred:
142 * - The total size of the method arguments has exceeded the maximum limit.
143 * - The number of requests sent have exceeded the maximum limit.
144 * @exception E_PRIVILEGE_DENIED The application does not have the privilege to call this method.
145 * @exception E_SYSTEM A system error has occurred.
146 * @remarks The total size of the method arguments is under 16KB because a severe system performance degradation may occur for larger messages. @n
147 * @c E_MAX_EXCEEDED may be returned for messages over 16KB.
149 result GetValue(const Tizen::Base::String& dataId, const Tizen::Base::String& key, RequestId& reqId, int pageNo = 1, int countPerPage = 20);
152 * Adds the value associated with the specified @c key, to the key-values map owned by the key-value structured data control provider. @n
153 * The %AddValue() method is asynchronous.
154 * For receiving the response from the data control provider, set the listener
155 * using the MapDataControl::SetMapDataControlResponseListener() method. @n
156 * When the response has been received from the data control provider,
157 * the IMapDataControlResponseListener::OnMapDataControlAddValueResponseReceived() method is called.
161 * @privilege %http://tizen.org/privilege/datacontrol.consumer
163 * @return An error code
164 * @param[in] dataId The string that identifies the specific data, usually a registry section to add to @n
165 * The string consists of one or more components, separated by a slash('/').
166 * @param[in] key The key of the value list to add
167 * @param[in] value The value to add
168 * @param[out] reqId The ID of the request
169 * @exception E_SUCCESS The method is successful.
170 * @exception E_INVALID_STATE This instance has not been constructed properly as yet.
171 * @exception E_ILLEGAL_ACCESS Either of the following conditions has occurred:
172 * - The access is denied due to insufficient permission.
173 * - The application using this method is not signed with the same certificate as that of the provider application. @b Since: @b 2.1
174 * @exception E_MAX_EXCEEDED Either of the following conditions has occurred:
175 * - The total size of the method arguments has exceeded the maximum limit.
176 * - The number of requests sent have exceeded the maximum limit.
177 * @exception E_PRIVILEGE_DENIED The application does not have the privilege to call this method.
178 * @exception E_SYSTEM A system error has occurred.
179 * @remarks The total size of the method arguments is under 16KB because a severe system performance degradation may occur for larger messages. @n
180 * @c E_MAX_EXCEEDED may be returned for messages over 16KB.
182 result AddValue(const Tizen::Base::String& dataId, const Tizen::Base::String& key, const Tizen::Base::String& value, RequestId& reqId);
185 * Sets the value associated with the specified @c key to a new value. @n
186 * The key-values map is owned by the key-value structured data control provider. @n
187 * The %SetValue() method is asynchronous.
188 * For receiving the response from the data control provider, set the listener
189 * using the MapDataControl::SetMapDataControlResponseListener() method. @n
190 * When the response has been received from the data control provider,
191 * the IMapDataControlResponseListener::OnMapDataControlSetValueResponseReceived() method is called.
195 * @privilege %http://tizen.org/privilege/datacontrol.consumer
197 * @return An error code
198 * @param[in] dataId The string that identifies the specific data, usually a registry section to update @n
199 * The string consists of one or more components, separated by a slash('/').
200 * @param[in] key The key of the value to replace
201 * @param[in] oldValue The value to replace
202 * @param[in] newValue The new value that replaces the existing value
203 * @param[out] reqId The ID of the request
204 * @exception E_SUCCESS The method is successful.
205 * @exception E_INVALID_STATE This instance has not been constructed properly as yet.
206 * @exception E_ILLEGAL_ACCESS Either of the following conditions has occurred:
207 * - The access is denied due to insufficient permission.
208 * - The application using this method is not signed with the same certificate as that of the provider application. @b Since: @b 2.1
209 * @exception E_MAX_EXCEEDED Either of the following conditions has occurred:
210 * - The total size of the method arguments has exceeded the maximum limit.
211 * - The number of requests sent have exceeded the maximum limit.
212 * @exception E_PRIVILEGE_DENIED The application does not have the privilege to call this method.
213 * @exception E_SYSTEM A system error has occurred.
214 * @remarks The total size of the method arguments is under 16KB because a severe system performance degradation may occur for larger messages. @n
215 * @c E_MAX_EXCEEDED may be returned for messages over 16KB.
217 result SetValue(const Tizen::Base::String& dataId, const Tizen::Base::String& key, const Tizen::Base::String& oldValue, const Tizen::Base::String& newValue, RequestId& reqId);
220 * Removes the value associated with the specified @c key, from the key-values map owned by the key-value structured data control provider. @n
221 * The %RemoveValue() method is asynchronous.
222 * For receiving the response from the data control provider, set the listener
223 * using the MapDataControl::SetMapDataControlResponseListener() method. @n
224 * When the response has been received from the data control provider,
225 * the IMapDataControlResponseListener::OnMapDataControlRemoveValueResponseReceived() method is called.
229 * @privilege %http://tizen.org/privilege/datacontrol.consumer
231 * @return An error code
232 * @param[in] dataId The string that identifies the specific data, usually a registry section to remove from @n
233 * The string consists of one or more components, separated by a slash('/').
234 * @param[in] key The key of the value to remove
235 * @param[in] value The value to remove
236 * @param[out] reqId The ID of the request
237 * @exception E_SUCCESS The method is successful.
238 * @exception E_INVALID_STATE This instance has not been constructed properly as yet.
239 * @exception E_ILLEGAL_ACCESS Either of the following conditions has occurred:
240 * - The access is denied due to insufficient permission.
241 * - The application using this method is not signed with the same certificate as that of the provider application. @b Since: @b 2.1
242 * @exception E_MAX_EXCEEDED Either of the following conditions has occurred:
243 * - The total size of the method arguments has exceeded the maximum limit.
244 * - The number of requests sent have exceeded the maximum limit.
245 * @exception E_PRIVILEGE_DENIED The application does not have the privilege to call this method.
246 * @exception E_SYSTEM A system error has occurred.
247 * @remarks The total size of the method arguments is under 16KB because a severe system performance degradation may occur for larger messages. @n
248 * @c E_MAX_EXCEEDED may be returned for messages over 16KB.
250 result RemoveValue(const Tizen::Base::String& dataId, const Tizen::Base::String& key, const Tizen::Base::String& value, RequestId& reqId);
253 * Sets the MAP-based data control listener for this instance.
257 * @return An error code
258 * @param[in] pListener The data control callback listener @n
259 * Some data controls need to get the callback result by implementing
260 * the IMapDataControlResponseListener interface.
261 * @exception E_SUCCESS The method is successful.
262 * @exception E_INVALID_STATE This instance has not been constructed properly as yet.
263 * @exception E_SYSTEM A system error has occurred.
265 result SetMapDataControlResponseListener(IMapDataControlResponseListener* pListener);
269 * This default constructor is intentionally declared as private so that only the platform can create an instance.
273 MapDataControl(void);
276 * The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
279 * @remarks This constructor is hidden.
281 MapDataControl(const MapDataControl& mapDataControl);
284 * The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
287 * @remarks This operator is hidden.
289 MapDataControl& operator =(const MapDataControl& mapDataControl);
292 class _MapDataControlImpl * __pMapDataControlImpl;
294 friend class _MapDataControlImpl;
299 #endif // _FAPP_MAP_DATA_CONTROL_H_