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
58 class _OSP_EXPORT_ MapDataControl
59 : public Tizen::Base::Object
64 * This destructor overrides Tizen::Base::Object::~Object().
68 virtual ~MapDataControl(void);
71 * Gets the value list associated with the specified @c key, from a key-values map owned by MAP-type data control provider. @n
72 * The %GetValue() method is asynchronous.
73 * For receiving the response from data control provider, set the listener
74 * with MapDataControl::SetMapDataControlResponseListener(). @n
75 * When the requested value list has been received from data control provider,
76 * the IMapDataControlResponseListener::OnMapDataControlGetValueResponseReceived() method is called.
80 * @return An error code
81 * @param[in] dataId A string for identifying specific data, usually a registry section to get from @n
82 * The string consists of one or more components, separated by a slash('/').
83 * @param[in] key A key of the value list to obtain
84 * @param[out] reqId The ID of the request
85 * @param[in] pageNo The page number of the value set @n
86 * It starts from @c 1.
87 * @param[in] countPerPage The desired maximum count of the data item on the page
88 * @exception E_SUCCESS The method is successful.
89 * @exception E_INVALID_STATE This instance has not been properly constructed as yet.
90 * @exception E_INVALID_ARG Either of the following conditions has occurred: @n
91 * - The specified @c pageNo parameter is less than @c 1.
92 * - The specified @c countPerPage parameter is less than @c 1.
93 * @exception E_ILLEGAL_ACCESS Access is denied due to insufficient permission.
94 * @exception E_OUT_OF_MEMORY The memory is insufficient.
95 * @exception E_SYSTEM A system error has occurred.
97 result GetValue(const Tizen::Base::String& dataId, const Tizen::Base::String& key, RequestId& reqId, int pageNo = 1, int countPerPage = 20);
100 * Adds the value associated with the specified @c key, to a key-values map owned by MAP-type data control provider. @n
101 * The %AddValue() method is asynchronous.
102 * For receiving the response from data control provider, set the listener
103 * with MapDataControl::SetMapDataControlResponseListener(). @n
104 * When the response has been received from the data control provider,
105 * the IMapDataControlResponseListener::OnMapDataControlAddValueResponseReceived() method is called.
109 * @return An error code
110 * @param[in] dataId A string for identifying specific data, usually a registry section to add to @n
111 * The string consists of one or more components, separated by a slash('/').
112 * @param[in] key A key of the value list to add
113 * @param[in] value A value to add
114 * @param[out] reqId The ID of the request
115 * @exception E_SUCCESS The method is successful.
116 * @exception E_INVALID_STATE This instance has not been properly constructed as yet.
117 * @exception E_ILLEGAL_ACCESS Access is denied due to insufficient permission.
118 * @exception E_OUT_OF_MEMORY The memory is insufficient.
119 * @exception E_SYSTEM A system error has occurred.
121 result AddValue(const Tizen::Base::String& dataId, const Tizen::Base::String& key, const Tizen::Base::String& value, RequestId& reqId);
124 * Sets the value associated with the specified @c key with a new value. @n
125 * The key-values map is owned by MAP-type data control provider. @n
126 * The %SetValue() method is asynchronous.
127 * For receiving the response from data control provider, set the listener
128 * with MapDataControl::SetMapDataControlResponseListener(). @n
129 * When the response has been received from the data control provider,
130 * the IMapDataControlResponseListener::OnMapDataControlSetValueResponseReceived() method is called.
134 * @return An error code
135 * @param[in] dataId A string for identifying specific data, usually a registry section to update @n
136 * The string consists of one or more components, separated by a slash('/').
137 * @param[in] key A key of the value to replace
138 * @param[in] oldValue A value to replace
139 * @param[in] newValue A new value to replace the existing value
140 * @param[out] reqId The ID of the request
141 * @exception E_SUCCESS The method is successful.
142 * @exception E_INVALID_STATE This instance has not been properly constructed as yet.
143 * @exception E_ILLEGAL_ACCESS Access is denied due to insufficient permission.
144 * @exception E_OUT_OF_MEMORY The memory is insufficient.
145 * @exception E_SYSTEM A system error has occurred.
147 result SetValue(const Tizen::Base::String& dataId, const Tizen::Base::String& key, const Tizen::Base::String& oldValue, const Tizen::Base::String& newValue, RequestId& reqId);
150 * Removes the value associated with the specified @c key, from a key-values map owned by MAP-type data control provider.
151 * The %RemoveValue() method is asynchronous.
152 * For receiving the response from data control provider, set the listener
153 * with MapDataControl::SetMapDataControlResponseListener(). @n
154 * When the response has been received from the data control provider,
155 * the IMapDataControlResponseListener::OnMapDataControlRemoveValueResponseReceived() method is called.
159 * @return An error code
160 * @param[in] dataId A string for identifying specific data, usually a registry section to remove from @n
161 * The string consists of one or more components, separated by a slash('/').
162 * @param[in] key A key of the value to removed
163 * @param[in] value A value to removed
164 * @param[out] reqId The ID of the request
165 * @exception E_SUCCESS The method is successful.
166 * @exception E_INVALID_STATE This instance has not been properly constructed as yet.
167 * @exception E_ILLEGAL_ACCESS Access is denied due to insufficient permission.
168 * @exception E_OUT_OF_MEMORY The memory is insufficient.
169 * @exception E_SYSTEM A system error has occurred.
171 result RemoveValue(const Tizen::Base::String& dataId, const Tizen::Base::String& key, const Tizen::Base::String& value, RequestId& reqId);
174 * Sets the MAP-based data control listener to this instance.
178 * @return An error code
179 * @param[in] pListener The data control callback listener @n
180 * Some data controls need to get the callback result by implementing
181 * the IMapDataControlResponseListener interface.
182 * @exception E_SUCCESS The method is successful.
183 * @exception E_INVALID_STATE This instance has not been properly constructed.
184 * @exception E_SYSTEM A system error has occurred.
186 result SetMapDataControlResponseListener(IMapDataControlResponseListener* pListener);
190 * This default constructor is intentionally declared as private so that only the platform can create an instance.
194 MapDataControl(void);
197 * The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
200 * @remarks This constructor is hidden.
202 MapDataControl(const MapDataControl& mapDataControl);
205 * The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
208 * @remarks This operator is hidden.
210 MapDataControl& operator =(const MapDataControl& mapDataControl);
213 class _MapDataControlImpl * __pMapDataControlImpl;
215 friend class _MapDataControlImpl;
220 #endif // _FAPP_MAP_DATA_CONTROL_H_