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