include/OCPlatform.h

   1 //******************************************************************
   2 //
   3 // Copyright 2014 Intel Corporation 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
  38 namespace OC
  39 {
  40     /**
  41     *   @brief  Both server and client must initialize the core platform by instantiating OCPlatform.
  42     *           On successful initialization, an instance of the OCPlatform is returned.
  43     *           APIs in OCPlatform provide mechanism to register a resource and host the resource
  44     *           on the server, find resources on the network etc.
  45     */
  46     class OCPlatform
  47     {
  48     public:
  49         /**
  50         * Constructor for OCPlatform. Constructs a new OCPlatform from a given PlatformConfig with
  51         * appropriate fields
  52         * @param config PlatformConfig struct which has details such as modeType (server/client/both),
  53         *               in-proc/out-of-proc etc.
  54         */
  55         OCPlatform(const PlatformConfig& config);
  56
  57         /**
  58         * Virtual destructor
  59         */
  60         virtual ~OCPlatform(void);
  61
  62         /**
  63         * API for notifying core that resource's attributes have changed.
  64         *
  65         * @param OCResourceHandle resource handle of the resource
  66         *
  67         * @return OCStackResult return value of this API. Returns OC_STACK_OK if success.
  68         * NOTE: This API is for server side only.
  69         * NOTE: OCResourceHandle is defined in ocstack.h.
  70         * NOTE: OCStackResult is defined in ocstack.h.
  71         */
  72         static OCStackResult notifyObservers(OCResourceHandle resourceHandle);
  73
  74         /**
  75         * API for Service and Resource Discovery.
  76         * NOTE: This API applies to client side only.
  77         *
  78         * @param host - Host IP Address of a service to direct resource discovery query. If null or
  79         *        empty, performs multicast resource discovery query
  80         * @param resourceURI - name of the resource. If null or empty, performs search for all resource names
  81         * @param handler - Handles callbacks, success states and failure states.
  82         *
  83         *        Four modes of discovery defined as follows:
  84         *        (NULL/Empty, NULL/Empty) - Performs ALL service discovery AND ALL resource discovery.
  85         *        (NULL/Empty, Not Empty) - Performs query for a filtered/scoped/particular resource(s)
  86         *                                  from ALL services.
  87         *        (Not Empty, NULL/Empty) - Performs ALL resource discovery on a particular service.
  88         *        (Not Empty, Not Empty) - Performs query for a filtered/scoped/particular resource(s)
  89         *                                  from a particular service.
  90         *
  91         * @return OCStackResult return value of this API. Returns OC_STACK_OK if success.
  92         * NOTE: First parameter 'host' currently represents an IP address. This will change in future
  93         * and will refer to endpoint interface so that we can refer to other transports such as BTH etc.
  94         * NOTE: OCStackResult is defined in ocstack.h.
  95         */
  96         OCStackResult findResource(const std::string& host, const std::string& resourceURI,
  97             std::function<void(OCResource::Ptr)> resourceHandler);
  98
  99         /**
 100         * This API registers a resource with the server
 101         * NOTE: This API applies to server side only.
 102         *
 103         * @param resourceHandle - Upon successful registration, resourceHandle will be filled
 104         * @param resourceURI - The URI of the resource. Example: "a/light". See NOTE below
 105         * @param resourceTypeName - The resource type. Example: "light"
 106         * @param resourceInterface - The resource interface (whether it is collection etc).
 107         * @param entityHandler - entity handler callback.
 108         * @param resourceProperty - indicates the property of the resource. Defined in ocstack.h.
 109         * setting resourceProperty as OC_DISCOVERABLE will allow Discovery of this resource
 110         * setting resourceProperty as OC_OBSERVABLE will allow observation
 111         * settings resourceProperty as OC_DISCOVERABLE | OC_OBSERVABLE will allow both discovery and observation
 112         *
 113         * @return OCStackResult return value of this API. Returns OC_STACK_OK if success.
 114         * NOTE: "a/light" is a relative URI.
 115         * Above relative URI will be prepended (by core) with a host IP + namespace "oc"
 116         * Therefore, fully qualified URI format would be //HostIP-Address/namespace/relativeURI"
 117         * Example, a relative URI: 'a/light' will result in a fully qualified URI: //134.134.161.33/oc/a/light"
 118         * First parameter can take a relative URI and core will take care of preparing the fully qualified URI
 119         * OR
 120         * first paramter can take fully qualified URI and core will take that as is for further operations
 121         * NOTE: OCStackResult is defined in ocstack.h.
 122         */
 123         OCStackResult registerResource(OCResourceHandle& resourceHandle,
 124                         std::string& resourceURI,
 125                         const std::string& resourceTypeName,
 126                         const std::string& resourceInterface,
 127                         std::function<void(const OCResourceRequest::Ptr, const OCResourceResponse::Ptr)> entityHandler,
 128                         uint8_t resourceProperty);
 129
 130         /**
 131         * Add a resource to a container resource.
 132         *
 133         * @param containerHandle - handle to the container resource
 134         * @param addedResourceHandle - handle to resource to be added to the container resource
 135         *
 136         * @return OCStackResult return value of this API. Returns OC_STACK_OK if success.<br>
 137         * NOTE: OCStackResult is defined in ocstack.h. <br>
 138         * NOTE: bindResourceToContainer must be used only after the both container resource and
 139         * resource to add under a container are created and respective handles obtained<br>
 140         * <b>Example:</b> <br>
 141         * Step 1: registerResource(homeResourceHandle, "a/home", "home", Link_Interface, entityHandler, OC_DISCOVERABLE | OC_OBSERVABLE);<br>
 142         * Step 2: registerResource(kitchenResourceHandle, "a/kitchen", "kitchen", Link_Interface, entityHandler, OC_DISCOVERABLE | OC_OBSERVABLE);<br>
 143         * Step 3: bindResourceToContainer(homeResourceHandle, kitchenResourceHandle);<br>
 144         * At the end of Step 3, resource "a/home" will contain a reference to "a/kitchen".<br>
 145         */
 146         OCStackResult bindResource(const OCResourceHandle containerHandle, const OCResourceHandle resourceHandle);
 147
 148         /**
 149         * Add multiple resources to a container resource.
 150         *
 151         * @param containerHandle - handle to the container resource
 152         * @param addedResourceHandleList reference to list of resource handles to be added to the container resource
 153         *
 154         * @return OCStackResult return value of this API. Returns OC_STACK_OK if success. <br>
 155         * NOTE: OCStackResult is defined in ocstack.h. <br>
 156         * NOTE: bindResourcesToContainer must be used only after the both container resource and
 157         * list of resources to add under a container are created and respective handles obtained <br>
 158         * <b> Example: </b> <br>
 159         * Step 1: registerResource(homeResourceHandle, "a/home", "home", Link_Interface, homeEntityHandler, OC_DISCOVERABLE | OC_OBSERVABLE);<br>
 160         * Step 2: registerResource(kitchenResourceHandle, "a/kitchen", "kitchen", Link_Interface, kitchenEntityHandler, OC_DISCOVERABLE | OC_OBSERVABLE);<br>
 161         * Step 3: registerResource(roomResourceHandle, "a/room", "room", Link_Interface, roomEntityHandler, OC_DISCOVERABLE | OC_OBSERVABLE);<br>
 162         * Step 4: std::vector<OCResourceHandle> rList; rList.push_back(kitchenResourceHandle); rList.push_back(roomResourceHandle);<br>
 163         * Step 5: bindResourceToContainer(homeResourceHandle, rList);<br>
 164         * At the end of Step 5, resource "a/home" will contain a references to "a/kitchen" and "a/room" <br>
 165         */
 166         OCStackResult bindResources(const OCResourceHandle containerHandle, const std::vector<OCResourceHandle>& addedResourceHandleList);
 167
 168         /**
 169         * Unbind a resource from a container resource.
 170         *
 171         * @param containerHandle - handle to the container resource
 172         * @param resourceHandle resource handle to be unbound from the container resource
 173         *
 174         * @return OCStackResult return value of this API. Returns OC_STACK_OK if success. <br>
 175         * NOTE: OCStackResult is defined in ocstack.h.<br>
 176         * NOTE: unbindResource must be used only after the both container resource and
 177         * resource to unbind from a container are created and respective handles obtained<br>
 178         * <b> Example </b> <br>
 179         * Step 1: registerResource(homeResourceHandle, "a/home", "home", Link_Interface, entityHandler, OC_DISCOVERABLE | OC_OBSERVABLE);<br>
 180         * Step 2: registerResource(kitchenResourceHandle, "a/kitchen", "kitchen", Link_Interface, entityHandler, OC_DISCOVERABLE | OC_OBSERVABLE);<br>
 181         * Step 3: bindResourceToContainer(homeResourceHandle, kitchenResourceHandle);<br>
 182         * Step 4: unbindResource(homeResourceHandle, kitchenResourceHandle);<br>
 183         * At the end of Step 4, resource "a/home" will no longer reference "a/kitchen". <br>
 184         */
 185         OCStackResult unbindResource(OCResourceHandle containerHandle, OCResourceHandle resourceHandle);
 186
 187         /**
 188         * Unbind resources from a container resource.
 189         *
 190         * @param containerHandle - handle to the container resource
 191         * @param resourceHandleList List of resource handles to be unbound from the container resource
 192         *
 193         * @return OCStackResult return value of this API. Returns OC_STACK_OK if success. <br>
 194         *
 195         * NOTE: OCStackResult is defined in ocstack.h.<br>
 196         * NOTE: unbindResources must be used only after the both container resource and
 197         * list of resources resource to unbind from a container are created and respective handles obtained. <br>
 198         * <b>Example</b> <br>
 199         * Step 1: registerResource(homeResourceHandle, "a/home", "home", Link_Interface, homeEntityHandler, OC_DISCOVERABLE | OC_OBSERVABLE);<br>
 200         * Step 2: registerResource(kitchenResourceHandle, "a/kitchen", "kitchen", Link_Interface, kitchenEntityHandler, OC_DISCOVERABLE | OC_OBSERVABLE);<br>
 201         * Step 3: registerResource(roomResourceHandle, "a/room", "room", Link_Interface, roomEntityHandler, OC_DISCOVERABLE | OC_OBSERVABLE);<br>
 202         * Step 4: std::vector<OCResourceHandle> rList; rList.push_back(kitchenResourceHandle); rList.push_back(roomResourceHandle);<br>
 203         * Step 5: bindResourceToContainer(homeResourceHandle, rList);<br>
 204         * Step 6: unbindResources(homeResourceHandle, rList);<br>
 205         * At the end of Step 6, resource "a/home" will no longer reference to "a/kitchen" and "a/room"<br>
 206         */
 207         OCStackResult unbindResources(OCResourceHandle containerHandle, std::vector<OCResourceHandle>& resourceHandleList);
 208
 209         /**
 210         * Binds a type to a particular resource
 211         * @param resourceHandle - handle to the resource
 212         * @param resourceTypeName - new typename to bind to the resource
 213
 214         * @return OCStackResult - return value of the API. Returns OCSTACk_OK if success <br>
 215         */
 216         OCStackResult bindTypeToResource(const OCResourceHandle& resourceHandle,
 217                         const std::string& resourceTypeName) const;
 218
 219         /**
 220         * Binds an interface to a particular resource
 221         * @param resourceHandle - handle to the resource
 222         * @param resourceTypeName - new interface  to bind to the resource
 223
 224         * @return OCStackResult - return value of the API. Returns OCSTACk_OK if success <br>
 225         */
 226         OCStackResult bindInterfaceToResource(const OCResourceHandle& resourceHandle,
 227                         const std::string& resourceInterfaceName) const;
 228
 229         /**
 230         * Creates a resource proxy object so that get/put/observe functionality
 231         * can be used without discovering the object in advance.  Note that the
 232         * consumer of this method needs to provide all of the details required to
 233         * correctly contact and observe the object. If the consumer lacks any of
 234         * this information, they should discover the resource object normally.
 235         * Additionally, you can only create this object if OCPlatform was initialized
 236         * to be a Client or Client/Server.  Otherwise, this will return an empty
 237         * shared ptr.
 238         *
 239         * @param host - a string containing a resolvable host address of the server
 240         *           holding the resource. Currently this should be in the format
 241         *           coap://address:port, though in the future, we expect this to
 242         *           change to //address:port
 243         *
 244         * @param uri - the rest of the resource's URI that will permit messages to be
 245         *           properly routed.  Example: /a/light
 246         *
 247         * @param isObservable - a boolean containing whether the resource supports observation
 248         *
 249         * @param resourceTypes - a collection of resource types implemented by the resource
 250         *
 251         * @param interfaces - a collection of interfaces that the resource supports/implements
 252         * @return OCResource::Ptr - a shared pointer to the new resource object
 253         */
 254         OCResource::Ptr constructResourceObject(const std::string& host, const std::string& uri,
 255                         bool isObservable, const std::vector<std::string>& resourceTypes,
 256                         const std::vector<std::string>& interfaces);
 257     private:
 258         std::unique_ptr<WrapperFactory> m_WrapperInstance;
 259         IServerWrapper::Ptr m_server;
 260         IClientWrapper::Ptr m_client;
 261
 262         /**
 263         *  Private function to initalize the platfrom
 264         */
 265         void init(const PlatformConfig& config);
 266
 267         /**
 268         *  Private function cleanup the platform
 269         */
 270         void cleanup();
 271     };
 272 }
 273
 274 #endif //__OCPLATFORM_H
 275
 276