resource/include/OCResource.h

   1 //******************************************************************
   2 //
   3 // Copyright 2014 Intel Mobile Communications GmbH All Rights Reserved.
   4 //
   5 //-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
   6 //
   7 // Licensed under the Apache License, Version 2.0 (the "License");
   8 // you may not use this file except in compliance with the License.
   9 // You may obtain a copy of the License at
  10 //
  11 //      http://www.apache.org/licenses/LICENSE-2.0
  12 //
  13 // Unless required by applicable law or agreed to in writing, software
  14 // distributed under the License is distributed on an "AS IS" BASIS,
  15 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  16 // See the License for the specific language governing permissions and
  17 // limitations under the License.
  18 //
  19 //-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
  20
  21 /// @file OCResource.h
  22
  23 /// @brief  This file contains the declaration of classes and its members related to
  24 ///         Resource.
  25
  26 #ifndef __OCRESOURCE_H
  27 #define __OCRESOURCE_H
  28
  29 #include <memory>
  30 #include <random>
  31 #include <algorithm>
  32
  33 #include <OCApi.h>
  34 #include <ResourceInitException.h>
  35 #include <IClientWrapper.h>
  36 #include <InProcClientWrapper.h>
  37 #include <OCRepresentation.h>
  38
  39 namespace OC
  40 {
  41     class OCResource;
  42     class OCResourceIdentifier;
  43     ostream& operator <<(ostream& os, const OCResourceIdentifier& ri);
  44     /**
  45     *  @brief  OCResourceIdentifier represents the identity information for a server. This
  46     *          object combined with the OCResource's URI property uniquely identify an
  47     *          OCResource on or across networks.
  48     *          Equality operators are implemented.  However, internal representation is subject
  49     *          to change and thus should not be accessed or depended on.
  50     */
  51     class OCResourceIdentifier
  52     {
  53         friend class OCResource;
  54         friend ostream& operator <<(ostream& os, const OCResourceIdentifier& ri);
  55
  56         public:
  57             bool operator==(const OCResourceIdentifier &other) const;
  58
  59             bool operator!=(const OCResourceIdentifier &other) const;
  60
  61             bool operator<(const OCResourceIdentifier &other) const;
  62
  63             bool operator>(const OCResourceIdentifier &other) const;
  64
  65             bool operator<=(const OCResourceIdentifier &other) const;
  66
  67             bool operator>=(const OCResourceIdentifier &other) const;
  68
  69         private:
  70
  71             OCResourceIdentifier(const std::string& wireServerIdentifier,
  72                     const std::string& resourceUri );
  73
  74         private:
  75             uint32_t m_representation;
  76             const std::string& m_resourceUri;
  77     };
  78
  79     /**
  80     *   @brief  OCResource represents an OC resource. A resource could be a light controller,
  81     *           temperature sensor, smoke detector, etc. A resource comes with a well-defined
  82     *           contract or interface onto which you can perform different operations, such as
  83     *           turning on the light, getting the current temperature or subscribing for event
  84     *           notifications from the smoke detector. A resource can be composed of one or
  85     *           more resources.
  86     */
  87     class OCResource
  88     {
  89     friend class OCPlatform_impl;
  90     friend class ListenOCContainer;
  91     public:
  92         typedef std::shared_ptr<OCResource> Ptr;
  93         /**
  94         * Virtual destructor
  95         */
  96         virtual ~OCResource(void);
  97
  98         /**
  99         * Function to get the attributes of a resource.
 100         * @param queryParametersMap map which can have the query parameter name and value
 101         * @param attributeHandler handles callback
 102         *        The callback function will be invoked with a map of attribute name and values.
 103         *        The callback function will also have the result from this Get operation
 104         *        This will have error codes
 105         * @param QualityOfService the quality of communication
 106         * @return OCStackResult return value of this API. Returns OC_STACK_OK if success.
 107         * NOTE: OCStackResult is defined in ocstack.h.
 108         */
 109         OCStackResult get(const QueryParamsMap& queryParametersMap, GetCallback attributeHandler);
 110         OCStackResult get(const QueryParamsMap& queryParametersMap, GetCallback attributeHandler,
 111                           QualityOfService QoS);
 112
 113         /**
 114         * Function to get the attributes of a resource.
 115         *
 116         * @param resourceType resourceType of the resource operate on
 117         * @param resourceInterface interface type of the resource to operate on
 118         * @param queryParametersMap map which can have the query parameter name and value
 119         * @param attributeHandler handles callback
 120         *        The callback function will be invoked with a map of attribute name and values.
 121         *        The callback function will be invoked with a list of URIs if 'get' is invoked on a
 122         *        resource container (list will be empty if not a container)
 123         *        The callback function will also have the result from this Get operation. This will
 124         *        have error codes
 125         * @param QualityOfService the quality of communication
 126         * @return OCStackResult return value of this API. Returns OC_STACK_OK if success. <br>
 127         * NOTE: OCStackResult is defined in ocstack.h.<br>
 128         * <b>Example:</b><br>
 129         * Consider resource "a/home" (with link interface and resource type as home) contains links
 130         *  to "a/kitchen" and "a/room".
 131         * Step 1: get("home", Link_Interface, &onGet)<br>
 132         * Callback onGet will receive a) Empty attribute map because there are no attributes for
 133         * a/home b) list with
 134         * full URI of "a/kitchen" and "a/room" resources and their properties c) error code for GET
 135         * operation<br>
 136         * NOTE: A resource may contain single or multiple resource types. Also, a resource may
 137         * contain single or multiple interfaces.<br>
 138         * Currently, single GET request is allowed to do operate on single resource type or resource
 139         * interface. In future, a single GET <br>
 140         * can operate on multiple resource types and interfaces. <br>
 141         * NOTE: A client can traverse a tree or graph by doing successive GETs on the returned
 142         * resources at a node.<br>
 143         */
 144         OCStackResult get(const std::string& resourceType, const std::string& resourceInterface,
 145                         const QueryParamsMap& queryParametersMap, GetCallback attributeHandler);
 146         OCStackResult get(const std::string& resourceType, const std::string& resourceInterface,
 147                         const QueryParamsMap& queryParametersMap, GetCallback attributeHandler,
 148                         QualityOfService QoS);
 149
 150         /**
 151         * Function to set the representation of a resource (via PUT)
 152         * @param representation which can either have all the attribute names and values
 153                  (which will represent entire state of the resource) or a
 154         *        set of attribute names and values which needs to be modified
 155         *        The callback function will be invoked with a map of attribute name and values.
 156         *        The callback function will also have the result from this Put operation
 157         *        This will have error codes
 158         * @param queryParametersMap map which can have the query parameter name and value
 159         * @param attributeHandler attribute handler
 160         * @param QualityOfService the quality of communication
 161         * @return OCStackResult return value of this API. Returns OC_STACK_OK if success.
 162         * NOTE: OCStackResult is defined in ocstack.h.
 163         */
 164         OCStackResult put(const OCRepresentation& representation,
 165                         const QueryParamsMap& queryParametersMap, PutCallback attributeHandler);
 166         OCStackResult put(const OCRepresentation& representation,
 167                         const QueryParamsMap& queryParametersMap, PutCallback attributeHandler,
 168                         QualityOfService QoS);
 169
 170         /**
 171         * Function to set the attributes of a resource (via PUT)
 172         * @param resourceType resource type of the resource to operate on
 173         * @param resourceInterface interface type of the resource to operate on
 174         * @param representation representation of the resource
 175         * @param queryParametersMap Map which can have the query parameter name and value
 176         * @param attributeHandler attribute handler
 177         *        The callback function will be invoked with a map of attribute name and values.
 178         *        The callback function will also have the result from this Put operation
 179         *        This will have error codes.
 180         *        The Representation parameter maps which can either have all the attribute names
 181         *        and values
 182         *        (which will represent entire state of the resource) or a
 183         *        set of attribute names and values which needs to be modified
 184         * @param QualityOfService the quality of communication
 185         * @return OCStackResult return value of this API. Returns OC_STACK_OK if success. <br>
 186         * NOTE: OCStackResult is defined in ocstack.h. <br>
 187         */
 188         OCStackResult put(const std::string& resourceType, const std::string& resourceInterface,
 189                         const OCRepresentation& representation, const QueryParamsMap& queryParametersMap,
 190                         PutCallback attributeHandler);
 191         OCStackResult put(const std::string& resourceType, const std::string& resourceInterface,
 192                         const OCRepresentation& representation, const QueryParamsMap& queryParametersMap,
 193                         PutCallback attributeHandler, QualityOfService QoS);
 194
 195         /**
 196         * Function to post on a resource
 197         * @param representation which can either have all the attribute names and values
 198                  (which will represent entire state of the resource) or a
 199         *        set of attribute names and values which needs to be modified
 200         *        The callback function will be invoked with a map of attribute name and values.
 201         *        The callback function will also have the result from this Put operation
 202         *        This will have error codes
 203         * @param queryParametersMap map which can have the query parameter name and value
 204         * @param attributeHandler attribute handler
 205         * @param QualityOfService the quality of communication
 206         * @return OCStackResult return value of this API. Returns OC_STACK_OK if success.
 207         * NOTE: OCStackResult is defined in ocstack.h.
 208         */
 209         OCStackResult post(const OCRepresentation& representation,
 210                         const QueryParamsMap& queryParametersMap, PostCallback attributeHandler);
 211         OCStackResult post(const OCRepresentation& representation,
 212                         const QueryParamsMap& queryParametersMap, PostCallback attributeHandler,
 213                         QualityOfService QoS);
 214
 215         /**
 216         * Function to post on a resource
 217         * @param resourceType resource type of the resource to operate on
 218         * @param resourceInterface interface type of the resource to operate on
 219         * @param representation representation of the resource
 220         * @param queryParametersMap Map which can have the query parameter name and value
 221         * @param attributeHandler attribute handler
 222         *        The callback function will be invoked with a map of attribute name and values.
 223         *        The callback function will also have the result from this Put operation
 224         *        This will have error codes.
 225         *        The Representation parameter maps which can either have all the attribute names
 226         *        and values
 227         *        (which will represent entire state of the resource) or a
 228         *        set of attribute names and values which needs to be modified
 229         * @param QualityOfService the quality of communication
 230         * @return OCStackResult return value of this API. Returns OC_STACK_OK if success. <br>
 231         * NOTE: OCStackResult is defined in ocstack.h. <br>
 232         */
 233         OCStackResult post(const std::string& resourceType, const std::string& resourceInterface,
 234                         const OCRepresentation& representation, const QueryParamsMap& queryParametersMap,
 235                         PostCallback attributeHandler);
 236         OCStackResult post(const std::string& resourceType, const std::string& resourceInterface,
 237                         const OCRepresentation& representation, const QueryParamsMap& queryParametersMap,
 238                         PostCallback attributeHandler, QualityOfService QoS);
 239
 240         /**
 241         * Function to perform DELETE operation
 242         * @param observeHandler handles callback
 243         *        The callback function will have headerOptions and result from this Delete
 244         *        operation. This will have error codes
 245         * @return OCStackResult return value of this API. Returns OC_STACK_OK if success.
 246         * NOTE: OCStackResult is defined in ocstack.h.
 247         */
 248         OCStackResult deleteResource(DeleteCallback deleteHandler);
 249         OCStackResult deleteResource(DeleteCallback deleteHandler, QualityOfService QoS);
 250
 251         /**
 252         * Function to set observation on the resource
 253         * @param observeType allows the client to specify how it wants to observe.
 254         * @param queryParametersMap map which can have the query parameter name and value
 255         * @param observeHandler handles callback
 256         *        The callback function will be invoked with a map of attribute name and values.
 257         *        The callback function will also have the result from this observe operation
 258         *        This will have error codes
 259         * @param QualityOfService the quality of communication
 260         * @return OCStackResult return value of this API. Returns OC_STACK_OK if success.
 261         * NOTE: OCStackResult is defined in ocstack.h.
 262         */
 263         OCStackResult observe(ObserveType observeType, const QueryParamsMap& queryParametersMap,
 264                         ObserveCallback observeHandler);
 265         OCStackResult observe(ObserveType observeType, const QueryParamsMap& queryParametersMap,
 266                         ObserveCallback observeHandler, QualityOfService qos);
 267
 268         /**
 269         * Function to cancel the observation on the resource
 270         * @return OCStackResult return value of this API. Returns OC_STACK_OK if success.
 271         * NOTE: OCStackResult is defined in ocstack.h.
 272         */
 273         OCStackResult cancelObserve();
 274         OCStackResult cancelObserve(QualityOfService qos);
 275
 276         /**
 277         * Function to set header information.
 278         * @param headerOptions std::vector where header information(header optionID and optionData
 279         * is passed
 280         *
 281         * NOTE: Once the headers information is set, it will be applicable to GET, PUT and observe
 282         * request. <br>
 283         * setHeaderOptions can be used multiple times if headers need to be modifed by the client.
 284         * Latest headers will be used to send in the request. <br>
 285         * NOTE: Initial support is only for two headers. If headerMap consists of more than two
 286         * header options, they will be ignored. <br>
 287         * Use unsetHeaderOptions API to clear the header information.
 288         */
 289         void setHeaderOptions(const HeaderOptions& headerOptions)
 290         {
 291             m_headerOptions = headerOptions;
 292         }
 293
 294         /**
 295         * Function to unset header options.
 296         */
 297         void unsetHeaderOptions()
 298         {
 299             m_headerOptions.clear();
 300         }
 301
 302         /**
 303         * Function to get the host address of this resource
 304         * @return std::string host address
 305         * NOTE: This might or might not be exposed in future due to security concerns
 306         */
 307         std::string host() const;
 308
 309         /**
 310         * Function to get the URI for this resource
 311         * @return std::string resource URI
 312         */
 313         std::string uri() const;
 314
 315 #ifdef CA_INT
 316         /**
 317         * Function to get the connectivity type of this resource
 318         * @return uint8_t connectivity type
 319         */
 320         OCConnectivityType connectivityType() const;
 321 #endif
 322
 323         /**
 324         * Function to provide ability to check if this resource is observable or not
 325         * @return bool true indicates resource is observable; false indicates resource is
 326         *         not observable.
 327         */
 328         bool isObservable() const;
 329
 330         /**
 331         * Function to get the list of resource types
 332         * @return vector of resource types
 333         */
 334         std::vector<std::string> getResourceTypes() const
 335         {
 336             return m_resourceTypes;
 337         }
 338
 339         /**
 340         * Function to get the list of resource interfaces
 341         * @return vector of resource interface
 342         */
 343         std::vector<std::string> getResourceInterfaces(void) const
 344         {
 345             return m_interfaces;
 346         }
 347
 348         // TODO-CA Revisit this since we are exposing two identifiers
 349         /**
 350         * Function to get a unqiue identifier for this
 351         * resource across network interfaces.  This will
 352         * be guaranteed unique for every resource-per-server
 353         * independent of how this was discovered.
 354         * @return OCResourceIdentifier object, which can
 355         * be used for all comparison and hashing.
 356         */
 357         OCResourceIdentifier uniqueIdentifier() const;
 358
 359         /**
 360         * Function to get a string representation of the resource's server ID.
 361         * This is unique per- server independent on how it was discovered.
 362         * Note: The format of the return value is subject to change and will
 363         * likely change both in size and contents in the future.
 364         */
 365         std::string sid() const;
 366
 367         // overloaded operators allow for putting into a 'set'
 368         // the uniqueidentifier allows for putting into a hash
 369         bool operator==(const OCResource &other) const;
 370
 371         bool operator!=(const OCResource &other) const;
 372
 373         bool operator<(const OCResource &other) const;
 374
 375         bool operator>(const OCResource &other) const;
 376
 377         bool operator<=(const OCResource &other) const;
 378
 379         bool operator>=(const OCResource &other) const;
 380
 381     private:
 382         std::weak_ptr<IClientWrapper> m_clientWrapper;
 383         std::string m_uri;
 384         OCResourceIdentifier m_resourceId;
 385         std::string m_host;
 386 #ifdef CA_INT
 387         OCConnectivityType m_connectivityType;
 388 #endif
 389         bool m_isObservable;
 390         bool m_isCollection;
 391         std::vector<std::string> m_resourceTypes;
 392         std::vector<std::string> m_interfaces;
 393         std::vector<std::string> m_children;
 394         OCDoHandle m_observeHandle;
 395         HeaderOptions m_headerOptions;
 396
 397     private:
 398 #ifdef CA_INT
 399         OCResource(std::weak_ptr<IClientWrapper> clientWrapper, const std::string& host,
 400             const std::string& uri, const std::string& serverId,
 401             OCConnectivityType m_connectivityType, bool observable,
 402             const std::vector<std::string>& resourceTypes,
 403             const std::vector<std::string>& interfaces);
 404 #else
 405         OCResource(std::weak_ptr<IClientWrapper> clientWrapper, const std::string& host,
 406             const std::string& uri, const std::string& serverId, bool observable,
 407             const std::vector<std::string>& resourceTypes,
 408             const std::vector<std::string>& interfaces);
 409 #endif
 410     };
 411
 412 } // namespace OC
 413
 414 #endif //__OCRESOURCE_H