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