/**
* @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
#include <vector>
#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.
*
LOST_SIGNAL, /**< Failed to reach the resource. */
};
+ enum class CacheMode
+ {
+ OBSERVE_ONLY,
+ OBSERVE_WITH_POLLING
+ };
+
/**
* The states of monitoring.
*
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<RCSRemoteResourceObject>
{
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;
~RCSRemoteResourceObject();
/**
+ * 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()
/**
* 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.
*
* 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.
*
* @see getCachedAttribute(const std::string&) const
*
*/
- void startCaching(CacheUpdatedCallback cb);
+ void startCaching(CacheUpdatedCallback cb, CacheMode mode = CacheMode::OBSERVE_WITH_POLLING);
/**
* Stops caching.
/**
* 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()
*/
* 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.
* @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
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);
+
+ /**
+ * 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.
*
*/