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