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 MAP-type data control behavior.
46 * @final This class is not intended for extension.
48 * The %MapDataControl class represents the MAP-type data control behavior, that provides a standard mechanism
49 * for accessing specific data exported by other applications.
50 * Data control provider can share its own data to 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
61 * using namespace Tizen::Base;
62 * using namespace Tizen::App;
64 * class MyMapDataControlResponseListener:
65 * : public Tizen::App::IMapDataControlResponseListener
68 * void OnMapDataControlGetValueResponseReceived(RequestId reqId, const String& providerId, const String& dataId, IList& resultValueList, bool providerResult, const String* pErrorMsg)
70 * int count = resultValueList.GetCount();
71 * for (int i = 0; i < count; i++)
73 * String pPerson = static_cast< String* >(resultValueList.GetAt(i));
74 * AppLog("%dth person: %ls", i, pPerson->GetPointer());
80 * MyClass::Execute(void)
82 * String providerId(L"http://tizen.org/datacontrol/provider/example");
83 * MapDataControl* pDc = AppManager::GetMapDataControlN(providerId);
85 * MyMapDataControlResponseListener* pResponseListener = new MyMapDataControlResponseListener();
87 * pDc->SetMapDataControlResponseListener(pResponseListener);
89 * String dataId(L"test");
90 * String person(L"person");
93 * pDc->GetValue(dataId, person, reqId);
99 class _OSP_EXPORT_ MapDataControl
100 : public Tizen::Base::Object
105 * This destructor overrides Tizen::Base::Object::~Object().
109 virtual ~MapDataControl(void);
112 * Gets the value list associated with the specified @c key, from a key-values map owned by MAP-type data control provider. @n
113 * The %GetValue() method is asynchronous.
114 * For receiving the response from data control provider, set the listener
115 * with MapDataControl::SetMapDataControlResponseListener(). @n
116 * When the requested value list has been received from data control provider,
117 * the IMapDataControlResponseListener::OnMapDataControlGetValueResponseReceived() method is called.
121 * @return An error code
122 * @param[in] dataId A string for identifying specific data, usually a registry section to get from @n
123 * The string consists of one or more components, separated by a slash('/').
124 * @param[in] key A key of the value list to obtain
125 * @param[out] reqId The ID of the request
126 * @param[in] pageNo The page number of the value set @n
127 * It starts from @c 1.
128 * @param[in] countPerPage The desired maximum count of the data item on the page
129 * @exception E_SUCCESS The method is successful.
130 * @exception E_INVALID_STATE This instance has not been properly constructed as yet.
131 * @exception E_INVALID_ARG Either of the following conditions has occurred: @n
132 * - The specified @c pageNo parameter is less than @c 1.
133 * - The specified @c countPerPage parameter is less than @c 1.
134 * @exception E_ILLEGAL_ACCESS Either of the following conditions has occurred: @n
135 * - Access is denied due to insufficient permission.
136 * - The application using this method is not signed with the same certificate of provider application. @b Since: @b 2.1
137 * @exception E_MAX_EXCEEDED Either of the following conditions has occurred: @n
138 * - The size of sending buffer has exceeded the maximum limit.
139 * - The number of sending requests has exceeded the maximum limit.
140 * @exception E_SYSTEM A system error has occurred.
141 * @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.
143 result GetValue(const Tizen::Base::String& dataId, const Tizen::Base::String& key, RequestId& reqId, int pageNo = 1, int countPerPage = 20);
146 * Adds the value associated with the specified @c key, to a key-values map owned by MAP-type data control provider. @n
147 * The %AddValue() method is asynchronous.
148 * For receiving the response from data control provider, set the listener
149 * with MapDataControl::SetMapDataControlResponseListener(). @n
150 * When the response has been received from the data control provider,
151 * the IMapDataControlResponseListener::OnMapDataControlAddValueResponseReceived() method is called.
155 * @return An error code
156 * @param[in] dataId A string for identifying specific data, usually a registry section to add to @n
157 * The string consists of one or more components, separated by a slash('/').
158 * @param[in] key A key of the value list to add
159 * @param[in] value A value to add
160 * @param[out] reqId The ID of the request
161 * @exception E_SUCCESS The method is successful.
162 * @exception E_INVALID_STATE This instance has not been properly constructed as yet.
163 * @exception E_ILLEGAL_ACCESS Either of the following conditions has occurred: @n
164 * - Access is denied due to insufficient permission.
165 * - The application using this method is not signed with the same certificate of provider application. @b Since: @b 2.1
166 * @exception E_MAX_EXCEEDED Either of the following conditions has occurred: @n
167 * - The size of sending buffer has exceeded the maximum limit.
168 * - The number of sending requests has exceeded the maximum limit.
169 * @exception E_SYSTEM A system error has occurred.
170 * @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.
172 result AddValue(const Tizen::Base::String& dataId, const Tizen::Base::String& key, const Tizen::Base::String& value, RequestId& reqId);
175 * Sets the value associated with the specified @c key with a new value. @n
176 * The key-values map is owned by MAP-type data control provider. @n
177 * The %SetValue() method is asynchronous.
178 * For receiving the response from data control provider, set the listener
179 * with MapDataControl::SetMapDataControlResponseListener(). @n
180 * When the response has been received from the data control provider,
181 * the IMapDataControlResponseListener::OnMapDataControlSetValueResponseReceived() method is called.
185 * @return An error code
186 * @param[in] dataId A string for identifying specific data, usually a registry section to update @n
187 * The string consists of one or more components, separated by a slash('/').
188 * @param[in] key A key of the value to replace
189 * @param[in] oldValue A value to replace
190 * @param[in] newValue A new value to replace the existing value
191 * @param[out] reqId The ID of the request
192 * @exception E_SUCCESS The method is successful.
193 * @exception E_INVALID_STATE This instance has not been properly constructed as yet.
194 * @exception E_ILLEGAL_ACCESS Either of the following conditions has occurred: @n
195 * - Access is denied due to insufficient permission.
196 * - The application using this method is not signed with the same certificate of provider application. @b Since: @b 2.1
197 * @exception E_MAX_EXCEEDED Either of the following conditions has occurred: @n
198 * - The size of sending buffer has exceeded the maximum limit.
199 * - The number of sending requests has exceeded the maximum limit.
200 * @exception E_SYSTEM A system error has occurred.
201 * @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.
203 result SetValue(const Tizen::Base::String& dataId, const Tizen::Base::String& key, const Tizen::Base::String& oldValue, const Tizen::Base::String& newValue, RequestId& reqId);
206 * Removes the value associated with the specified @c key, from a key-values map owned by MAP-type data control provider. @n
207 * The %RemoveValue() method is asynchronous.
208 * For receiving the response from data control provider, set the listener
209 * with MapDataControl::SetMapDataControlResponseListener(). @n
210 * When the response has been received from the data control provider,
211 * the IMapDataControlResponseListener::OnMapDataControlRemoveValueResponseReceived() method is called.
215 * @return An error code
216 * @param[in] dataId A string for identifying specific data, usually a registry section to remove from @n
217 * The string consists of one or more components, separated by a slash('/').
218 * @param[in] key A key of the value to remove
219 * @param[in] value A value to remove
220 * @param[out] reqId The ID of the request
221 * @exception E_SUCCESS The method is successful.
222 * @exception E_INVALID_STATE This instance has not been properly constructed as yet.
223 * @exception E_ILLEGAL_ACCESS Either of the following conditions has occurred: @n
224 * - Access is denied due to insufficient permission.
225 * - The application using this method is not signed with the same certificate of provider application. @b Since: @b 2.1
226 * @exception E_MAX_EXCEEDED Either of the following conditions has occurred: @n
227 * - The size of sending buffer has exceeded the maximum limit.
228 * - The number of sending requests has exceeded the maximum limit.
229 * @exception E_SYSTEM A system error has occurred.
230 * @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.
232 result RemoveValue(const Tizen::Base::String& dataId, const Tizen::Base::String& key, const Tizen::Base::String& value, RequestId& reqId);
235 * Sets the MAP-based data control listener to this instance.
239 * @return An error code
240 * @param[in] pListener The data control callback listener @n
241 * Some data controls need to get the callback result by implementing
242 * the IMapDataControlResponseListener interface.
243 * @exception E_SUCCESS The method is successful.
244 * @exception E_INVALID_STATE This instance has not been properly constructed.
245 * @exception E_SYSTEM A system error has occurred.
247 result SetMapDataControlResponseListener(IMapDataControlResponseListener* pListener);
251 * This default constructor is intentionally declared as private so that only the platform can create an instance.
255 MapDataControl(void);
258 * The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
261 * @remarks This constructor is hidden.
263 MapDataControl(const MapDataControl& mapDataControl);
266 * The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
269 * @remarks This operator is hidden.
271 MapDataControl& operator =(const MapDataControl& mapDataControl);
274 class _MapDataControlImpl * __pMapDataControlImpl;
276 friend class _MapDataControlImpl;
281 #endif // _FAPP_MAP_DATA_CONTROL_H_