From 85ebebac653bc2aa9f8e1ecc4cd7ac9d06da0be5 Mon Sep 17 00:00:00 2001 From: coderhyme Date: Sun, 28 Feb 2016 16:30:29 -0800 Subject: [PATCH] Updated api description for the client side of RE. Change-Id: I52babb04f0568dfcac22f176774111dc5033284a Signed-off-by: coderhyme Reviewed-on: https://gerrit.iotivity.org/gerrit/5245 Tested-by: jenkins-iotivity Reviewed-by: Uze Choi --- .../include/RCSDiscoveryManager.h | 24 ++-- .../include/RCSRemoteResourceObject.h | 159 ++++++++++++++++++--- .../src/resourceClient/RCSRemoteResourceObject.cpp | 51 ++----- .../unittests/ResourceClientTest.cpp | 2 +- 4 files changed, 165 insertions(+), 71 deletions(-) diff --git a/service/resource-encapsulation/include/RCSDiscoveryManager.h b/service/resource-encapsulation/include/RCSDiscoveryManager.h index 18572b5..71b260a 100644 --- a/service/resource-encapsulation/include/RCSDiscoveryManager.h +++ b/service/resource-encapsulation/include/RCSDiscoveryManager.h @@ -102,7 +102,7 @@ namespace OIC /** * Discovers resources of interest, regardless of uri and resource type. - * It is Consistently discovering resources until the discovery task is canceled. + * It will consistently discover resources until the discovery task is canceled. * * @param address A RCSAddress object * @param cb A callback to obtain discovered resource @@ -117,7 +117,7 @@ namespace OIC /** * Discovers resources of interest, regardless of resource type. - * It is Consistently discovering resources until the discovery task is canceled. + * It will consistently discover resources until the discovery task is canceled. * * @param address A RCSAddress object * @param relativeUri The relative uri of resource to be searched @@ -133,7 +133,7 @@ namespace OIC /** * Discovers resources of interest by resource type. - * It is Consistently discovering resources until the discovery task is canceled. + * It will consistently discover resources until the discovery task is canceled. * * @param address A RCSAddress object * @param resourceType Resource Type @@ -148,16 +148,16 @@ namespace OIC const std::string& resourceType, ResourceDiscoveredCallback cb); /** - * Discovers resources of interest by resource type. - * It is Consistently discovering resources until the discovery task is canceled. + * Discovers resources of interest by resource types. + * It will consistently discover resources until the discovery task is canceled. * * @param address A RCSAddress object * @param resourceTypes List of Resource Types * @param cb A callback to obtain discovered resource * * @throws InvalidParameterException If cb is empty. - * @throws InvalidParameterException If resourceType's size is than 2, - * at least one of resource type is empty. + * @throws RCSBadRequestException If resourceTypes contain more than one element and + * any of them is empty. * * @note The callback will be invoked in an internal thread. * @note If resourceTypes is empty, discovers resource by all resource types. @@ -168,8 +168,8 @@ namespace OIC ResourceDiscoveredCallback cb); /** - * Discovers resources of interest by resource types with provided relativeUri. - * It is Consistently discovering resources until the discovery task is canceled. + * Discovers resources of interest by a resource type with provided relativeUri. + * It will consistently discover resources until the discovery task is canceled. * * @param address A RCSAddress object * @param relativeUri The relative uri of resource to be searched @@ -187,7 +187,7 @@ namespace OIC /** * Discovers resources of interest by resource types with provided relativeUri. - * It is Consistently discovering resources until the discovery task is canceled. + * It will consistently discover resources until the discovery task is canceled. * * @param address A RCSAddress object * @param relativeUri The relative uri of resource to be searched @@ -195,8 +195,8 @@ namespace OIC * @param cb A callback to obtain discovered resource * * @throws InvalidParameterException If cb is empty. - * @throws InvalidParameterException If resourceType's size is than 2, - * at least one of resource type is empty. + * @throws RCSBadRequestException If resourceTypes contain more than one element and + * any of them is empty. * * @note The callback will be invoked in an internal thread. * @note If resourceTypes is empty, discovers resource by all resource types. diff --git a/service/resource-encapsulation/include/RCSRemoteResourceObject.h b/service/resource-encapsulation/include/RCSRemoteResourceObject.h index 5960766..5a27f0a 100644 --- a/service/resource-encapsulation/include/RCSRemoteResourceObject.h +++ b/service/resource-encapsulation/include/RCSRemoteResourceObject.h @@ -83,27 +83,65 @@ namespace OIC class PrimitiveResource; + /** + * This is to specify query parameters for requests to the server. + * + * @see RCSRemoteResourceObject + */ class RCSQueryParams { public: typedef std::unordered_map< std::string, std::string > Map; public: - RCSQueryParams& setResourceInterface(const std::string&); - RCSQueryParams& setResourceInterface(std::string&&); - RCSQueryParams& setResuorceType(const std::string&); - RCSQueryParams& setResuorceType(std::string&&); + /** + * Sets an interface of the resource to operate on + * + * @param interface interface + */ + RCSQueryParams& setResourceInterface(std::string interface); + + /** + * Sets a resource type of the resource to operate on + * + * @param type resource type + */ + RCSQueryParams& setResourceType(std::string type); - RCSQueryParams& put(const std::string&, const std::string&); - RCSQueryParams& put(std::string&&, std::string&&); - RCSQueryParams& put(const std::string&, std::string&&); - RCSQueryParams& put(std::string&&, const std::string&); + /** + * Sets a resource type of the resource to operate on + * + * @param key key to be inserted + * @param value value to be inserted + * + * @note "rt" and "if" are reserved, so you should avoid them as a key. + * + */ + RCSQueryParams& put(std::string key, std::string value); + /** + * Returns the resource interface. + */ std::string getResourceInterface() const; + + /** + * Returns the resource type. + */ std::string getResourceType() const; - std::string get(const std::string&) const; + /** + * Returns a value. + * + * @param key key of the element whose mapped value is accessed. + * + * @throws InvalidKeyException If @a key doesn't match the key of any value. + */ + std::string get(const std::string& key) const; + + /** + * Returns all params. + */ const Map& getAll() const; private: @@ -156,8 +194,17 @@ namespace OIC typedef std::function< void(const RCSResourceAttributes& attrs, int eCode) > RemoteAttributesGetCallback; - typedef std::function< void(const HeaderOpts&, const RCSRepresentation& rep, int eCode) > - GetCallback; + /** + * Callback definition to be invoked when the response of get is received. + * + * @param HeaderOpts + * @param rep the result representation + * @param eCode the error code received from the resource + * + * @see get + */ + typedef std::function< void(const HeaderOpts& headerOpts, + const RCSRepresentation& rep, int eCode) > GetCallback; /** * Callback definition to be invoked when the response of setRemoteAttributes is @@ -168,11 +215,20 @@ namespace OIC * * @see setRemoteAttributes */ - typedef std::function< void(const RCSResourceAttributes&, int) > + typedef std::function< void(const RCSResourceAttributes& attrs, int eCode) > RemoteAttributesSetCallback; - typedef std::function< void(const HeaderOpts&, const RCSRepresentation& rep, int eCode) > - SetCallback; + /** + * Callback definition to be invoked when the response of set is received. + * + * @param HeaderOpts + * @param rep the result representation + * @param eCode the error code received from the resource + * + * @see set + */ + typedef std::function< void(const HeaderOpts& headerOpts, + const RCSRepresentation& rep, int eCode) > SetCallback; private: typedef int CacheID; @@ -185,7 +241,13 @@ namespace OIC ~RCSRemoteResourceObject(); - static RCSRemoteResourceObject::Ptr fromOCResource(std::shared_ptr< OC::OCResource >); + /** + * Creates an instance from an OCResource instance. + * + * @throw RCSInvalidParameterException If ocResource is nullptr. + */ + static RCSRemoteResourceObject::Ptr fromOCResource( + std::shared_ptr< OC::OCResource > ocResource); /** * Returns whether monitoring is enabled. @@ -351,19 +413,41 @@ namespace OIC * Gets resource attributes directly from the server. * * This API send a get request to the resource of interest and provides - * the attributes to the caller in the RemoteAttributesReceivedCallback. + * the attributes to the caller in the RemoteAttributesGetCallback. * * @throws PlatformException If the operation failed * @throws InvalidParameterException If cb is an empty function or null. * - * @see RCSResourceAttributes::Value - * * @note The callback will be invoked in an internal thread. */ void getRemoteAttributes(RemoteAttributesGetCallback cb); + /** + * Gets resource representation with empty query parameters directly from the server. + * + * @param cb A callback to receive the response. + * + * @throws PlatformException If the operation failed + * @throws InvalidParameterException If cb is an empty function or null. + * + * @note The callback will be invoked in an internal thread. + */ void get(GetCallback cb); - void get(const RCSQueryParams&, GetCallback cb); + + /** + * Gets resource representation directly from the server. + * + * The response could be different by the query parameters, it depends on server. + * + * @param queryParams Query parameters + * @param cb A callback to receive the response. + * + * @throws PlatformException If the operation failed + * @throws InvalidParameterException If cb is an empty function or null. + * + * @note The callback will be invoked in an internal thread. + */ + void get(const RCSQueryParams& queryParams, GetCallback cb); /** * Sends a set request with resource attributes to the server. @@ -384,8 +468,43 @@ namespace OIC void setRemoteAttributes(const RCSResourceAttributes& attributes, RemoteAttributesSetCallback cb); + /** + * Sends a set request with resource attributes to the server. + * + * The SetRequest behavior depends on query parameters and the server. + * + * @param attributes Attributes to set + * @param cb A callback to receive the response. + * + * @throws PlatformException If the operation failed + * @throws InvalidParameterException If cb is an empty function or null. + * + * @see RCSResourceObject + * @see RCSResourceObject::SetRequestHandlerPolicy + * + * @note The callback will be invoked in an internal thread. + */ void set(const RCSResourceAttributes& attributes, SetCallback cb); - void set(const RCSQueryParams&, const RCSResourceAttributes& attributes, SetCallback cb); + + /** + * Sends a set request with resource attributes to the server. + * + * The SetRequest behavior depends on query parameters and the server. + * + * @param queryParams Query parameters + * @param attributes Attributes to set + * @param cb A callback to receive the response. + * + * @throws PlatformException If the operation failed + * @throws InvalidParameterException If cb is an empty function or null. + * + * @see RCSResourceObject + * @see RCSResourceObject::SetRequestHandlerPolicy + * + * @note The callback will be invoked in an internal thread. + */ + void set(const RCSQueryParams& queryParams, const RCSResourceAttributes& attributes, + SetCallback cb); /** * Returns the uri of the resource. diff --git a/service/resource-encapsulation/src/resourceClient/RCSRemoteResourceObject.cpp b/service/resource-encapsulation/src/resourceClient/RCSRemoteResourceObject.cpp index f87bce5..54e7ce8 100644 --- a/service/resource-encapsulation/src/resourceClient/RCSRemoteResourceObject.cpp +++ b/service/resource-encapsulation/src/resourceClient/RCSRemoteResourceObject.cpp @@ -121,54 +121,24 @@ namespace OIC namespace Service { - RCSQueryParams& RCSQueryParams::setResourceInterface(const std::string& resourceInterface) - { - m_resourceInterface = resourceInterface; - return *this; - } - - RCSQueryParams& RCSQueryParams::setResourceInterface(std::string&& resourceInterface) + RCSQueryParams& RCSQueryParams::setResourceInterface(std::string resourceInterface) { m_resourceInterface = std::move(resourceInterface); return *this; } - RCSQueryParams& RCSQueryParams::setResuorceType(const std::string& resourceType) - { - m_resourceType = resourceType; - return *this; - } - - RCSQueryParams& RCSQueryParams::setResuorceType(std::string&& resourceType) + RCSQueryParams& RCSQueryParams::setResourceType(std::string resourceType) { m_resourceType = std::move(resourceType); return *this; } - RCSQueryParams& RCSQueryParams::put(const std::string& key, const std::string& value) - { - m_map[key] = value; - return *this; - } - - RCSQueryParams& RCSQueryParams::put(std::string&& key, std::string&& value) + RCSQueryParams& RCSQueryParams::put(std::string key, std::string value) { m_map[std::move(key)] = std::move(value); return *this; } - RCSQueryParams& RCSQueryParams::put(const std::string& key, std::string&& value) - { - m_map[key] = std::move(value); - return *this; - } - - RCSQueryParams& RCSQueryParams::put(std::string&& key, const std::string& value) - { - m_map[std::move(key)] = value; - return *this; - } - std::string RCSQueryParams::getResourceInterface() const { return m_resourceInterface; @@ -181,7 +151,14 @@ namespace OIC std::string RCSQueryParams::get(const std::string& key) const { - return m_map.at(key); + try + { + return m_map.at(key); + } + catch (const std::out_of_range&) + { + throw RCSInvalidKeyException(key + " is an invalid key"); + } } const RCSQueryParams::Map& RCSQueryParams::getAll() const @@ -191,8 +168,8 @@ namespace OIC RCSRemoteResourceObject::RCSRemoteResourceObject( - std::shared_ptr< PrimitiveResource > pResource) : - m_primitiveResource{ pResource }, + std::shared_ptr< PrimitiveResource > primtiveResource) : + m_primitiveResource{ primtiveResource }, m_cacheId{ }, m_brokerId{ } { @@ -435,8 +412,6 @@ namespace OIC const auto& paramMap = queryParams.getAll(); - std::cout << queryParams.getResourceInterface() << "??\n"; - m_primitiveResource->requestGetWith( queryParams.getResourceType(), queryParams.getResourceInterface(), OC::QueryParamsMap{ paramMap.begin(), paramMap.end() }, diff --git a/service/resource-encapsulation/unittests/ResourceClientTest.cpp b/service/resource-encapsulation/unittests/ResourceClientTest.cpp index 5c47717..341d365 100644 --- a/service/resource-encapsulation/unittests/ResourceClientTest.cpp +++ b/service/resource-encapsulation/unittests/ResourceClientTest.cpp @@ -177,7 +177,7 @@ TEST_F(RemoteResourceObjectTest, QueryParamsForGetWillBePassedToBase) constexpr char PARAM_KEY[] { "aKey" }; constexpr char VALUE[] { "value" }; - object->get(RCSQueryParams().setResourceInterface(RESOURCEINTERFACE).setResuorceType(RESOURCETYPE). + object->get(RCSQueryParams().setResourceInterface(RESOURCEINTERFACE).setResourceType(RESOURCETYPE). put(PARAM_KEY, VALUE), [](const HeaderOpts&, const RCSRepresentation&, int){}); -- 2.7.4