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 * @return An error code
124 * @param[in] dataId The string that identifies the specific data, usually a registry section to get from @n
125 * The string consists of one or more components, separated by a slash('/').
126 * @param[in] key The key of the value list to obtain
127 * @param[out] reqId The ID of the request
128 * @param[in] pageNo The page number of the value set @n
129 * It starts from @c 1.
130 * @param[in] countPerPage The desired maximum count of the data items per page
131 * @exception E_SUCCESS The method is successful.
132 * @exception E_INVALID_STATE This instance has not been constructed properly as yet.
133 * @exception E_INVALID_ARG Either of the following conditions has occurred:
134 * - The specified @c pageNo is less than @c 1.
135 * - The specified @c countPerPage is less than @c 1.
136 * @exception E_ILLEGAL_ACCESS Either of the following conditions has occurred:
137 * - The access is denied due to insufficient permission.
138 * - The application using this method is not signed with the same certificate as that of the provider application. @b Since: @b 2.1
139 * @exception E_MAX_EXCEEDED Either of the following conditions has occurred:
140 * - The total size of the method arguments has exceeded the maximum limit.
141 * - The number of requests sent have exceeded the maximum limit.
142 * @exception E_SYSTEM A system error has occurred.
143 * @remarks The total size of the method arguments is under 16KB because a severe system performance degradation may occur for larger messages. @n
144 * @c E_MAX_EXCEEDED may be returned for messages over 16KB.
146 result GetValue(const Tizen::Base::String& dataId, const Tizen::Base::String& key, RequestId& reqId, int pageNo = 1, int countPerPage = 20);
149 * Adds the value associated with the specified @c key, to the key-values map owned by the key-value structured data control provider. @n
150 * The %AddValue() method is asynchronous.
151 * For receiving the response from the data control provider, set the listener
152 * using the MapDataControl::SetMapDataControlResponseListener() method. @n
153 * When the response has been received from the data control provider,
154 * the IMapDataControlResponseListener::OnMapDataControlAddValueResponseReceived() method is called.
158 * @return An error code
159 * @param[in] dataId The string that identifies the specific data, usually a registry section to add to @n
160 * The string consists of one or more components, separated by a slash('/').
161 * @param[in] key The key of the value list to add
162 * @param[in] value The value to add
163 * @param[out] reqId The ID of the request
164 * @exception E_SUCCESS The method is successful.
165 * @exception E_INVALID_STATE This instance has not been constructed properly as yet.
166 * @exception E_ILLEGAL_ACCESS Either of the following conditions has occurred:
167 * - The access is denied due to insufficient permission.
168 * - The application using this method is not signed with the same certificate as that of the provider application. @b Since: @b 2.1
169 * @exception E_MAX_EXCEEDED Either of the following conditions has occurred:
170 * - The total size of the method arguments has exceeded the maximum limit.
171 * - The number of requests sent have exceeded the maximum limit.
172 * @exception E_SYSTEM A system error has occurred.
173 * @remarks The total size of the method arguments is under 16KB because a severe system performance degradation may occur for larger messages. @n
174 * @c E_MAX_EXCEEDED may be returned for messages over 16KB.
176 result AddValue(const Tizen::Base::String& dataId, const Tizen::Base::String& key, const Tizen::Base::String& value, RequestId& reqId);
179 * Sets the value associated with the specified @c key to a new value. @n
180 * The key-values map is owned by the key-value structured data control provider. @n
181 * The %SetValue() method is asynchronous.
182 * For receiving the response from the data control provider, set the listener
183 * using the MapDataControl::SetMapDataControlResponseListener() method. @n
184 * When the response has been received from the data control provider,
185 * the IMapDataControlResponseListener::OnMapDataControlSetValueResponseReceived() method is called.
189 * @return An error code
190 * @param[in] dataId The string that identifies the specific data, usually a registry section to update @n
191 * The string consists of one or more components, separated by a slash('/').
192 * @param[in] key The key of the value to replace
193 * @param[in] oldValue The value to replace
194 * @param[in] newValue The new value that replaces the existing value
195 * @param[out] reqId The ID of the request
196 * @exception E_SUCCESS The method is successful.
197 * @exception E_INVALID_STATE This instance has not been constructed properly as yet.
198 * @exception E_ILLEGAL_ACCESS Either of the following conditions has occurred:
199 * - The access is denied due to insufficient permission.
200 * - The application using this method is not signed with the same certificate as that of the provider application. @b Since: @b 2.1
201 * @exception E_MAX_EXCEEDED Either of the following conditions has occurred:
202 * - The total size of the method arguments has exceeded the maximum limit.
203 * - The number of requests sent have exceeded the maximum limit.
204 * @exception E_SYSTEM A system error has occurred.
205 * @remarks The total size of the method arguments is under 16KB because a severe system performance degradation may occur for larger messages. @n
206 * @c E_MAX_EXCEEDED may be returned for messages over 16KB.
208 result SetValue(const Tizen::Base::String& dataId, const Tizen::Base::String& key, const Tizen::Base::String& oldValue, const Tizen::Base::String& newValue, RequestId& reqId);
211 * Removes the value associated with the specified @c key, from the key-values map owned by the key-value structured data control provider. @n
212 * The %RemoveValue() method is asynchronous.
213 * For receiving the response from the data control provider, set the listener
214 * using the MapDataControl::SetMapDataControlResponseListener() method. @n
215 * When the response has been received from the data control provider,
216 * the IMapDataControlResponseListener::OnMapDataControlRemoveValueResponseReceived() method is called.
220 * @return An error code
221 * @param[in] dataId The string that identifies the specific data, usually a registry section to remove from @n
222 * The string consists of one or more components, separated by a slash('/').
223 * @param[in] key The key of the value to remove
224 * @param[in] value The value to remove
225 * @param[out] reqId The ID of the request
226 * @exception E_SUCCESS The method is successful.
227 * @exception E_INVALID_STATE This instance has not been constructed properly as yet.
228 * @exception E_ILLEGAL_ACCESS Either of the following conditions has occurred:
229 * - The access is denied due to insufficient permission.
230 * - The application using this method is not signed with the same certificate as that of the provider application. @b Since: @b 2.1
231 * @exception E_MAX_EXCEEDED Either of the following conditions has occurred:
232 * - The total size of the method arguments has exceeded the maximum limit.
233 * - The number of requests sent have exceeded the maximum limit.
234 * @exception E_SYSTEM A system error has occurred.
235 * @remarks The total size of the method arguments is under 16KB because a severe system performance degradation may occur for larger messages. @n
236 * @c E_MAX_EXCEEDED may be returned for messages over 16KB.
238 result RemoveValue(const Tizen::Base::String& dataId, const Tizen::Base::String& key, const Tizen::Base::String& value, RequestId& reqId);
241 * Sets the MAP-based data control listener for this instance.
245 * @return An error code
246 * @param[in] pListener The data control callback listener @n
247 * Some data controls need to get the callback result by implementing
248 * the IMapDataControlResponseListener interface.
249 * @exception E_SUCCESS The method is successful.
250 * @exception E_INVALID_STATE This instance has not been constructed properly as yet.
251 * @exception E_SYSTEM A system error has occurred.
253 result SetMapDataControlResponseListener(IMapDataControlResponseListener* pListener);
257 * This default constructor is intentionally declared as private so that only the platform can create an instance.
261 MapDataControl(void);
264 * The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
267 * @remarks This constructor is hidden.
269 MapDataControl(const MapDataControl& mapDataControl);
272 * The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
275 * @remarks This operator is hidden.
277 MapDataControl& operator =(const MapDataControl& mapDataControl);
280 class _MapDataControlImpl * __pMapDataControlImpl;
282 friend class _MapDataControlImpl;
287 #endif // _FAPP_MAP_DATA_CONTROL_H_