//
-// Open Service Platform
// Copyright (c) 2012 Samsung Electronics Co., Ltd.
//
// Licensed under the Apache License, Version 2.0 (the License);
/**
* @class MapDataControl
- * @brief This class represents the MAP-type data control behavior.
+ * @brief This class represents the key-value structured data control behavior.
*
* @since 2.0
*
* @final This class is not intended for extension.
*
- * The %MapDataControl class represents the MAP-type data control behavior, that provides a standard mechanism
+ * The %MapDataControl class represents the key-value structured data control behavior, that provides a standard mechanism
* for accessing specific data exported by other applications.
- * Data control provider can share its own data to data control consumers.
+ * A data control provider can share its data with data control consumers.
*
* For more information on the class features, see <a href="../org.tizen.native.appprogramming/html/guide/app/data_controls.htm">Data Controls</a>.
*
* @see Tizen::App::AppManager
+ *
+ * The following example demonstrates how to use the %MapDataControl class.
+ *
+ * @code
+ *
+ * #include <FBase.h>
+ * #include <FApp.h>
+ *
+ * using namespace Tizen::Base;
+ * using namespace Tizen::App;
+ *
+ * class MyMapDataControlResponseListener:
+ * : public Tizen::App::IMapDataControlResponseListener
+ * {
+ * public:
+ * void OnMapDataControlGetValueResponseReceived(RequestId reqId, const String& providerId, const String& dataId, IList& resultValueList, bool providerResult, const String* pErrorMsg)
+ * {
+ * int count = resultValueList.GetCount();
+ * for (int i = 0; i < count; i++)
+ * {
+ * String pPerson = static_cast< String* >(resultValueList.GetAt(i));
+ * AppLog("%dth person: %ls", i, pPerson->GetPointer());
+ * }
+ * }
+ * };
+ *
+ * void
+ * MyClass::Execute(void)
+ * {
+ * String providerId(L"http://tizen.org/datacontrol/provider/example");
+ * MapDataControl* pDc = AppManager::GetMapDataControlN(providerId);
+ *
+ * MyMapDataControlResponseListener* pResponseListener = new MyMapDataControlResponseListener();
+ *
+ * pDc->SetMapDataControlResponseListener(pResponseListener);
+ *
+ * String dataId(L"test");
+ * String person(L"person");
+ * RequestId reqId;
+ *
+ * pDc->GetValue(dataId, person, reqId);
+ * }
+ *
+ * @endcode
*/
class _OSP_EXPORT_ MapDataControl
virtual ~MapDataControl(void);
/**
- * Gets the value list associated with the specified @c key, from a key-values map owned by MAP-type data control provider. @n
+ * 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
* The %GetValue() method is asynchronous.
- * For receiving the response from data control provider, set the listener
- * with MapDataControl::SetMapDataControlResponseListener(). @n
- * When the requested value list has been received from data control provider,
+ * For receiving the response from the data control provider, set the listener
+ * using the MapDataControl::SetMapDataControlResponseListener() method. @n
+ * When the requested value list has been received from the data control provider,
* the IMapDataControlResponseListener::OnMapDataControlGetValueResponseReceived() method is called.
*
* @since 2.0
*
* @return An error code
- * @param[in] dataId A string for identifying specific data, usually a registry section to get from @n
- * The string consists of one or more components, separated by a slash('/').
- * @param[in] key A key of the value list to obtain
- * @param[out] reqId The ID of the request
- * @param[in] pageNo The page number of the value set @n
- * It starts from @c 1.
- * @param[in] countPerPage The desired maximum count of the data item on the page
+ * @param[in] dataId The string that identifies the specific data, usually a registry section to get from @n
+ * The string consists of one or more components, separated by a slash('/').
+ * @param[in] key The key of the value list to obtain
+ * @param[out] reqId The ID of the request
+ * @param[in] pageNo The page number of the value set @n
+ * It starts from @c 1.
+ * @param[in] countPerPage The desired maximum count of the data items per page
* @exception E_SUCCESS The method is successful.
- * @exception E_INVALID_STATE This instance has not been properly constructed as yet.
- * @exception E_INVALID_ARG Either of the following conditions has occurred: @n
- * - The specified @c pageNo parameter is less than @c 1.
- * - The specified @c countPerPage parameter is less than @c 1.
- * @exception E_ILLEGAL_ACCESS Either of the following conditions has occurred: @n
- * - Access is denied due to insufficient permission.
- * - The application using this method is not signed with the same certificate of provider application. @b Since: @b 2.1
- * @exception E_MAX_EXCEEDED Either of the following conditions has occurred: @n
- * - The size of sending buffer has exceeded the maximum limit.
- * - The number of sending requests has exceeded the maximum limit.
+ * @exception E_INVALID_STATE This instance has not been constructed properly as yet.
+ * @exception E_INVALID_ARG Either of the following conditions has occurred:
+ * - The specified @c pageNo is less than @c 1.
+ * - The specified @c countPerPage is less than @c 1.
+ * @exception E_ILLEGAL_ACCESS Either of the following conditions has occurred:
+ * - The access is denied due to insufficient permission.
+ * - The application using this method is not signed with the same certificate as that of the provider application. @b Since: @b 2.1
+ * @exception E_MAX_EXCEEDED Either of the following conditions has occurred:
+ * - The total size of the method arguments has exceeded the maximum limit.
+ * - The number of requests sent have exceeded the maximum limit.
* @exception E_SYSTEM A system error has occurred.
- * @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.
+ * @remarks The total size of the method arguments is under 16KB because a severe system performance degradation may occur for larger messages. @n
+ * @c E_MAX_EXCEEDED may be returned for messages over 16KB.
*/
result GetValue(const Tizen::Base::String& dataId, const Tizen::Base::String& key, RequestId& reqId, int pageNo = 1, int countPerPage = 20);
/**
- * Adds the value associated with the specified @c key, to a key-values map owned by MAP-type data control provider. @n
+ * Adds the value associated with the specified @c key, to the key-values map owned by the key-value structured data control provider. @n
* The %AddValue() method is asynchronous.
- * For receiving the response from data control provider, set the listener
- * with MapDataControl::SetMapDataControlResponseListener(). @n
+ * For receiving the response from the data control provider, set the listener
+ * using the MapDataControl::SetMapDataControlResponseListener() method. @n
* When the response has been received from the data control provider,
* the IMapDataControlResponseListener::OnMapDataControlAddValueResponseReceived() method is called.
*
* @since 2.0
*
* @return An error code
- * @param[in] dataId A string for identifying specific data, usually a registry section to add to @n
- * The string consists of one or more components, separated by a slash('/').
- * @param[in] key A key of the value list to add
- * @param[in] value A value to add
- * @param[out] reqId The ID of the request
+ * @param[in] dataId The string that identifies the specific data, usually a registry section to add to @n
+ * The string consists of one or more components, separated by a slash('/').
+ * @param[in] key The key of the value list to add
+ * @param[in] value The value to add
+ * @param[out] reqId The ID of the request
* @exception E_SUCCESS The method is successful.
- * @exception E_INVALID_STATE This instance has not been properly constructed as yet.
- * @exception E_ILLEGAL_ACCESS Either of the following conditions has occurred: @n
- * - Access is denied due to insufficient permission.
- * - The application using this method is not signed with the same certificate of provider application. @b Since: @b 2.1
- * @exception E_MAX_EXCEEDED Either of the following conditions has occurred: @n
- * - The size of sending buffer has exceeded the maximum limit.
- * - The number of sending requests has exceeded the maximum limit.
+ * @exception E_INVALID_STATE This instance has not been constructed properly as yet.
+ * @exception E_ILLEGAL_ACCESS Either of the following conditions has occurred:
+ * - The access is denied due to insufficient permission.
+ * - The application using this method is not signed with the same certificate as that of the provider application. @b Since: @b 2.1
+ * @exception E_MAX_EXCEEDED Either of the following conditions has occurred:
+ * - The total size of the method arguments has exceeded the maximum limit.
+ * - The number of requests sent have exceeded the maximum limit.
* @exception E_SYSTEM A system error has occurred.
- * @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.
+ * @remarks The total size of the method arguments is under 16KB because a severe system performance degradation may occur for larger messages. @n
+ * @c E_MAX_EXCEEDED may be returned for messages over 16KB.
*/
result AddValue(const Tizen::Base::String& dataId, const Tizen::Base::String& key, const Tizen::Base::String& value, RequestId& reqId);
/**
- * Sets the value associated with the specified @c key with a new value. @n
- * The key-values map is owned by MAP-type data control provider. @n
+ * Sets the value associated with the specified @c key to a new value. @n
+ * The key-values map is owned by the key-value structured data control provider. @n
* The %SetValue() method is asynchronous.
- * For receiving the response from data control provider, set the listener
- * with MapDataControl::SetMapDataControlResponseListener(). @n
+ * For receiving the response from the data control provider, set the listener
+ * using the MapDataControl::SetMapDataControlResponseListener() method. @n
* When the response has been received from the data control provider,
* the IMapDataControlResponseListener::OnMapDataControlSetValueResponseReceived() method is called.
*
* @since 2.0
*
* @return An error code
- * @param[in] dataId A string for identifying specific data, usually a registry section to update @n
- * The string consists of one or more components, separated by a slash('/').
- * @param[in] key A key of the value to replace
- * @param[in] oldValue A value to replace
- * @param[in] newValue A new value to replace the existing value
- * @param[out] reqId The ID of the request
+ * @param[in] dataId The string that identifies the specific data, usually a registry section to update @n
+ * The string consists of one or more components, separated by a slash('/').
+ * @param[in] key The key of the value to replace
+ * @param[in] oldValue The value to replace
+ * @param[in] newValue The new value that replaces the existing value
+ * @param[out] reqId The ID of the request
* @exception E_SUCCESS The method is successful.
- * @exception E_INVALID_STATE This instance has not been properly constructed as yet.
- * @exception E_ILLEGAL_ACCESS Either of the following conditions has occurred: @n
- * - Access is denied due to insufficient permission.
- * - The application using this method is not signed with the same certificate of provider application. @b Since: @b 2.1
- * @exception E_MAX_EXCEEDED Either of the following conditions has occurred: @n
- * - The size of sending buffer has exceeded the maximum limit.
- * - The number of sending requests has exceeded the maximum limit.
+ * @exception E_INVALID_STATE This instance has not been constructed properly as yet.
+ * @exception E_ILLEGAL_ACCESS Either of the following conditions has occurred:
+ * - The access is denied due to insufficient permission.
+ * - The application using this method is not signed with the same certificate as that of the provider application. @b Since: @b 2.1
+ * @exception E_MAX_EXCEEDED Either of the following conditions has occurred:
+ * - The total size of the method arguments has exceeded the maximum limit.
+ * - The number of requests sent have exceeded the maximum limit.
* @exception E_SYSTEM A system error has occurred.
- * @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.
+ * @remarks The total size of the method arguments is under 16KB because a severe system performance degradation may occur for larger messages. @n
+ * @c E_MAX_EXCEEDED may be returned for messages over 16KB.
*/
result SetValue(const Tizen::Base::String& dataId, const Tizen::Base::String& key, const Tizen::Base::String& oldValue, const Tizen::Base::String& newValue, RequestId& reqId);
/**
- * Removes the value associated with the specified @c key, from a key-values map owned by MAP-type data control provider. @n
+ * Removes the value associated with the specified @c key, from the key-values map owned by the key-value structured data control provider. @n
* The %RemoveValue() method is asynchronous.
- * For receiving the response from data control provider, set the listener
- * with MapDataControl::SetMapDataControlResponseListener(). @n
+ * For receiving the response from the data control provider, set the listener
+ * using the MapDataControl::SetMapDataControlResponseListener() method. @n
* When the response has been received from the data control provider,
* the IMapDataControlResponseListener::OnMapDataControlRemoveValueResponseReceived() method is called.
*
* @since 2.0
*
* @return An error code
- * @param[in] dataId A string for identifying specific data, usually a registry section to remove from @n
- * The string consists of one or more components, separated by a slash('/').
- * @param[in] key A key of the value to remove
- * @param[in] value A value to remove
- * @param[out] reqId The ID of the request
+ * @param[in] dataId The string that identifies the specific data, usually a registry section to remove from @n
+ * The string consists of one or more components, separated by a slash('/').
+ * @param[in] key The key of the value to remove
+ * @param[in] value The value to remove
+ * @param[out] reqId The ID of the request
* @exception E_SUCCESS The method is successful.
- * @exception E_INVALID_STATE This instance has not been properly constructed as yet.
- * @exception E_ILLEGAL_ACCESS Either of the following conditions has occurred: @n
- * - Access is denied due to insufficient permission.
- * - The application using this method is not signed with the same certificate of provider application. @b Since: @b 2.1
- * @exception E_MAX_EXCEEDED Either of the following conditions has occurred: @n
- * - The size of sending buffer has exceeded the maximum limit.
- * - The number of sending requests has exceeded the maximum limit.
+ * @exception E_INVALID_STATE This instance has not been constructed properly as yet.
+ * @exception E_ILLEGAL_ACCESS Either of the following conditions has occurred:
+ * - The access is denied due to insufficient permission.
+ * - The application using this method is not signed with the same certificate as that of the provider application. @b Since: @b 2.1
+ * @exception E_MAX_EXCEEDED Either of the following conditions has occurred:
+ * - The total size of the method arguments has exceeded the maximum limit.
+ * - The number of requests sent have exceeded the maximum limit.
* @exception E_SYSTEM A system error has occurred.
- * @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.
+ * @remarks The total size of the method arguments is under 16KB because a severe system performance degradation may occur for larger messages. @n
+ * @c E_MAX_EXCEEDED may be returned for messages over 16KB.
*/
result RemoveValue(const Tizen::Base::String& dataId, const Tizen::Base::String& key, const Tizen::Base::String& value, RequestId& reqId);
/**
- * Sets the MAP-based data control listener to this instance.
+ * Sets the MAP-based data control listener for this instance.
*
* @since 2.0
*
* Some data controls need to get the callback result by implementing
* the IMapDataControlResponseListener interface.
* @exception E_SUCCESS The method is successful.
- * @exception E_INVALID_STATE This instance has not been properly constructed.
+ * @exception E_INVALID_STATE This instance has not been constructed properly as yet.
* @exception E_SYSTEM A system error has occurred.
*/
result SetMapDataControlResponseListener(IMapDataControlResponseListener* pListener);
projects / platform / framework / native / appfw.git / blobdiff