include/OCPlatform.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.h
  22
  23 /// @brief  This file contains the declaration of classes and its members related to
  24 ///         OCPlatform.
  25
  26 #ifndef __OCPLATFORM_H
  27 #define __OCPLATFORM_H
  28
  29 #include <map>
  30
  31 #include "OCApi.h"
  32 #include "OCResource.h"
  33 #include "OCPlatformHandler.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
  50     {
  51     private:
  52         mutable boost::iostreams::stream<OC::oc_log_stream> m_log_stream;
  53
  54     public:
  55         // typedef for handle to cancel presence info with
  56         typedef OCDoHandle OCPresenceHandle;
  57
  58         /**
  59         * Constructor for OCPlatform. Constructs a new OCPlatform from a given PlatformConfig with
  60         * appropriate fields
  61         * @param config PlatformConfig struct which has details such as modeType (server/client/both),
  62         *               in-proc/out-of-proc etc.
  63         */
  64         OCPlatform(const PlatformConfig& config);
  65         OCPlatform(const PlatformConfig& config, OC::oc_log_stream& log_target);
  66
  67         /**
  68         * Virtual destructor
  69         */
  70         virtual ~OCPlatform(void);
  71
  72         /**
  73         * API for notifying base that resource's attributes have changed.
  74         *
  75         * @param OCResourceHandle resource handle of the resource
  76         *
  77         * @return OCStackResult return value of this API. Returns OC_STACK_OK if success.
  78         * NOTE: This API is for server side only.
  79         * NOTE: OCResourceHandle is defined in ocstack.h.
  80         * NOTE: OCStackResult is defined in ocstack.h.
  81         */
  82         static OCStackResult notifyAllObservers(OCResourceHandle resourceHandle);
  83
  84         /**
  85         * API for notifying only specific clients that resource's attributes have changed.
  86         *
  87         * @param OCResourceHandle resource handle of the resource
  88         * @param observationIds std vector of observationIds. These set of ids are ones which
  89         * which will be notified upon resource change.
  90         * @param responsePtr OCResourceResponse pointer used by app to fill the response for this
  91         * resource change.
  92         *
  93         * @return OCStackResult return value of this API. Returns OC_STACK_OK if success.
  94         *
  95         * NOTE: This API is for server side only.
  96         * NOTE: OCResourceHandle is defined in ocstack.h.
  97         * NOTE: OCStackResult is defined in ocstack.h.
  98         */
  99         static OCStackResult notifyListOfObservers(
 100                                 OCResourceHandle resourceHandle,
 101                                 ObservationIds& observationIds,
 102                                 const std::shared_ptr<OCResourceResponse> responsePtr);
 103
 104         /**
 105         * API for Service and Resource Discovery.
 106         * NOTE: This API applies to client side only.
 107         *
 108         * @param host - Host IP Address of a service to direct resource discovery query. If null or
 109         *        empty, performs multicast resource discovery query
 110         * @param resourceURI - name of the resource. If null or empty, performs search for all resource names
 111         * @param handler - Handles callbacks, success states and failure states.
 112         *
 113         *        Four modes of discovery defined as follows:
 114         *        (NULL/Empty, NULL/Empty) - Performs ALL service discovery AND ALL resource discovery.
 115         *        (NULL/Empty, Not Empty) - Performs query for a filtered/scoped/particular resource(s)
 116         *                                  from ALL services.
 117         *        (Not Empty, NULL/Empty) - Performs ALL resource discovery on a particular service.
 118         *        (Not Empty, Not Empty) - Performs query for a filtered/scoped/particular resource(s)
 119         *                                  from a particular service.
 120         *
 121         * @return OCStackResult return value of this API. Returns OC_STACK_OK if success.
 122         * NOTE: First parameter 'host' currently represents an IP address. This will change in future
 123         * and will refer to endpoint interface so that we can refer to other transports such as BTH etc.
 124         * NOTE: OCStackResult is defined in ocstack.h.
 125         */
 126         OCStackResult findResource(const std::string& host, const std::string& resourceURI,
 127             FindCallback resourceHandler);
 128
 129         /**
 130         * This API registers a resource with the server
 131         * NOTE: This API applies to server side only.
 132         *
 133         * @param resourceHandle - Upon successful registration, resourceHandle will be filled
 134         * @param resourceURI - The URI of the resource. Example: "a/light". See NOTE below
 135         * @param resourceTypeName - The resource type. Example: "light"
 136         * @param resourceInterface - The resource interface (whether it is collection etc).
 137         * @param entityHandler - entity handler callback.
 138         * @param resourceProperty - indicates the property of the resource. Defined in ocstack.h.
 139         * setting resourceProperty as OC_DISCOVERABLE will allow Discovery of this resource
 140         * setting resourceProperty as OC_OBSERVABLE will allow observation
 141         * settings resourceProperty as OC_DISCOVERABLE | OC_OBSERVABLE will allow both discovery and observation
 142         *
 143         * @return OCStackResult return value of this API. Returns OC_STACK_OK if success.
 144         * NOTE: "a/light" is a relative URI.
 145         * Above relative URI will be prepended (by core) with a host IP + namespace "oc"
 146         * Therefore, fully qualified URI format would be //HostIP-Address/namespace/relativeURI"
 147         * Example, a relative URI: 'a/light' will result in a fully qualified URI: //192.168.1.1/oc/a/light"
 148         * First parameter can take a relative URI and core will take care of preparing the fully qualified URI
 149         * OR
 150         * first paramter can take fully qualified URI and core will take that as is for further operations
 151         * NOTE: OCStackResult is defined in ocstack.h.
 152         */
 153         OCStackResult registerResource(OCResourceHandle& resourceHandle,
 154                         std::string& resourceURI,
 155                         const std::string& resourceTypeName,
 156                         const std::string& resourceInterface,
 157                         EntityHandler entityHandler,
 158                         uint8_t resourceProperty);
 159
 160         /**
 161         * Set default device entity handler
 162         *
 163         * @param entityHandler - entity handler to handle requests for
 164         *                        any undefined resources or default actions.
 165         *                        if NULL is passed it removes the device default entity handler.
 166         *
 167         * @return
 168         *     OC_STACK_OK    - no errors
 169         *     OC_STACK_ERROR - stack process error
 170         */
 171         OCStackResult setDefaultDeviceEntityHandler(EntityHandler entityHandler);
 172
 173         /**
 174         * This API unregisters a resource with the server
 175         * NOTE: This API applies to server side only.
 176         *
 177         * @param resourceHandle - This is the resource handle which we which to unregister from the server
 178         *
 179         * @return OCStackResult return value of this API. Returns OC_STACK_OK if success.
 180         * NOTE: OCStackResult is defined in ocstack.h.
 181         */
 182         OCStackResult unregisterResource(const OCResourceHandle& resourceHandle) const;
 183
 184         /**
 185         * Add a resource to a collection resource.
 186         *
 187         * @param collectionHandle - handle to the collection resource
 188         * @param addedResourceHandle - handle to resource to be added to the collection resource
 189         *
 190         * @return OCStackResult return value of this API. Returns OC_STACK_OK if success.<br>
 191         * NOTE: OCStackResult is defined in ocstack.h. <br>
 192         * NOTE: bindResource must be used only after the both collection resource and
 193         * resource to add under a collections are created and respective handles obtained<br>
 194         * <b>Example:</b> <br>
 195         * Step 1: registerResource(homeResourceHandle, "a/home", "home", Link_Interface, entityHandler, OC_DISCOVERABLE | OC_OBSERVABLE);<br>
 196         * Step 2: registerResource(kitchenResourceHandle, "a/kitchen", "kitchen", Link_Interface, entityHandler, OC_DISCOVERABLE | OC_OBSERVABLE);<br>
 197         * Step 3: bindResource(homeResourceHandle, kitchenResourceHandle);<br>
 198         * At the end of Step 3, resource "a/home" will contain a reference to "a/kitchen".<br>
 199         */
 200         OCStackResult bindResource(const OCResourceHandle collectionHandle, const OCResourceHandle resourceHandle);
 201
 202         /**
 203         * Add multiple resources to a collection resource.
 204         *
 205         * @param collectionHandle - handle to the collection resource
 206         * @param addedResourceHandleList reference to list of resource handles to be added to the collection resource
 207         *
 208         * @return OCStackResult return value of this API. Returns OC_STACK_OK if success. <br>
 209         * NOTE: OCStackResult is defined in ocstack.h. <br>
 210         * NOTE: bindResources must be used only after the both collection resource and
 211         * list of resources to add under a collection are created and respective handles obtained <br>
 212         * <b> Example: </b> <br>
 213         * Step 1: registerResource(homeResourceHandle, "a/home", "home", Link_Interface, homeEntityHandler, OC_DISCOVERABLE | OC_OBSERVABLE);<br>
 214         * Step 2: registerResource(kitchenResourceHandle, "a/kitchen", "kitchen", Link_Interface, kitchenEntityHandler, OC_DISCOVERABLE | OC_OBSERVABLE);<br>
 215         * Step 3: registerResource(roomResourceHandle, "a/room", "room", Link_Interface, roomEntityHandler, OC_DISCOVERABLE | OC_OBSERVABLE);<br>
 216         * Step 4: std::vector<OCResourceHandle> rList; rList.push_back(kitchenResourceHandle); rList.push_back(roomResourceHandle);<br>
 217         * Step 5: bindResource(homeResourceHandle, rList);<br>
 218         * At the end of Step 5, resource "a/home" will contain a references to "a/kitchen" and "a/room" <br>
 219         */
 220         OCStackResult bindResources(const OCResourceHandle collectionHandle, const std::vector<OCResourceHandle>& addedResourceHandleList);
 221
 222         /**
 223         * Unbind a resource from a collection resource.
 224         *
 225         * @param collectionHandle - handle to the collection resource
 226         * @param resourceHandle resource handle to be unbound from the collection resource
 227         *
 228         * @return OCStackResult return value of this API. Returns OC_STACK_OK if success. <br>
 229         * NOTE: OCStackResult is defined in ocstack.h.<br>
 230         * NOTE: unbindResource must be used only after the both collection resource and
 231         * resource to unbind from a collection are created and respective handles obtained<br>
 232         * <b> Example </b> <br>
 233         * Step 1: registerResource(homeResourceHandle, "a/home", "home", Link_Interface, entityHandler, OC_DISCOVERABLE | OC_OBSERVABLE);<br>
 234         * Step 2: registerResource(kitchenResourceHandle, "a/kitchen", "kitchen", Link_Interface, entityHandler, OC_DISCOVERABLE | OC_OBSERVABLE);<br>
 235         * Step 3: bindResource(homeResourceHandle, kitchenResourceHandle);<br>
 236         * Step 4: unbindResource(homeResourceHandle, kitchenResourceHandle);<br>
 237         * At the end of Step 4, resource "a/home" will no longer reference "a/kitchen". <br>
 238         */
 239         OCStackResult unbindResource(const OCResourceHandle collectionHandle, const OCResourceHandle resourceHandle);
 240
 241         /**
 242         * Unbind resources from a collection resource.
 243         *
 244         * @param collectionHandle - handle to the collection resource
 245         * @param resourceHandleList List of resource handles to be unbound from the collection resource
 246         *
 247         * @return OCStackResult return value of this API. Returns OC_STACK_OK if success. <br>
 248         *
 249         * NOTE: OCStackResult is defined in ocstack.h.<br>
 250         * NOTE: unbindResources must be used only after the both collection resource and
 251         * list of resources resource to unbind from a collection are created and respective handles obtained. <br>
 252         * <b>Example</b> <br>
 253         * Step 1: registerResource(homeResourceHandle, "a/home", "home", Link_Interface, homeEntityHandler, OC_DISCOVERABLE | OC_OBSERVABLE);<br>
 254         * Step 2: registerResource(kitchenResourceHandle, "a/kitchen", "kitchen", Link_Interface, kitchenEntityHandler, OC_DISCOVERABLE | OC_OBSERVABLE);<br>
 255         * Step 3: registerResource(roomResourceHandle, "a/room", "room", Link_Interface, roomEntityHandler, OC_DISCOVERABLE | OC_OBSERVABLE);<br>
 256         * Step 4: std::vector<OCResourceHandle> rList; rList.push_back(kitchenResourceHandle); rList.push_back(roomResourceHandle);<br>
 257         * Step 5: bindResource(homeResourceHandle, rList);<br>
 258         * Step 6: unbindResources(homeResourceHandle, rList);<br>
 259         * At the end of Step 6, resource "a/home" will no longer reference to "a/kitchen" and "a/room"<br>
 260         */
 261         OCStackResult unbindResources(const OCResourceHandle collectionHandle, const std::vector<OCResourceHandle>& resourceHandleList);
 262
 263         /**
 264         * Binds a type to a particular resource
 265         * @param resourceHandle - handle to the resource
 266         * @param resourceTypeName - new typename to bind to the resource
 267
 268         * @return OCStackResult - return value of the API. Returns OCSTACK_OK if success <br>
 269         */
 270         OCStackResult bindTypeToResource(const OCResourceHandle& resourceHandle,
 271                         const std::string& resourceTypeName) const;
 272
 273         /**
 274         * Binds an interface to a particular resource
 275         * @param resourceHandle - handle to the resource
 276         * @param resourceTypeName - new interface  to bind to the resource
 277
 278         * @return OCStackResult - return value of the API. Returns OCSTACK_OK if success <br>
 279         */
 280         OCStackResult bindInterfaceToResource(const OCResourceHandle& resourceHandle,
 281                         const std::string& resourceInterfaceName) const;
 282
 283         public:
 284         /**
 285         * Start Presence announcements.
 286         *
 287         * @param ttl - time to live
 288         * @return OCStackResult - Returns OCSTACK_OK if success <br>
 289         *
 290         * Server can call this function when it comes online for the
 291         * first time, or when it comes back online from offline mode,
 292         * or when it re enters network.
 293         *
 294         */
 295
 296         OCStackResult startPresence(const unsigned int ttl);
 297
 298         /**
 299         * Stop Presence announcements.
 300         *
 301         * @return OCStackResult - Returns OCSTACK_OK if success <br>
 302         *
 303         * Server can call this function when it is terminating,
 304         * going offline, or when going away from network.
 305         *
 306         */
 307
 308         OCStackResult stopPresence();
 309
 310         /**
 311         * subscribes to a server's presence change events.  By making this subscription,
 312         * every time a server adds/removes/alters a resource, starts or is intentionally
 313         * stopped (potentially more to be added later).
 314         *
 315         * @param presenceHandle - a handle object that can be used to identify this subscription
 316         *               request.  It can be used to unsubscribe from these events in the future.
 317         *               It will be set upon successful return of this method.
 318         * @param host - The IP address/addressable name of the server to subscribe to.
 319         * @param presenceHandler - callback function that will receive notifications/subscription events
 320         *
 321         * @return OCStackResult - return value of the API.  Returns OCSTACK_OK if success <br>
 322         */
 323         OCStackResult subscribePresence(OCPresenceHandle& presenceHandle, const std::string& host,
 324                         SubscribeCallback presenceHandler);
 325
 326         /**
 327         * unsubscribes from a previously subscribed server's presence events. Note that
 328         * you may for a short time still receive events from the server since it may take time
 329         * for the unsubscribe to take effect.
 330         *
 331         * @param presenceHandle - the handle object provided by the subscribePresence call that identifies
 332         *               this subscription.
 333         *
 334         * @return OCStackResult - return value of the API.  Returns OCSTACK_OK if success <br>
 335         */
 336         OCStackResult unsubscribePresence(OCPresenceHandle presenceHandle);
 337
 338         /**
 339         * Creates a resource proxy object so that get/put/observe functionality
 340         * can be used without discovering the object in advance.  Note that the
 341         * consumer of this method needs to provide all of the details required to
 342         * correctly contact and observe the object. If the consumer lacks any of
 343         * this information, they should discover the resource object normally.
 344         * Additionally, you can only create this object if OCPlatform was initialized
 345         * to be a Client or Client/Server.  Otherwise, this will return an empty
 346         * shared ptr.
 347         *
 348         * @param host - a string containing a resolvable host address of the server
 349         *           holding the resource. Currently this should be in the format
 350         *           coap://address:port, though in the future, we expect this to
 351         *           change to //address:port
 352         *
 353         * @param uri - the rest of the resource's URI that will permit messages to be
 354         *           properly routed.  Example: /a/light
 355         *
 356         * @param isObservable - a boolean containing whether the resource supports observation
 357         *
 358         * @param resourceTypes - a collection of resource types implemented by the resource
 359         *
 360         * @param interfaces - a collection of interfaces that the resource supports/implements
 361         * @return OCResource::Ptr - a shared pointer to the new resource object
 362         */
 363         OCResource::Ptr constructResourceObject(const std::string& host, const std::string& uri,
 364                         bool isObservable, const std::vector<std::string>& resourceTypes,
 365                         const std::vector<std::string>& interfaces);
 366
 367     public:
 368         inline boost::iostreams::stream<OC::oc_log_stream>& log() const { return m_log_stream; }
 369
 370     private:
 371         PlatformConfig m_cfg;
 372
 373     private:
 374         std::unique_ptr<WrapperFactory> m_WrapperInstance;
 375         IServerWrapper::Ptr m_server;
 376         IClientWrapper::Ptr m_client;
 377         std::shared_ptr<std::recursive_mutex> m_csdkLock;
 378
 379     private:
 380         /**
 381         *  Private function to initalize the platfrom
 382         */
 383         void init(const PlatformConfig& config);
 384     };
 385 }
 386
 387 #endif //__OCPLATFORM_H
 388
 389