Add Io examples
[platform/framework/native/appfw.git] / inc / FAppMapDataControl.h
1 //
2 // Open Service Platform
3 // Copyright (c) 2012 Samsung Electronics Co., Ltd.
4 //
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
8 //
9 //     http://www.apache.org/licenses/LICENSE-2.0
10 //
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.
16 //
17
18 /**
19  * @file    FAppMapDataControl.h
20  * @brief   This is the header file for the %MapDataControl class.
21  *
22  * This header file contains the declarations of the %MapDataControl class.
23  */
24
25 #ifndef _FAPP_MAP_DATA_CONTROL_H_
26 #define _FAPP_MAP_DATA_CONTROL_H_
27
28 #include <FBaseDataType.h>
29 #include <FBaseObject.h>
30
31 namespace Tizen { namespace Base
32 {
33 class String;
34 }}
35
36 namespace Tizen { namespace App
37 {
38
39 class IMapDataControlResponseListener;
40
41 /**
42  * @class   MapDataControl
43  * @brief   This class represents the MAP-type data control behavior.
44  *
45  * @since       2.0
46  *
47  * @final   This class is not intended for extension.
48  *
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.
52  *
53  * For more information on the class features, see <a href="../org.tizen.native.appprogramming/html/guide/app/data_controls.htm">Data Controls</a>.
54  *
55  * @see Tizen::App::AppManager
56  *
57  * @code
58  *
59  * #include <FBase.h>
60  * #include <FApp.h>
61  *
62  * using namespace Tizen::Base;
63  * using namespace Tizen::App;
64  *
65  * class MyMapDataControlResponseListener:
66  *      : public Tizen::App::IMapDataControlResponseListener
67  * {
68  * public:
69  *      void OnMapDataControlGetValueResponseReceived(RequestId reqId, const String& providerId, const String& dataId, IList& resultValueList, bool providerResult, const String* pErrorMsg)
70  *      {
71  *              int count = resultValueList.GetCount();
72  *              for (int i = 0; i < count; i++)
73  *              {
74  *                      String pPerson = static_cast< String* >(resultValueList.GetAt(i));
75  *                      AppLog("%dth person: %ls", i, pPerson->GetPointer());
76  *              }
77  *      }
78  * };
79  *
80  * void
81  * MyClass::Execute(void)
82  * {
83  *              String providerId(L"http://tizen.org/datacontrol/provider/example");
84  *              MapDataControl* pDc = AppManager::GetMapDataControlN(providerId);
85  *
86  *              MyMapDataControlResponseListener* pResponseListener = new MyMapDataControlResponseListener();
87  *
88  *              pDc->SetMapDataControlResponseListener(pResponseListener);
89  *
90  *              String dataId(L"test");
91  *              String person(L"person");
92  *              RequestId reqId;
93  *
94  *              pDc->GetValue(dataId, person, reqId);
95  * }
96  *
97  * @endcode
98  */
99 class _OSP_EXPORT_ MapDataControl
100         : public Tizen::Base::Object
101 {
102
103 public:
104         /**
105         * This destructor overrides Tizen::Base::Object::~Object().
106         *
107         * @since        2.0
108         */
109         virtual ~MapDataControl(void);
110
111         /**
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.
118         *
119         * @since        2.0
120         *
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. E_MAX_EXCEEDED may be returned for messages over 16KB size.
142         */
143         result GetValue(const Tizen::Base::String& dataId, const Tizen::Base::String& key, RequestId& reqId, int pageNo = 1, int countPerPage = 20);
144
145         /**
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.
152         *
153         * @since        2.0
154         *
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. E_MAX_EXCEEDED may be returned for messages over 16KB size.
171         */
172         result AddValue(const Tizen::Base::String& dataId, const Tizen::Base::String& key, const Tizen::Base::String& value, RequestId& reqId);
173
174         /**
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.
182         *
183         * @since        2.0
184         *
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. E_MAX_EXCEEDED may be returned for messages over 16KB size.
202         */
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);
204
205         /**
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.
212         *
213         * @since        2.0
214         *
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. E_MAX_EXCEEDED may be returned for messages over 16KB size.
231         */
232         result RemoveValue(const Tizen::Base::String& dataId, const Tizen::Base::String& key, const Tizen::Base::String& value, RequestId& reqId);
233
234         /**
235         * Sets the MAP-based data control listener to this instance.
236         *
237         * @since        2.0
238         *
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.
246         */
247         result SetMapDataControlResponseListener(IMapDataControlResponseListener* pListener);
248
249 private:
250         /**
251         * This default constructor is intentionally declared as private so that only the platform can create an instance.
252         *
253         * @since        2.0
254         */
255         MapDataControl(void);
256
257         /**
258         * The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
259         *
260         * @since        2.0
261         * @remarks      This constructor is hidden.
262         */
263         MapDataControl(const MapDataControl& mapDataControl);
264
265         /**
266         * The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
267         *
268         * @since        2.0
269         * @remarks      This operator is hidden.
270         */
271         MapDataControl& operator =(const MapDataControl& mapDataControl);
272
273 private:
274         class _MapDataControlImpl * __pMapDataControlImpl;
275
276         friend class _MapDataControlImpl;
277 }; // MapDataControl
278
279 }} // Tizen::App
280
281 #endif // _FAPP_MAP_DATA_CONTROL_H_
282