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 FAppMapDataControl.h
20 * @brief This is the header file for the %MapDataControl class.
22 * This header file contains the declarations of the %MapDataControl class.
25 #ifndef _FAPP_MAP_DATA_CONTROL_H_
26 #define _FAPP_MAP_DATA_CONTROL_H_
28 #include <FBaseDataType.h>
29 #include <FBaseObject.h>
31 namespace Tizen { namespace Base
36 namespace Tizen { namespace App
39 class IMapDataControlResponseListener;
42 * @class MapDataControl
43 * @brief This class represents the MAP-type data control behavior.
47 * @final This class is not intended for extension.
49 * The %MapDataControl class represents the MAP-type data control behavior, that provides a standard mechanism
50 * for accessing specific data exported by other applications.
51 * Data control provider can share its own data to data control consumers.
53 * For more information on the class features, see <a href="../org.tizen.native.appprogramming/html/guide/app/data_controls.htm">Data Controls</a>.
55 * @see Tizen::App::AppManager
62 * using namespace Tizen::Base;
63 * using namespace Tizen::App;
65 * class MyMapDataControlResponseListener:
66 * : public Tizen::App::IMapDataControlResponseListener
69 * void OnMapDataControlGetValueResponseReceived(RequestId reqId, const String& providerId, const String& dataId, IList& resultValueList, bool providerResult, const String* pErrorMsg)
71 * int count = resultValueList.GetCount();
72 * for (int i = 0; i < count; i++)
74 * String pPerson = static_cast< String* >(resultValueList.GetAt(i));
75 * AppLog("%dth person: %ls", i, pPerson->GetPointer());
81 * MyClass::Execute(void)
83 * String providerId(L"http://tizen.org/datacontrol/provider/example");
84 * MapDataControl* pDc = AppManager::GetMapDataControlN(providerId);
86 * MyMapDataControlResponseListener* pResponseListener = new MyMapDataControlResponseListener();
88 * pDc->SetMapDataControlResponseListener(pResponseListener);
90 * String dataId(L"test");
91 * String person(L"person");
94 * pDc->GetValue(dataId, person, reqId);
100 class _OSP_EXPORT_ MapDataControl
101 : public Tizen::Base::Object
106 * This destructor overrides Tizen::Base::Object::~Object().
110 virtual ~MapDataControl(void);
113 * Gets the value list associated with the specified @c key, from a key-values map owned by MAP-type data control provider. @n
114 * The %GetValue() method is asynchronous.
115 * For receiving the response from data control provider, set the listener
116 * with MapDataControl::SetMapDataControlResponseListener(). @n
117 * When the requested value list has been received from data control provider,
118 * the IMapDataControlResponseListener::OnMapDataControlGetValueResponseReceived() method is called.
122 * @return An error code
123 * @param[in] dataId A string for identifying specific data, usually a registry section to get from @n
124 * The string consists of one or more components, separated by a slash('/').
125 * @param[in] key A key of the value list to obtain
126 * @param[out] reqId The ID of the request
127 * @param[in] pageNo The page number of the value set @n
128 * It starts from @c 1.
129 * @param[in] countPerPage The desired maximum count of the data item on the page
130 * @exception E_SUCCESS The method is successful.
131 * @exception E_INVALID_STATE This instance has not been properly constructed as yet.
132 * @exception E_INVALID_ARG Either of the following conditions has occurred: @n
133 * - The specified @c pageNo parameter is less than @c 1.
134 * - The specified @c countPerPage parameter is less than @c 1.
135 * @exception E_ILLEGAL_ACCESS Either of the following conditions has occurred: @n
136 * - Access is denied due to insufficient permission.
137 * - The application using this method is not signed with the same certificate of provider application. @b Since: @b 2.1
138 * @exception E_MAX_EXCEEDED Either of the following conditions has occurred: @n
139 * - The size of sending buffer has exceeded the maximum limit.
140 * - The number of sending requests has exceeded the maximum limit.
141 * @exception E_SYSTEM A system error has occurred.
142 * @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.
144 result GetValue(const Tizen::Base::String& dataId, const Tizen::Base::String& key, RequestId& reqId, int pageNo = 1, int countPerPage = 20);
147 * Adds the value associated with the specified @c key, to a key-values map owned by MAP-type data control provider. @n
148 * The %AddValue() method is asynchronous.
149 * For receiving the response from data control provider, set the listener
150 * with MapDataControl::SetMapDataControlResponseListener(). @n
151 * When the response has been received from the data control provider,
152 * the IMapDataControlResponseListener::OnMapDataControlAddValueResponseReceived() method is called.
156 * @return An error code
157 * @param[in] dataId A string for identifying specific data, usually a registry section to add to @n
158 * The string consists of one or more components, separated by a slash('/').
159 * @param[in] key A key of the value list to add
160 * @param[in] value A value to add
161 * @param[out] reqId The ID of the request
162 * @exception E_SUCCESS The method is successful.
163 * @exception E_INVALID_STATE This instance has not been properly constructed as yet.
164 * @exception E_ILLEGAL_ACCESS Either of the following conditions has occurred: @n
165 * - Access is denied due to insufficient permission.
166 * - The application using this method is not signed with the same certificate of provider application. @b Since: @b 2.1
167 * @exception E_MAX_EXCEEDED Either of the following conditions has occurred: @n
168 * - The size of sending buffer has exceeded the maximum limit.
169 * - The number of sending requests has exceeded the maximum limit.
170 * @exception E_SYSTEM A system error has occurred.
171 * @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.
173 result AddValue(const Tizen::Base::String& dataId, const Tizen::Base::String& key, const Tizen::Base::String& value, RequestId& reqId);
176 * Sets the value associated with the specified @c key with a new value. @n
177 * The key-values map is owned by MAP-type data control provider. @n
178 * The %SetValue() method is asynchronous.
179 * For receiving the response from data control provider, set the listener
180 * with MapDataControl::SetMapDataControlResponseListener(). @n
181 * When the response has been received from the data control provider,
182 * the IMapDataControlResponseListener::OnMapDataControlSetValueResponseReceived() method is called.
186 * @return An error code
187 * @param[in] dataId A string for identifying specific data, usually a registry section to update @n
188 * The string consists of one or more components, separated by a slash('/').
189 * @param[in] key A key of the value to replace
190 * @param[in] oldValue A value to replace
191 * @param[in] newValue A new value to replace the existing value
192 * @param[out] reqId The ID of the request
193 * @exception E_SUCCESS The method is successful.
194 * @exception E_INVALID_STATE This instance has not been properly constructed as yet.
195 * @exception E_ILLEGAL_ACCESS Either of the following conditions has occurred: @n
196 * - Access is denied due to insufficient permission.
197 * - The application using this method is not signed with the same certificate of provider application. @b Since: @b 2.1
198 * @exception E_MAX_EXCEEDED Either of the following conditions has occurred: @n
199 * - The size of sending buffer has exceeded the maximum limit.
200 * - The number of sending requests has exceeded the maximum limit.
201 * @exception E_SYSTEM A system error has occurred.
202 * @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.
204 result SetValue(const Tizen::Base::String& dataId, const Tizen::Base::String& key, const Tizen::Base::String& oldValue, const Tizen::Base::String& newValue, RequestId& reqId);
207 * Removes the value associated with the specified @c key, from a key-values map owned by MAP-type data control provider. @n
208 * The %RemoveValue() method is asynchronous.
209 * For receiving the response from data control provider, set the listener
210 * with MapDataControl::SetMapDataControlResponseListener(). @n
211 * When the response has been received from the data control provider,
212 * the IMapDataControlResponseListener::OnMapDataControlRemoveValueResponseReceived() method is called.
216 * @return An error code
217 * @param[in] dataId A string for identifying specific data, usually a registry section to remove from @n
218 * The string consists of one or more components, separated by a slash('/').
219 * @param[in] key A key of the value to remove
220 * @param[in] value A value to remove
221 * @param[out] reqId The ID of the request
222 * @exception E_SUCCESS The method is successful.
223 * @exception E_INVALID_STATE This instance has not been properly constructed as yet.
224 * @exception E_ILLEGAL_ACCESS Either of the following conditions has occurred: @n
225 * - Access is denied due to insufficient permission.
226 * - The application using this method is not signed with the same certificate of provider application. @b Since: @b 2.1
227 * @exception E_MAX_EXCEEDED Either of the following conditions has occurred: @n
228 * - The size of sending buffer has exceeded the maximum limit.
229 * - The number of sending requests has exceeded the maximum limit.
230 * @exception E_SYSTEM A system error has occurred.
231 * @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.
233 result RemoveValue(const Tizen::Base::String& dataId, const Tizen::Base::String& key, const Tizen::Base::String& value, RequestId& reqId);
236 * Sets the MAP-based data control listener to this instance.
240 * @return An error code
241 * @param[in] pListener The data control callback listener @n
242 * Some data controls need to get the callback result by implementing
243 * the IMapDataControlResponseListener interface.
244 * @exception E_SUCCESS The method is successful.
245 * @exception E_INVALID_STATE This instance has not been properly constructed.
246 * @exception E_SYSTEM A system error has occurred.
248 result SetMapDataControlResponseListener(IMapDataControlResponseListener* pListener);
252 * This default constructor is intentionally declared as private so that only the platform can create an instance.
256 MapDataControl(void);
259 * The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
262 * @remarks This constructor is hidden.
264 MapDataControl(const MapDataControl& mapDataControl);
267 * The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
270 * @remarks This operator is hidden.
272 MapDataControl& operator =(const MapDataControl& mapDataControl);
275 class _MapDataControlImpl * __pMapDataControlImpl;
277 friend class _MapDataControlImpl;
282 #endif // _FAPP_MAP_DATA_CONTROL_H_