inc/FAppMapDataControl.h

   1 //
   2 // Copyright (c) 2012 Samsung Electronics Co., Ltd.
   3 //
   4 // Licensed under the Apache License, Version 2.0 (the License);
   5 // you may not use this file except in compliance with the License.
   6 // You may obtain a copy of the License at
   7 //
   8 //     http://www.apache.org/licenses/LICENSE-2.0
   9 //
  10 // Unless required by applicable law or agreed to in writing, software
  11 // distributed under the License is distributed on an "AS IS" BASIS,
  12 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13 // See the License for the specific language governing permissions and
  14 // limitations under the License.
  15 //
  16
  17 /**
  18  * @file    FAppMapDataControl.h
  19  * @brief   This is the header file for the %MapDataControl class.
  20  *
  21  * This header file contains the declarations of the %MapDataControl class.
  22  */
  23
  24 #ifndef _FAPP_MAP_DATA_CONTROL_H_
  25 #define _FAPP_MAP_DATA_CONTROL_H_
  26
  27 #include <FBaseDataType.h>
  28 #include <FBaseObject.h>
  29
  30 namespace Tizen { namespace Base
  31 {
  32 class String;
  33 }}
  34
  35 namespace Tizen { namespace App
  36 {
  37
  38 class IMapDataControlResponseListener;
  39
  40 /**
  41  * @class   MapDataControl
  42  * @brief   This class represents the key-value structured data control behavior.
  43  *
  44  * @since       2.0
  45  *
  46  * @final   This class is not intended for extension.
  47  *
  48  * The %MapDataControl class represents the key-value structured data control behavior, that provides a standard mechanism
  49  * for accessing specific data exported by other applications.
  50  * A data control provider can share its data with data control consumers.
  51  *
  52  * For more information on the class features, see <a href="../org.tizen.native.appprogramming/html/guide/app/data_controls.htm">Data Controls</a>.
  53  *
  54  * @see Tizen::App::AppManager
  55  *
  56  * The following example demonstrates how to use the %MapDataControl class.
  57  *
  58  * @code
  59  *
  60  * #include <FBase.h>
  61  * #include <FApp.h>
  62  *
  63  * using namespace Tizen::Base;
  64  * using namespace Tizen::App;
  65  *
  66  * class MyMapDataControlResponseListener:
  67  *      : public Tizen::App::IMapDataControlResponseListener
  68  * {
  69  * public:
  70  *      void OnMapDataControlGetValueResponseReceived(RequestId reqId, const String& providerId, const String& dataId, IList& resultValueList, bool providerResult, const String* pErrorMsg)
  71  *      {
  72  *              int count = resultValueList.GetCount();
  73  *              for (int i = 0; i < count; i++)
  74  *              {
  75  *                      String pPerson = static_cast< String* >(resultValueList.GetAt(i));
  76  *                      AppLog("%dth person: %ls", i, pPerson->GetPointer());
  77  *              }
  78  *      }
  79  * };
  80  *
  81  * void
  82  * MyClass::Execute(void)
  83  * {
  84  *              String providerId(L"http://tizen.org/datacontrol/provider/example");
  85  *              MapDataControl* pDc = AppManager::GetMapDataControlN(providerId);
  86  *
  87  *              MyMapDataControlResponseListener* pResponseListener = new MyMapDataControlResponseListener();
  88  *
  89  *              pDc->SetMapDataControlResponseListener(pResponseListener);
  90  *
  91  *              String dataId(L"test");
  92  *              String person(L"person");
  93  *              RequestId reqId;
  94  *
  95  *              pDc->GetValue(dataId, person, reqId);
  96  * }
  97  *
  98  * @endcode
  99  */
 100
 101 class _OSP_EXPORT_ MapDataControl
 102         : public Tizen::Base::Object
 103 {
 104
 105 public:
 106         /**
 107         * This destructor overrides Tizen::Base::Object::~Object().
 108         *
 109         * @since        2.0
 110         */
 111         virtual ~MapDataControl(void);
 112
 113         /**
 114         * Gets the value list associated with the specified @c key, from the key-values map owned by the key-value structured data control provider. @n
 115         * The %GetValue() method is asynchronous.
 116         * For receiving the response from the data control provider, set the listener
 117         * using the MapDataControl::SetMapDataControlResponseListener() method. @n
 118         * When the requested value list has been received from the data control provider,
 119         * the IMapDataControlResponseListener::OnMapDataControlGetValueResponseReceived() method is called.
 120         *
 121         * @since        2.0
 122         * @privlevel    public
 123         * @privilege    %http://tizen.org/privilege/datacontrol.consumer
 124         *
 125         * @return               An error code
 126         * @param[in]    dataId                          The string that identifies the specific data, usually a registry section to get from @n
 127         *                                       The string consists of one or more components, separated by a slash('/').
 128         * @param[in]    key                     The key of the value list to obtain
 129         * @param[out]   reqId                           The ID of the request
 130         * @param[in]    pageNo                          The page number of the value set @n
 131         *                                                                       It starts from @c 1.
 132         * @param[in]    countPerPage            The desired maximum count of the data items per page
 133         * @exception    E_SUCCESS                       The method is successful.
 134         * @exception    E_INVALID_STATE         This instance has not been constructed properly as yet.
 135         * @exception    E_INVALID_ARG           Either of the following conditions has occurred:
 136         *                                                                       - The specified @c pageNo is less than @c 1.
 137         *                                                                       - The specified @c countPerPage is less than @c 1.
 138         * @exception    E_ILLEGAL_ACCESS        Either of the following conditions has occurred:
 139         *                                                                       - The access is denied due to insufficient permission.
 140         *                                                                       - The application using this method is not signed with the same certificate as that of the provider application. @b Since: @b 2.1
 141         * @exception    E_MAX_EXCEEDED          Either of the following conditions has occurred:
 142         *                                                                       - The total size of the method arguments has exceeded the maximum limit.
 143         *                                                                       - The number of requests sent have exceeded the maximum limit.
 144         * @exception    E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
 145         * @exception    E_SYSTEM                        A system error has occurred.
 146         * @remarks      The total size of the method arguments is under 16KB because a severe system performance degradation may occur for larger messages. @n
 147         *                       @c E_MAX_EXCEEDED may be returned for messages over 16KB.
 148         */
 149         result GetValue(const Tizen::Base::String& dataId, const Tizen::Base::String& key, RequestId& reqId, int pageNo = 1, int countPerPage = 20);
 150
 151         /**
 152         * Adds the value associated with the specified @c key, to the key-values map owned by the key-value structured data control provider. @n
 153         * The %AddValue() method is asynchronous.
 154         * For receiving the response from the data control provider, set the listener
 155         * using the MapDataControl::SetMapDataControlResponseListener() method. @n
 156         * When the response has been received from the data control provider,
 157         * the IMapDataControlResponseListener::OnMapDataControlAddValueResponseReceived() method is called.
 158         *
 159         * @since        2.0
 160         * @privlevel    public
 161         * @privilege    %http://tizen.org/privilege/datacontrol.consumer
 162         *
 163         * @return               An error code
 164         * @param[in]    dataId                          The string that identifies the specific data, usually a registry section to add to @n
 165         *                                                                       The string consists of one or more components, separated by a slash('/').
 166         * @param[in]    key                                     The key of the value list to add
 167         * @param[in]    value                           The value to add
 168         * @param[out]   reqId                           The ID of the request
 169         * @exception    E_SUCCESS                       The method is successful.
 170         * @exception    E_INVALID_STATE         This instance has not been constructed properly as yet.
 171         * @exception    E_ILLEGAL_ACCESS        Either of the following conditions has occurred:
 172         *                                                                       - The access is denied due to insufficient permission.
 173         *                                                                       - The application using this method is not signed with the same certificate as that of the provider application. @b Since: @b 2.1
 174         * @exception    E_MAX_EXCEEDED          Either of the following conditions has occurred:
 175         *                                                                       - The total size of the method arguments has exceeded the maximum limit.
 176         *                                                                       - The number of requests sent have exceeded the maximum limit.
 177         * @exception    E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
 178         * @exception    E_SYSTEM                        A system error has occurred.
 179         * @remarks      The total size of the method arguments is under 16KB because a severe system performance degradation may occur for larger messages. @n
 180         *                       @c E_MAX_EXCEEDED may be returned for messages over 16KB.
 181         */
 182         result AddValue(const Tizen::Base::String& dataId, const Tizen::Base::String& key, const Tizen::Base::String& value, RequestId& reqId);
 183
 184         /**
 185         * Sets the value associated with the specified @c key to a new value. @n
 186         * The key-values map is owned by the key-value structured data control provider. @n
 187         * The %SetValue() method is asynchronous.
 188         * For receiving the response from the data control provider, set the listener
 189         * using the MapDataControl::SetMapDataControlResponseListener() method. @n
 190         * When the response has been received from the data control provider,
 191         * the IMapDataControlResponseListener::OnMapDataControlSetValueResponseReceived() method is called.
 192         *
 193         * @since        2.0
 194         * @privlevel    public
 195         * @privilege    %http://tizen.org/privilege/datacontrol.consumer
 196         *
 197         * @return               An error code
 198         * @param[in]    dataId                          The string that identifies the specific data, usually a registry section to update @n
 199         *                                                                       The string consists of one or more components, separated by a slash('/').
 200         * @param[in]    key                                     The key of the value to replace
 201         * @param[in]    oldValue                        The value to replace
 202         * @param[in]    newValue                        The new value that replaces the existing value
 203         * @param[out]   reqId                           The ID of the request
 204         * @exception    E_SUCCESS                       The method is successful.
 205         * @exception    E_INVALID_STATE         This instance has not been constructed properly as yet.
 206         * @exception    E_ILLEGAL_ACCESS        Either of the following conditions has occurred:
 207         *                                                                       - The access is denied due to insufficient permission.
 208         *                                                                       - The application using this method is not signed with the same certificate as that of the provider application. @b Since: @b 2.1
 209         * @exception    E_MAX_EXCEEDED          Either of the following conditions has occurred:
 210         *                                                                       - The total size of the method arguments has exceeded the maximum limit.
 211         *                                                                       - The number of requests sent have exceeded the maximum limit.
 212         * @exception    E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
 213         * @exception    E_SYSTEM                        A system error has occurred.
 214         * @remarks      The total size of the method arguments is under 16KB because a severe system performance degradation may occur for larger messages. @n
 215         *                       @c E_MAX_EXCEEDED may be returned for messages over 16KB.
 216         */
 217         result SetValue(const Tizen::Base::String& dataId, const Tizen::Base::String& key, const Tizen::Base::String& oldValue, const Tizen::Base::String& newValue, RequestId& reqId);
 218
 219         /**
 220         * Removes the value associated with the specified @c key, from the key-values map owned by the key-value structured data control provider. @n
 221         * The %RemoveValue() method is asynchronous.
 222         * For receiving the response from the data control provider, set the listener
 223         * using the MapDataControl::SetMapDataControlResponseListener() method. @n
 224         * When the response has been received from the data control provider,
 225         * the IMapDataControlResponseListener::OnMapDataControlRemoveValueResponseReceived() method is called.
 226         *
 227         * @since        2.0
 228         * @privlevel    public
 229         * @privilege    %http://tizen.org/privilege/datacontrol.consumer
 230         *
 231         * @return               An error code
 232         * @param[in]    dataId                          The string that identifies the specific data, usually a registry section to remove from @n
 233         *                                                                       The string consists of one or more components, separated by a slash('/').
 234         * @param[in]    key                                     The key of the value to remove
 235         * @param[in]    value                   The value to remove
 236         * @param[out]   reqId                           The ID of the request
 237         * @exception    E_SUCCESS                       The method is successful.
 238         * @exception    E_INVALID_STATE         This instance has not been constructed properly as yet.
 239         * @exception    E_ILLEGAL_ACCESS        Either of the following conditions has occurred:
 240         *                                                                       - The access is denied due to insufficient permission.
 241         *                                                                       - The application using this method is not signed with the same certificate as that of the provider application. @b Since: @b 2.1
 242         * @exception    E_MAX_EXCEEDED          Either of the following conditions has occurred:
 243         *                                                                       - The total size of the method arguments has exceeded the maximum limit.
 244         *                                                                       - The number of requests sent have exceeded the maximum limit.
 245         * @exception    E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
 246         * @exception    E_SYSTEM                        A system error has occurred.
 247         * @remarks      The total size of the method arguments is under 16KB because a severe system performance degradation may occur for larger messages. @n
 248         *                       @c E_MAX_EXCEEDED may be returned for messages over 16KB.
 249         */
 250         result RemoveValue(const Tizen::Base::String& dataId, const Tizen::Base::String& key, const Tizen::Base::String& value, RequestId& reqId);
 251
 252         /**
 253         * Sets the MAP-based data control listener for this instance.
 254         *
 255         * @since        2.0
 256         *
 257         * @return               An error code
 258         * @param[in]    pListener                       The data control callback listener @n
 259         *                                                                       Some data controls need to get the callback result by implementing
 260         *                                                                       the IMapDataControlResponseListener interface.
 261         * @exception    E_SUCCESS                       The method is successful.
 262         * @exception    E_INVALID_STATE         This instance has not been constructed properly as yet.
 263         * @exception    E_SYSTEM                        A system error has occurred.
 264         */
 265         result SetMapDataControlResponseListener(IMapDataControlResponseListener* pListener);
 266
 267 private:
 268         /**
 269         * This default constructor is intentionally declared as private so that only the platform can create an instance.
 270         *
 271         * @since        2.0
 272         */
 273         MapDataControl(void);
 274
 275         /**
 276         * The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
 277         *
 278         * @since        2.0
 279         * @remarks      This constructor is hidden.
 280         */
 281         MapDataControl(const MapDataControl& mapDataControl);
 282
 283         /**
 284         * The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
 285         *
 286         * @since        2.0
 287         * @remarks      This operator is hidden.
 288         */
 289         MapDataControl& operator =(const MapDataControl& mapDataControl);
 290
 291 private:
 292         class _MapDataControlImpl * __pMapDataControlImpl;
 293
 294         friend class _MapDataControlImpl;
 295 }; // MapDataControl
 296
 297 }} // Tizen::App
 298
 299 #endif // _FAPP_MAP_DATA_CONTROL_H_
 300