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