Merge "Flow control for DataControl" into tizen_2.1
[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
58 class _OSP_EXPORT_ MapDataControl
59         : public Tizen::Base::Object
60 {
61
62 public:
63         /**
64         * This destructor overrides Tizen::Base::Object::~Object().
65         *
66         * @since        2.0
67         */
68         virtual ~MapDataControl(void);
69
70         /**
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.
77         *
78         * @since        2.0
79         *
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        Either of the following conditions has occurred: @n
94         *                                                                       - Access is denied due to insufficient permission.
95         *                                                                       - The application using this method is not signed with the same certificate of provider application. @b Since: @b 2.1
96         * @exception    E_MAX_EXCEEDED          Either of the following conditions has occurred: @n
97         *                                                                       - The size of sending buffer has exceeded the maximum limit.
98         *                                                                       - The number of sending requests has exceeded the maximum limit.
99         * @exception    E_SYSTEM                        A system error has occurred.
100         * @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.
101         */
102         result GetValue(const Tizen::Base::String& dataId, const Tizen::Base::String& key, RequestId& reqId, int pageNo = 1, int countPerPage = 20);
103
104         /**
105         * Adds the value associated with the specified @c key, to a key-values map owned by MAP-type data control provider. @n
106         * The %AddValue() method is asynchronous.
107         * For receiving the response from data control provider, set the listener
108         * with MapDataControl::SetMapDataControlResponseListener(). @n
109         * When the response has been received from the data control provider,
110         * the IMapDataControlResponseListener::OnMapDataControlAddValueResponseReceived() method is called.
111         *
112         * @since        2.0
113         *
114         * @return               An error code
115         * @param[in]    dataId          A string for identifying specific data, usually a registry section to add to @n
116         *                                                       The string consists of one or more components, separated by a slash('/').
117         * @param[in]    key                     A key of the value list to add
118         * @param[in]    value       A value to add
119         * @param[out]   reqId           The ID of the request
120         * @exception    E_SUCCESS                       The method is successful.
121         * @exception    E_INVALID_STATE         This instance has not been properly constructed as yet.
122         * @exception    E_ILLEGAL_ACCESS        Either of the following conditions has occurred: @n
123         *                                                                       - Access is denied due to insufficient permission.
124         *                                                                       - The application using this method is not signed with the same certificate of provider application. @b Since: @b 2.1
125         * @exception    E_MAX_EXCEEDED          Either of the following conditions has occurred: @n
126         *                                                                       - The size of sending buffer has exceeded the maximum limit.
127         *                                                                       - The number of sending requests has exceeded the maximum limit.
128         * @exception    E_SYSTEM                        A system error has occurred.
129         * @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.
130         */
131         result AddValue(const Tizen::Base::String& dataId, const Tizen::Base::String& key, const Tizen::Base::String& value, RequestId& reqId);
132
133         /**
134         * Sets the value associated with the specified @c key with a new value. @n
135         * The key-values map is owned by MAP-type data control provider. @n
136         * The %SetValue() method is asynchronous.
137         * For receiving the response from data control provider, set the listener
138         * with MapDataControl::SetMapDataControlResponseListener(). @n
139         * When the response has been received from the data control provider,
140         * the IMapDataControlResponseListener::OnMapDataControlSetValueResponseReceived() method is called.
141         *
142         * @since        2.0
143         *
144         * @return               An error code
145         * @param[in]    dataId          A string for identifying specific data, usually a registry section to update @n
146         *                                                       The string consists of one or more components, separated by a slash('/').
147         * @param[in]    key                     A key of the value to replace
148         * @param[in]    oldValue        A value to replace
149         * @param[in]    newValue        A new value to replace the existing value
150         * @param[out]   reqId           The ID of the request
151         * @exception    E_SUCCESS                       The method is successful.
152         * @exception    E_INVALID_STATE         This instance has not been properly constructed as yet.
153         * @exception    E_ILLEGAL_ACCESS        Either of the following conditions has occurred: @n
154         *                                                                       - Access is denied due to insufficient permission.
155         *                                                                       - The application using this method is not signed with the same certificate of provider application. @b Since: @b 2.1
156         * @exception    E_MAX_EXCEEDED          Either of the following conditions has occurred: @n
157         *                                                                       - The size of sending buffer has exceeded the maximum limit.
158         *                                                                       - The number of sending requests has exceeded the maximum limit.
159         * @exception    E_SYSTEM                        A system error has occurred.
160         * @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.
161         */
162         result SetValue(const Tizen::Base::String& dataId, const Tizen::Base::String& key, const Tizen::Base::String& oldValue, const Tizen::Base::String& newValue, RequestId& reqId);
163
164         /**
165         * Removes the value associated with the specified @c key, from a key-values map owned by MAP-type data control provider. @n
166         * The %RemoveValue() method is asynchronous.
167         * For receiving the response from data control provider, set the listener
168         * with MapDataControl::SetMapDataControlResponseListener(). @n
169         * When the response has been received from the data control provider,
170         * the IMapDataControlResponseListener::OnMapDataControlRemoveValueResponseReceived() method is called.
171         *
172         * @since        2.0
173         *
174         * @return               An error code
175         * @param[in]    dataId          A string for identifying specific data, usually a registry section to remove from @n
176         *                                                       The string consists of one or more components, separated by a slash('/').
177         * @param[in]    key                     A key of the value to remove
178         * @param[in]    value       A value to remove
179         * @param[out]   reqId           The ID of the request
180         * @exception    E_SUCCESS                       The method is successful.
181         * @exception    E_INVALID_STATE         This instance has not been properly constructed as yet.
182         * @exception    E_ILLEGAL_ACCESS        Either of the following conditions has occurred: @n
183         *                                                                       - Access is denied due to insufficient permission.
184         *                                                                       - The application using this method is not signed with the same certificate of provider application. @b Since: @b 2.1
185         * @exception    E_MAX_EXCEEDED          Either of the following conditions has occurred: @n
186         *                                                                       - The size of sending buffer has exceeded the maximum limit.
187         *                                                                       - The number of sending requests has exceeded the maximum limit.
188         * @exception    E_SYSTEM                        A system error has occurred.
189         * @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.
190         */
191         result RemoveValue(const Tizen::Base::String& dataId, const Tizen::Base::String& key, const Tizen::Base::String& value, RequestId& reqId);
192
193         /**
194         * Sets the MAP-based data control listener to this instance.
195         *
196         * @since        2.0
197         *
198         * @return               An error code
199         * @param[in]    pListener                       The data control callback listener @n
200         *                                                                       Some data controls need to get the callback result by implementing
201         *                                                                       the IMapDataControlResponseListener interface.
202         * @exception    E_SUCCESS                       The method is successful.
203         * @exception    E_INVALID_STATE         This instance has not been properly constructed.
204         * @exception    E_SYSTEM                        A system error has occurred.
205         */
206         result SetMapDataControlResponseListener(IMapDataControlResponseListener* pListener);
207
208 private:
209         /**
210         * This default constructor is intentionally declared as private so that only the platform can create an instance.
211         *
212         * @since        2.0
213         */
214         MapDataControl(void);
215
216         /**
217         * The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
218         *
219         * @since        2.0
220         * @remarks      This constructor is hidden.
221         */
222         MapDataControl(const MapDataControl& mapDataControl);
223
224         /**
225         * The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
226         *
227         * @since        2.0
228         * @remarks      This operator is hidden.
229         */
230         MapDataControl& operator =(const MapDataControl& mapDataControl);
231
232 private:
233         class _MapDataControlImpl * __pMapDataControlImpl;
234
235         friend class _MapDataControlImpl;
236 }; // MapDataControl
237
238 }} // Tizen::App
239
240 #endif // _FAPP_MAP_DATA_CONTROL_H_
241