X-Git-Url: http://review.tizen.org/git/?a=blobdiff_plain;f=inc%2FFAppMapDataControl.h;h=f903e228ffdc7e9e8dd2918858efdb3b2a120ea1;hb=0a3f6678afe1bdff47660be2598a82d6d037c161;hp=a840b03303a8a6205eeff4206c4884ba1a131545;hpb=bad4dc664cab035e50c39096818c3df3a80b4bb2;p=platform%2Fframework%2Fnative%2Fappfw.git diff --git a/inc/FAppMapDataControl.h b/inc/FAppMapDataControl.h index a840b03..f903e22 100755 --- a/inc/FAppMapDataControl.h +++ b/inc/FAppMapDataControl.h @@ -1,5 +1,4 @@ // -// Open Service Platform // Copyright (c) 2012 Samsung Electronics Co., Ltd. // // Licensed under the Apache License, Version 2.0 (the License); @@ -40,19 +39,63 @@ class IMapDataControlResponseListener; /** * @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 Data Controls. * * @see Tizen::App::AppManager + * + * The following example demonstrates how to use the %MapDataControl class. + * + * @code + * + * #include + * #include + * + * 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 @@ -68,130 +111,134 @@ public: 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 * @@ -200,7 +247,7 @@ public: * 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);