resource/include/OCPlatform_impl.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 /**
  22  * @file
  23  *
  24  * Implementation of the OCPlatform functionality. It contains a singleton
  25  * interface that is used only by the OCPlatform namespace and is the
  26  * central entrance to the stack.
  27  */
  28
  29 #ifndef __OCPLATFORM_IMPL_H
  30 #define __OCPLATFORM_IMPL_H
  31
  32 #include <map>
  33
  34 #include "OCApi.h"
  35 #include "OCResource.h"
  36 #include "WrapperFactory.h"
  37 #include "OCResourceRequest.h"
  38 #include "OCResourceResponse.h"
  39 #include "OCRepresentation.h"
  40
  41 #include "oc_logger.hpp"
  42
  43 namespace OC
  44 {
  45     /**
  46     *   @brief Both server and client must initialize the core platform by instantiating OCPlatform.
  47     *          On successful initialization, an instance of the OCPlatform is returned.
  48     *          APIs in OCPlatform provide mechanism to register a resource and host the resource
  49     *          on the server, find resources on the network etc.
  50     */
  51     class OCPlatform_impl
  52     {
  53     private:
  54         static PlatformConfig& globalConfig();
  55     public:
  56         /**
  57          * API for overwriting the default configuration of the OCPlatform object.
  58          * Note: Any calls made to this AFTER the first call to OCPlatform::Instance
  59          * will have no affect
  60          */
  61         static void Configure(const PlatformConfig& config);
  62
  63         /**
  64          * API for retrieving the current OCPlatform object.  This will use the
  65          * default platform config, unless the default is over-written using the
  66          * Configure method before the first call to instance.
  67          */
  68         static OCPlatform_impl& Instance();
  69
  70     public:
  71         // typedef for handle to cancel presence info with
  72         typedef OCDoHandle OCPresenceHandle;
  73
  74         /**
  75         * Virtual destructor
  76         */
  77         virtual ~OCPlatform_impl(void);
  78
  79         /**
  80         * API for notifying base that resource's attributes have changed.
  81         *
  82         * @param OCResourceHandle resource handle of the resource
  83         * @param QualityOfService the quality of communication
  84         *
  85         * @return OCStackResult return value of this API. Returns OC_STACK_OK if success.
  86         * NOTE: This API is for server side only.
  87         * NOTE: OCResourceHandle is defined in ocstack.h.
  88         * NOTE: OCStackResult is defined in ocstack.h.
  89         */
  90         OCStackResult notifyAllObservers(OCResourceHandle resourceHandle);
  91         OCStackResult notifyAllObservers(OCResourceHandle resourceHandle, QualityOfService QoS);
  92
  93         /**
  94         * API for notifying only specific clients that resource's attributes have changed.
  95         *
  96         * @param OCResourceHandle resource handle of the resource
  97         * @param observationIds std vector of observationIds. These set of ids are ones which
  98         * which will be notified upon resource change.
  99         * @param responsePtr OCResourceResponse pointer used by app to fill the response for this
 100         * resource change.
 101         * @param QualityOfService the quality of communication
 102         *
 103         * @return OCStackResult return value of this API. Returns OC_STACK_OK if success.
 104         *
 105         * NOTE: This API is for server side only.
 106         * NOTE: OCResourceHandle is defined in ocstack.h.
 107         * NOTE: OCStackResult is defined in ocstack.h.
 108         */
 109         OCStackResult notifyListOfObservers(
 110                     OCResourceHandle resourceHandle,
 111                     ObservationIds& observationIds,
 112                     const std::shared_ptr<OCResourceResponse> responsePtr);
 113         OCStackResult notifyListOfObservers(
 114                     OCResourceHandle resourceHandle,
 115                     ObservationIds& observationIds,
 116                     const std::shared_ptr<OCResourceResponse> responsePtr,
 117                     QualityOfService QoS);
 118
 119         /**
 120         * API for Service and Resource Discovery.
 121         * NOTE: This API applies to client side only.
 122         *
 123         * @param host - Host IP Address of a service to direct resource discovery query. If null or
 124         *        empty, performs multicast resource discovery query
 125         * @param resourceURI - name of the resource. If null or empty, performs search for all
 126         *        resource names
 127         * @param handler - Handles callbacks, success states and failure states.
 128         *
 129         *        Four modes of discovery defined as follows:
 130         *        (NULL/Empty, NULL/Empty) - Performs ALL service discovery AND ALL resource
 131         *                                   discovery.
 132         *        (NULL/Empty, Not Empty) - Performs query for a filtered/scoped/particular
 133         *                                   resource(s) from ALL services.
 134         *        (Not Empty, NULL/Empty) - Performs ALL resource discovery on a particular service.
 135         *        (Not Empty, Not Empty) - Performs query for a filtered/scoped/particular
 136         *                                   resource(s) from a particular service.
 137         * @param QualityOfService the quality of communication
 138         *
 139         * @return OCStackResult return value of this API. Returns OC_STACK_OK if success.
 140         * NOTE: First parameter 'host' currently represents an IP address. This will change in
 141         * future and will refer to endpoint interface so that we can refer to other transports such
 142         * as BTH etc.
 143         * NOTE: OCStackResult is defined in ocstack.h.
 144         */
 145         OCStackResult findResource(const std::string& host, const std::string& resourceURI,
 146                     FindCallback resourceHandler);
 147         OCStackResult findResource(const std::string& host, const std::string& resourceURI,
 148                     FindCallback resourceHandler, QualityOfService QoS);
 149
 150         /**
 151          * API for Device Discovery
 152          *
 153          * @param host - Host IP Address. If null or empty, Multicast is performed.
 154          * @param resourceURI - Uri containing address to the virtual device in C Stack
 155          *                       ("/oc/core/d")
 156          *
 157          * @param QualityOfService the quality of communication
 158          *
 159          */
 160         OCStackResult getDeviceInfo(const std::string& host, const std::string& deviceURI,
 161                     FindDeviceCallback deviceInfoHandler);
 162         OCStackResult getDeviceInfo(const std::string& host, const std::string& deviceURI,
 163                     FindDeviceCallback deviceInfoHandler, QualityOfService QoS);
 164
 165         /**
 166         * This API registers a resource with the server
 167         * NOTE: This API applies to server side only.
 168         *
 169         * @param resourceHandle - Upon successful registration, resourceHandle will be filled
 170         * @param resourceURI - The URI of the resource. Example: "a/light". See NOTE below
 171         * @param resourceTypeName - The resource type. Example: "light"
 172         * @param resourceInterface - The resource interface (whether it is collection etc).
 173         * @param entityHandler - entity handler callback.
 174         * @param resourceProperty - indicates the property of the resource. Defined in ocstack.h.
 175         * setting resourceProperty as OC_DISCOVERABLE will allow Discovery of this resource
 176         * setting resourceProperty as OC_OBSERVABLE will allow observation
 177         * settings resourceProperty as OC_DISCOVERABLE | OC_OBSERVABLE will allow both discovery
 178         * and observation
 179         *
 180         * @return OCStackResult return value of this API. Returns OC_STACK_OK if success.
 181         * NOTE: "a/light" is a relative URI.
 182         * Above relative URI will be prepended (by core) with a host IP + namespace "oc"
 183         * Therefore, fully qualified URI format would be //HostIP-Address/namespace/relativeURI"
 184         * Example, a relative URI: 'a/light' will result in a fully qualified URI:
 185         *   //192.168.1.1/oc/a/light"
 186         * First parameter can take a relative URI and core will take care of preparing the fully
 187         * qualified URI OR
 188         * first paramter can take fully qualified URI and core will take that as is for further
 189         * operations
 190         * NOTE: OCStackResult is defined in ocstack.h.
 191         */
 192         OCStackResult registerResource(OCResourceHandle& resourceHandle,
 193                         std::string& resourceURI,
 194                         const std::string& resourceTypeName,
 195                         const std::string& resourceInterface,
 196                         EntityHandler entityHandler,
 197                         uint8_t resourceProperty);
 198
 199         /**
 200          * This API registers a resource with the server
 201          * NOTE: This API applies to server & client side.
 202
 203          * @param resourceHandle - Upon successful registration, resourceHandle will be filled
 204          * @param OCResource - The instance of OCResource that all data filled.
 205          *
 206          * @return OCStackResult return value of this API. Returns OC_STACK_OK if success.
 207          */
 208
 209         OCStackResult registerResource(OCResourceHandle& resourceHandle,
 210                         const std::shared_ptr<OCResource> resource);
 211
 212         /**
 213          * This API registers all the device specific information
 214          *
 215          * @param OCDeviceInfo - Structure containing all the device related information
 216          *
 217          * @return OCStackResult return value of the API. Returns OC_STACK_OK if success
 218          *
 219          * Note: OCDeviceInfo is defined in OCStack.h
 220          */
 221         OCStackResult registerDeviceInfo(const OCDeviceInfo deviceInfo);
 222
 223         /**
 224         * Set default device entity handler
 225         *
 226         * @param entityHandler - entity handler to handle requests for
 227         *                        any undefined resources or default actions.
 228         *                        if NULL is passed it removes the device default entity handler.
 229         *
 230         * @return
 231         *     OC_STACK_OK    - no errors
 232         *     OC_STACK_ERROR - stack process error
 233         */
 234         OCStackResult setDefaultDeviceEntityHandler(EntityHandler entityHandler);
 235
 236         /**
 237         * This API unregisters a resource with the server
 238         * NOTE: This API applies to server side only.
 239         *
 240         * @param resourceHandle - This is the resource handle which we which to unregister from the
 241         *                           server
 242         *
 243         * @return OCStackResult return value of this API. Returns OC_STACK_OK if success.
 244         * NOTE: OCStackResult is defined in ocstack.h.
 245         */
 246         OCStackResult unregisterResource(const OCResourceHandle& resourceHandle) const;
 247
 248         /**
 249         * Add a resource to a collection resource.
 250         *
 251         * @param collectionHandle - handle to the collection resource
 252         * @param addedResourceHandle - handle to resource to be added to the collection resource
 253         *
 254         * @return OCStackResult return value of this API. Returns OC_STACK_OK if success.<br>
 255         * NOTE: OCStackResult is defined in ocstack.h. <br>
 256         * NOTE: bindResource must be used only after the both collection resource and
 257         * resource to add under a collections are created and respective handles obtained<br>
 258         * <b>Example:</b> <br>
 259         * Step 1: registerResource(homeResourceHandle, "a/home", "home", Link_Interface,
 260         *               entityHandler, OC_DISCOVERABLE | OC_OBSERVABLE);<br>
 261         * Step 2: registerResource(kitchenResourceHandle, "a/kitchen", "kitchen", Link_Interface,
 262         *               entityHandler, OC_DISCOVERABLE | OC_OBSERVABLE);<br>
 263         * Step 3: bindResource(homeResourceHandle, kitchenResourceHandle);<br>
 264         * At the end of Step 3, resource "a/home" will contain a reference to "a/kitchen".<br>
 265         */
 266         OCStackResult bindResource(const OCResourceHandle collectionHandle,
 267                     const OCResourceHandle resourceHandle);
 268
 269         /**
 270         * Add multiple resources to a collection resource.
 271         *
 272         * @param collectionHandle - handle to the collection resource
 273         * @param addedResourceHandleList reference to list of resource handles to be added to
 274         *       the collection resource
 275         *
 276         * @return OCStackResult return value of this API. Returns OC_STACK_OK if success. <br>
 277         * NOTE: OCStackResult is defined in ocstack.h. <br>
 278         * NOTE: bindResources must be used only after the both collection resource and
 279         * list of resources to add under a collection are created and respective handles
 280         * obtained<br>
 281         * <b> Example: </b> <br>
 282         * Step 1: registerResource(homeResourceHandle, "a/home", "home", Link_Interface,
 283         *           homeEntityHandler, OC_DISCOVERABLE | OC_OBSERVABLE);<br>
 284         * Step 2: registerResource(kitchenResourceHandle, "a/kitchen", "kitchen", Link_Interface,
 285         *           kitchenEntityHandler, OC_DISCOVERABLE | OC_OBSERVABLE);<br>
 286         * Step 3: registerResource(roomResourceHandle, "a/room", "room", Link_Interface,
 287         *           roomEntityHandler, OC_DISCOVERABLE | OC_OBSERVABLE);<br>
 288         * Step 4: std::vector<OCResourceHandle> rList; rList.push_back(kitchenResourceHandle);
 289         *           rList.push_back(roomResourceHandle);<br>
 290         * Step 5: bindResource(homeResourceHandle, rList);<br>
 291         * At the end of Step 5, resource "a/home" will contain a references to "a/kitchen"
 292         *           and "a/room" <br>
 293         */
 294         OCStackResult bindResources(const OCResourceHandle collectionHandle,
 295                     const std::vector<OCResourceHandle>& addedResourceHandleList);
 296
 297         /**
 298         * Unbind a resource from a collection resource.
 299         *
 300         * @param collectionHandle - handle to the collection resource
 301         * @param resourceHandle resource handle to be unbound from the collection resource
 302         *
 303         * @return OCStackResult return value of this API. Returns OC_STACK_OK if success. <br>
 304         * NOTE: OCStackResult is defined in ocstack.h.<br>
 305         * NOTE: unbindResource must be used only after the both collection resource and
 306         * resource to unbind from a collection are created and respective handles obtained<br>
 307         * <b> Example </b> <br>
 308         * Step 1: registerResource(homeResourceHandle, "a/home", "home", Link_Interface,
 309         *       entityHandler, OC_DISCOVERABLE | OC_OBSERVABLE);<br>
 310         * Step 2: registerResource(kitchenResourceHandle, "a/kitchen", "kitchen", Link_Interface,
 311         *       entityHandler, OC_DISCOVERABLE | OC_OBSERVABLE);<br>
 312         * Step 3: bindResource(homeResourceHandle, kitchenResourceHandle);<br>
 313         * Step 4: unbindResource(homeResourceHandle, kitchenResourceHandle);<br>
 314         * At the end of Step 4, resource "a/home" will no longer reference "a/kitchen". <br>
 315         */
 316         OCStackResult unbindResource(const OCResourceHandle collectionHandle,
 317                     const OCResourceHandle resourceHandle);
 318
 319         /**
 320         * Unbind resources from a collection resource.
 321         *
 322         * @param collectionHandle - handle to the collection resource
 323         * @param resourceHandleList List of resource handles to be unbound from the collection
 324         *   resource
 325         *
 326         * @return OCStackResult return value of this API. Returns OC_STACK_OK if success. <br>
 327         *
 328         * NOTE: OCStackResult is defined in ocstack.h.<br>
 329         * NOTE: unbindResources must be used only after the both collection resource and
 330         * list of resources resource to unbind from a collection are created and respective handles
 331         * obtained. <br>
 332         * <b>Example</b> <br>
 333         * Step 1: registerResource(homeResourceHandle, "a/home", "home", Link_Interface,
 334         *       homeEntityHandler, OC_DISCOVERABLE | OC_OBSERVABLE);<br>
 335         * Step 2: registerResource(kitchenResourceHandle, "a/kitchen", "kitchen", Link_Interface,
 336         *       kitchenEntityHandler, OC_DISCOVERABLE | OC_OBSERVABLE);<br>
 337         * Step 3: registerResource(roomResourceHandle, "a/room", "room", Link_Interface,
 338         *       roomEntityHandler, OC_DISCOVERABLE | OC_OBSERVABLE);<br>
 339         * Step 4: std::vector<OCResourceHandle> rList; rList.push_back(kitchenResourceHandle);
 340         *       rList.push_back(roomResourceHandle);<br>
 341         * Step 5: bindResource(homeResourceHandle, rList);<br>
 342         * Step 6: unbindResources(homeResourceHandle, rList);<br>
 343         * At the end of Step 6, resource "a/home" will no longer reference to "a/kitchen"
 344         *       and "a/room"<br>
 345         */
 346         OCStackResult unbindResources(const OCResourceHandle collectionHandle,
 347                         const std::vector<OCResourceHandle>& resourceHandleList);
 348
 349         /**
 350         * Binds a type to a particular resource
 351         * @param resourceHandle - handle to the resource
 352         * @param resourceTypeName - new typename to bind to the resource
 353
 354         * @return OCStackResult - return value of the API. Returns OCSTACK_OK if success <br>
 355         */
 356         OCStackResult bindTypeToResource(const OCResourceHandle& resourceHandle,
 357                         const std::string& resourceTypeName) const;
 358
 359         /**
 360         * Binds an interface to a particular resource
 361         * @param resourceHandle - handle to the resource
 362         * @param resourceTypeName - new interface  to bind to the resource
 363
 364         * @return OCStackResult - return value of the API. Returns OCSTACK_OK if success <br>
 365         */
 366         OCStackResult bindInterfaceToResource(const OCResourceHandle& resourceHandle,
 367                         const std::string& resourceInterfaceName) const;
 368
 369         /**
 370         * Start Presence announcements.
 371         *
 372         * @param ttl - time to live
 373         * @return OCStackResult - Returns OCSTACK_OK if success <br>
 374         *
 375         * Server can call this function when it comes online for the
 376         * first time, or when it comes back online from offline mode,
 377         * or when it re enters network.
 378         *
 379         */
 380         OCStackResult startPresence(const unsigned int ttl);
 381
 382         /**
 383         * Stop Presence announcements.
 384         *
 385         * @return OCStackResult - Returns OCSTACK_OK if success <br>
 386         *
 387         * Server can call this function when it is terminating,
 388         * going offline, or when going away from network.
 389         *
 390         */
 391         OCStackResult stopPresence();
 392
 393         /**
 394         * subscribes to a server's presence change events.  By making this subscription,
 395         * every time a server adds/removes/alters a resource, starts or is intentionally
 396         * stopped (potentially more to be added later).
 397         *
 398         * @param presenceHandle - a handle object that can be used to identify this subscription
 399         *               request.  It can be used to unsubscribe from these events in the future.
 400         *               It will be set upon successful return of this method.
 401         * @param host - The IP address/addressable name of the server to subscribe to.
 402         * @param resourceType - a resource type specified as a filter for subscription callbacks.
 403         * @param presenceHandler - callback function that will receive notifications/subscription
 404         *                           events
 405         *
 406         * @return OCStackResult - return value of the API.  Returns OCSTACK_OK if success <br>
 407         */
 408         OCStackResult subscribePresence(OCPresenceHandle& presenceHandle, const std::string& host,
 409                         SubscribeCallback presenceHandler);
 410         OCStackResult subscribePresence(OCPresenceHandle& presenceHandle, const std::string& host,
 411                         const std::string& resourceType, SubscribeCallback presenceHandler);
 412
 413         /**
 414         * unsubscribes from a previously subscribed server's presence events. Note that
 415         * you may for a short time still receive events from the server since it may take time
 416         * for the unsubscribe to take effect.
 417         *
 418         * @param presenceHandle - the handle object provided by the subscribePresence call that
 419         *               identifies this subscription.
 420         *
 421         * @return OCStackResult - return value of the API.  Returns OCSTACK_OK if success <br>
 422         */
 423         OCStackResult unsubscribePresence(OCPresenceHandle presenceHandle);
 424
 425         /**
 426         * Creates a resource proxy object so that get/put/observe functionality
 427         * can be used without discovering the object in advance.  Note that the
 428         * consumer of this method needs to provide all of the details required to
 429         * correctly contact and observe the object. If the consumer lacks any of
 430         * this information, they should discover the resource object normally.
 431         * Additionally, you can only create this object if OCPlatform was initialized
 432         * to be a Client or Client/Server.  Otherwise, this will return an empty
 433         * shared ptr.
 434         *
 435         * @param host - a string containing a resolvable host address of the server
 436         *           holding the resource. Currently this should be in the format
 437         *           coap://address:port, though in the future, we expect this to
 438         *           change to //address:port
 439         *
 440         * @param uri - the rest of the resource's URI that will permit messages to be
 441         *           properly routed.  Example: /a/light
 442         *
 443         * @param isObservable - a boolean containing whether the resource supports observation
 444         *
 445         * @param resourceTypes - a collection of resource types implemented by the resource
 446         *
 447         * @param interfaces - a collection of interfaces that the resource supports/implements
 448         * @return OCResource::Ptr - a shared pointer to the new resource object
 449         */
 450         OCResource::Ptr constructResourceObject(const std::string& host, const std::string& uri,
 451                         bool isObservable, const std::vector<std::string>& resourceTypes,
 452                         const std::vector<std::string>& interfaces);
 453
 454         /**
 455         * Allows application entity handler to send response to an incoming request.
 456         *
 457         * @param pResponse - OCResourceResponse pointer that will permit to set values related
 458         * to resource response. <br>
 459         * @return OCStackResult - return value of the API. Returns OCSTACK_OK if success <br>
 460         */
 461         OCStackResult sendResponse(const std::shared_ptr<OCResourceResponse> pResponse);
 462
 463     private:
 464         PlatformConfig m_cfg;
 465
 466     private:
 467         std::unique_ptr<WrapperFactory> m_WrapperInstance;
 468         IServerWrapper::Ptr m_server;
 469         IClientWrapper::Ptr m_client;
 470         std::shared_ptr<std::recursive_mutex> m_csdkLock;
 471
 472     private:
 473         /**
 474         * Constructor for OCPlatform. Constructs a new OCPlatform from a given PlatformConfig with
 475         * appropriate fields
 476         * @param config PlatformConfig struct which has details such as modeType
 477         * (server/client/both), in-proc/out-of-proc etc.
 478         */
 479         OCPlatform_impl(const PlatformConfig& config);
 480
 481         /**
 482         * Private function to initalize the platfrom
 483         */
 484         void init(const PlatformConfig& config);
 485
 486         /**
 487         * Private constructor/operators to prevent copying
 488         * of this object
 489         */
 490         OCPlatform_impl(const OCPlatform_impl& other)= delete;
 491         OCPlatform_impl& operator=(const OCPlatform_impl&) = delete;
 492         OCPlatform_impl& operator=(const OCPlatform_impl&&) = delete;
 493     };
 494 }
 495
 496 #endif //__OCPLATFORM_IMPL_H
 497
 498