X-Git-Url: http://review.tizen.org/git/?a=blobdiff_plain;f=service%2Fresource-encapsulation%2Finclude%2FRCSRemoteResourceObject.h;h=e5af9a22cf175be38cb83008a333427b7738d9d3;hb=c315c87e07c4080ecd0ef488e7a1047bc3c509b2;hp=9ba1595def3f473b67d21881badfcd19437f64e4;hpb=c7947c2aac0d24b278b7198c3f45e4bc1a70482e;p=platform%2Fupstream%2Fiotivity.git diff --git a/service/resource-encapsulation/include/RCSRemoteResourceObject.h b/service/resource-encapsulation/include/RCSRemoteResourceObject.h index 9ba1595..e5af9a2 100644 --- a/service/resource-encapsulation/include/RCSRemoteResourceObject.h +++ b/service/resource-encapsulation/include/RCSRemoteResourceObject.h @@ -21,7 +21,7 @@ /** * @file * - * This file contains the Resource Client APIs provided to the developers. + * This file contains the declaration of classes and its members related to RCSRemoteResourceObject */ #ifndef RCSREMOTERESOURCEOBJECT_H @@ -30,11 +30,27 @@ #include #include "RCSResourceAttributes.h" +#include "RCSRepresentation.h" + +namespace OC +{ + class OCResource; + + namespace HeaderOption + { + class OCHeaderOption; + } +} namespace OIC { namespace Service { + + class RCSRepresentation; + + typedef std::vector< OC::HeaderOption::OCHeaderOption > HeaderOpts; + /** * The states of caching. * @@ -50,6 +66,12 @@ namespace OIC LOST_SIGNAL, /**< Failed to reach the resource. */ }; + enum class CacheMode + { + OBSERVE_ONLY, + OBSERVE_WITH_POLLING + }; + /** * The states of monitoring. * @@ -69,50 +91,153 @@ 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: + + /** + * 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); + + /** + * 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; + + /** + * 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: + std::string m_resourceInterface; + std::string m_resourceType; + + std::unordered_map< std::string, std::string > m_map; + }; + + /** + * + * This represents a remote resource and provides simple ways to interact with it. + * Basically this is a client of a remote resource that runs on other device. * - * The resource can be discovered with discoverResource. - * This class is an interaction point between Resource - * and the developers. Developer will get the RCSRemoteResourceObject - * by calling RCSDiscoveryManager::discoverResource. + * The class supports features to help get information of a remote resource + * such as monitoring and caching. * * @see RCSDiscoveryManager * */ - class RCSRemoteResourceObject + class RCSRemoteResourceObject : public std::enable_shared_from_this { public: typedef std::shared_ptr< RCSRemoteResourceObject > Ptr; /** - * Typedef for callback of startMonitoring API + * Callback definition to be invoked when monitoring state is changed. * + * @see startMonitioring * @see ResourceState */ typedef std::function< void(ResourceState) > StateChangedCallback; /** - * Typedef for callback of startCaching API + * Callback definition to be invoked when cache is updated. * - * @see RCSResourceAttributes + * @param attrs the updated attributes */ - typedef std::function< void(const RCSResourceAttributes&) > CacheUpdatedCallback; + typedef std::function< void(const RCSResourceAttributes& attrs, int eCode) > + CacheUpdatedCallback; /** - * Typedef for callback of getRemoteAttributes API + * Callback definition to be invoked when the response of getRemoteAttributes is + * received. * - * @see RCSResourceAttributes + * @param attrs the result attributes + * @param eCode the error code received from the resource + * + * @see getRemoteAttributes */ - typedef std::function< void(const RCSResourceAttributes&) > + typedef std::function< void(const RCSResourceAttributes& attrs, int eCode) > RemoteAttributesGetCallback; /** - * Typedef for callback of setRemoteAttributes API + * Callback definition to be invoked when the response of get is received. * - * @see RCSResourceAttributes + * @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 + * received. + * + * @param attrs the result attributes + * @param eCode the error code received from the resource + * + * @see setRemoteAttributes */ - typedef std::function< void(const RCSResourceAttributes&) > + typedef std::function< void(const RCSResourceAttributes& attrs, int eCode) > RemoteAttributesSetCallback; + /** + * 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; typedef unsigned int BrokerID; @@ -125,14 +250,30 @@ namespace OIC ~RCSRemoteResourceObject(); /** - * @return Returns whether monitoring is enabled. + * Creates an instance from an OCResource instance. + * + * @throw RCSInvalidParameterException If ocResource is nullptr. + */ + static RCSRemoteResourceObject::Ptr fromOCResource( + std::shared_ptr< OC::OCResource > ocResource); + + /** + * Returns an equivalent OCResource using RCSRemoteResourceObject instance. + * + * @throw RCSInvalidParameterException If rcsResource is nullptr. + */ + static std::shared_ptr< OC::OCResource > toOCResource( + RCSRemoteResourceObject::Ptr rcsResource); + + /** + * Returns whether monitoring is enabled. * * @see startMonitoring() */ bool isMonitoring() const; /** - * @return Returns whether caching is enabled. + * Returns whether caching is enabled. * * @see startCaching() */ @@ -140,7 +281,7 @@ namespace OIC bool isCaching() const; /** - * @return Returns whether the resource is observable. + * Returns whether the resource is observable. * */ bool isObservable() const; @@ -177,7 +318,7 @@ namespace OIC void stopMonitoring(); /** - * @return Returns the current state of the resource. + * Returns the current state of the resource. * * @see startMonitoring */ @@ -186,7 +327,7 @@ namespace OIC /** * Starts caching attributes of the resource. * - * This will start data caching for the resource. + * This will start caching for the resource. * Once caching started it will look for the data updation on the resource * and updates the cache data accordingly. * @@ -209,6 +350,7 @@ namespace OIC * updates the cached data accordingly. * * @param cb If non-empty function, it will be invoked whenever the cache updated. + * @param mode if CacheMode is OBSERVE_ONLY, it will be invoked when receive observe response only. * * @throws BadRequestException If caching is already started. * @@ -221,7 +363,7 @@ namespace OIC * @see getCachedAttribute(const std::string&) const * */ - void startCaching(CacheUpdatedCallback cb); + void startCaching(CacheUpdatedCallback cb, CacheMode mode = CacheMode::OBSERVE_WITH_POLLING); /** * Stops caching. @@ -234,16 +376,16 @@ namespace OIC void stopCaching(); /** - * @return Returns the current cache state. + * Returns the current cache state. * */ CacheState getCacheState() const; /** - * @return Returns whether cached data is available. + * Returns whether cached data is available. * - * Cache will be available always after CacheState::READY even if current state is - * CacheState::LOST_SIGNAL. + * Cache will be available always once cache state had been CacheState::READY + * even if current state is CacheState::LOST_SIGNAL. * * @see getCacheState() */ @@ -288,17 +430,43 @@ 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. - * - * @throw InvalidParameterException If cb is an empty function or null. + * the attributes to the caller in the RemoteAttributesGetCallback. * - * @see RCSResourceAttributes::Value + * @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 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); + + /** + * 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. * * The SetRequest behavior depends on the server, whether updating its attributes or not. @@ -306,7 +474,8 @@ namespace OIC * @param attributes Attributes to set * @param cb A callback to receive the response. * - * @throw InvalidParameterException If cb is an empty function or null. + * @throws PlatformException If the operation failed + * @throws InvalidParameterException If cb is an empty function or null. * * @see RCSResourceObject * @see RCSResourceObject::SetRequestHandlerPolicy @@ -317,25 +486,83 @@ namespace OIC RemoteAttributesSetCallback cb); /** - * @return Returns the uri of the resource. + * 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); + + /** + * 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); + + /** + * Sends a set request with resource representation to the server. + * + * The SetRequest behavior depends on query parameters and the server. + * + * @param queryParams Query parameters + * @param rep Representation 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 RCSRepresentation &rep, + SetCallback cb); + + /** + * Returns the uri of the resource. * */ std::string getUri() const; /** - * @return Returns the address of the resource . + * Returns the address of the resource . * */ std::string getAddress() const; /** - * @return Returns the resource types of the resource. + * Returns the resource types of the resource. * */ std::vector< std::string > getTypes() const; /** - * @return Returns the resource interfaces of the resource. + * Returns the resource interfaces of the resource. * */ std::vector< std::string > getInterfaces() const;