resource/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 /**
  22  * @file
  23  *
  24  * This file contains the declaration of classes and its members related to
  25  * OCPlatform.
  26  */
  27
  28 #ifndef __OCPLATFORM_H
  29 #define __OCPLATFORM_H
  30 #include <OCApi.h>
  31 #include <OCPlatform_impl.h>
  32 namespace OC
  33 {
  34     /**
  35     * @brief: This namespace contains the main entrance/functionality of the product.
  36     * It may be used with OC::OCPlatform::functionName.  To set a custom configuration,
  37     * the implementer must make a call to OCPlatform::Configure before the first usage
  38     * of a function in this namespace.
  39     */
  40     namespace OCPlatform
  41     {
  42         /**
  43         * API for overwriting the default configuration of the OCPlatform object.
  44         * Note: Any calls made to this AFTER the first call to OCPlatform::Instance
  45         * will have no affect
  46         */
  47         void Configure(const PlatformConfig& config);
  48
  49         // typedef for handle to cancel presence info with
  50         typedef OCDoHandle OCPresenceHandle;
  51
  52         /**
  53         * API for notifying base that resource's attributes have changed.
  54         *
  55         * @param OCResourceHandle resource handle of the resource
  56         * @param QualityOfService the quality of communication
  57         *
  58         * @return OCStackResult return value of this API. Returns OC_STACK_OK if success.
  59         * NOTE: This API is for server side only.
  60         * NOTE: OCResourceHandle is defined in ocstack.h.
  61         * NOTE: OCStackResult is defined in ocstack.h.
  62         */
  63         OCStackResult notifyAllObservers(OCResourceHandle resourceHandle);
  64         OCStackResult notifyAllObservers(OCResourceHandle resourceHandle, QualityOfService QoS);
  65
  66         /**
  67         * API for notifying only specific clients that resource's attributes have changed.
  68         *
  69         * @param OCResourceHandle resource handle of the resource
  70         * @param observationIds std vector of observationIds. These set of ids are ones which
  71         * which will be notified upon resource change.
  72         * @param responsePtr OCResourceResponse pointer used by app to fill the response for this
  73         * resource change.
  74         * @param QualityOfService the quality of communication
  75         *
  76         * @return OCStackResult return value of this API. Returns OC_STACK_OK if success.
  77         *
  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         OCStackResult notifyListOfObservers(
  83                     OCResourceHandle resourceHandle,
  84                     ObservationIds& observationIds,
  85                     const std::shared_ptr<OCResourceResponse> responsePtr);
  86         OCStackResult notifyListOfObservers(
  87                     OCResourceHandle resourceHandle,
  88                     ObservationIds& observationIds,
  89                     const std::shared_ptr<OCResourceResponse> responsePtr,
  90                     QualityOfService QoS);
  91
  92         /**
  93         * API for Service and Resource Discovery.
  94         * NOTE: This API applies to client side only.
  95         *
  96         * @param host - Host IP Address of a service to direct resource discovery query. If null or
  97         *        empty, performs multicast resource discovery query
  98         * @param resourceURI - name of the resource. If null or empty, performs search for all
  99         *       resource names
 100         * @param connectivityType - @ref OCConnectivityType type of connectivity indicating the
 101         *                           interface. Example: OC_WIFI, OC_ETHERNET, OC_ALL
 102         * @param handler - Handles callbacks, success states and failure states.
 103         *
 104         *        Four modes of discovery defined as follows:
 105         *        (NULL/Empty, NULL/Empty) - Performs ALL service discovery AND ALL resource
 106         *           discovery.
 107         *        (NULL/Empty, Not Empty) - Performs query for a filtered/scoped/particular
 108         *                                   resource(s) from ALL services.
 109         *        (Not Empty, NULL/Empty) - Performs ALL resource discovery on a particular service.
 110         *        (Not Empty, Not Empty) - Performs query for a filtered/scoped/particular
 111         *                                   resource(s)
 112         *                                  from a particular service.
 113         * @param QualityOfService the quality of communication
 114         *
 115         * @return OCStackResult return value of this API. Returns OC_STACK_OK if success.
 116         * NOTE: First parameter 'host' currently represents an IP address. This will change in
 117         * future and will refer to endpoint interface so that we can refer to other transports such
 118         * as BTH etc.
 119         * NOTE: OCStackResult is defined in ocstack.h.
 120         */
 121         OCStackResult findResource(const std::string& host, const std::string& resourceURI,
 122                     OCConnectivityType connectivityType, FindCallback resourceHandler);
 123         OCStackResult findResource(const std::string& host, const std::string& resourceURI,
 124                     OCConnectivityType connectivityType, FindCallback resourceHandler,
 125                     QualityOfService QoS);
 126
 127         /**
 128         * API for Device Discovery
 129         *
 130         *
 131         * @param host - Host IP Address. If null or empty, Multicast is performed.
 132         * @param deviceURI - Uri containing address to the virtual device in C Stack
 133                                 ("/oic/d")
 134         * @param connectivityType - @ref OCConnectivityType type of connectivity indicating the
 135         *                           interface. Example: OC_WIFI, OC_ETHERNET, OC_ALL
 136         * @param deviceInfoHandler - device discovery callback
 137         * @param QoS the quality of communication
 138         *
 139         */
 140         OCStackResult getDeviceInfo(const std::string& host, const std::string& deviceURI,
 141                     OCConnectivityType connectivityType, FindDeviceCallback deviceInfoHandler);
 142         OCStackResult getDeviceInfo(const std::string& host, const std::string& deviceURI,
 143                     OCConnectivityType connectivityType, FindDeviceCallback deviceInfoHandler,
 144                     QualityOfService QoS);
 145
 146         /**
 147         * API for Platform Discovery
 148         *
 149         *
 150         * @param host - Host IP Address. If null or empty, Multicast is performed.
 151         * @param platformURI - Uri containing address to the virtual platform in C Stack
 152                                 ("/oic/p")
 153         * @param connectivityType - @ref OCConnectivityType type of connectivity indicating the
 154         *                           interface. Example: OC_WIFI, OC_ETHERNET, OC_ALL
 155         * @param platformInfoHandler - platform discovery callback
 156         * @param QoS the quality of communication
 157         *
 158         */
 159         OCStackResult getPlatformInfo(const std::string& host, const std::string& platformURI,
 160                     OCConnectivityType connectivityType, FindPlatformCallback platformInfoHandler);
 161         OCStackResult getPlatformInfo(const std::string& host, const std::string& platformURI,
 162                     OCConnectivityType connectivityType, FindPlatformCallback platformInfoHandler,
 163                     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 and
 178         * 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/oic/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 parameter 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         OCStackResult registerResource(OCResourceHandle& resourceHandle,
 209                         const std::shared_ptr< OCResource > resource);
 210
 211         /**
 212         * Register Device Info
 213         *
 214         * @param deviceInfo - structure containing all the device specific information
 215         *
 216         * @return
 217         *      OC_STACK_OK   - no errors
 218         *      OC_STACK_ERROR - stack process error
 219         */
 220         OCStackResult registerDeviceInfo(const OCDeviceInfo deviceInfo);
 221
 222         /**
 223         * Register Platform Info
 224         *
 225         * @param platformInfo - structure containing all the platform specific information
 226         *
 227         * @return
 228         *      OC_STACK_OK   - no errors
 229         *      OC_STACK_ERROR - stack process error
 230         */
 231         OCStackResult registerPlatformInfo(const OCPlatformInfo platformInfo);
 232
 233         /**
 234         * Set default device entity handler
 235         *
 236         * @param entityHandler - entity handler to handle requests for
 237         *                        any undefined resources or default actions.
 238         *                        if NULL is passed it removes the device default entity handler.
 239         *
 240         * @return
 241         *     OC_STACK_OK    - no errors
 242         *     OC_STACK_ERROR - stack process error
 243         */
 244         OCStackResult setDefaultDeviceEntityHandler(EntityHandler entityHandler);
 245
 246         /**
 247         * This API unregisters a resource with the server
 248         * NOTE: This API applies to server side only.
 249         *
 250         * @param resourceHandle - This is the resource handle which we which to unregister from the
 251         * server
 252         *
 253         * @return OCStackResult return value of this API. Returns OC_STACK_OK if success.
 254         * NOTE: OCStackResult is defined in ocstack.h.
 255         */
 256         OCStackResult unregisterResource(const OCResourceHandle& resourceHandle);
 257
 258         /**
 259         * Add a resource to a collection resource.
 260         *
 261         * @param collectionHandle - handle to the collection resource
 262         * @param addedResourceHandle - handle to resource to be added to the collection resource
 263         *
 264         * @return OCStackResult return value of this API. Returns OC_STACK_OK if success.<br>
 265         * NOTE: OCStackResult is defined in ocstack.h. <br>
 266         * NOTE: bindResource must be used only after the both collection resource and
 267         * resource to add under a collections are created and respective handles obtained<br>
 268         * <b>Example:</b> <br>
 269         * Step 1: registerResource(homeResourceHandle, "a/home", "home", Link_Interface,
 270         *   entityHandler, OC_DISCOVERABLE | OC_OBSERVABLE);<br>
 271         * Step 2: registerResource(kitchenResourceHandle, "a/kitchen", "kitchen", Link_Interface,
 272         *   entityHandler, OC_DISCOVERABLE | OC_OBSERVABLE);<br>
 273         * Step 3: bindResource(homeResourceHandle, kitchenResourceHandle);<br>
 274         * At the end of Step 3, resource "a/home" will contain a reference to "a/kitchen".<br>
 275         */
 276         OCStackResult bindResource(const OCResourceHandle collectionHandle,
 277                 const OCResourceHandle resourceHandle);
 278
 279         /**
 280         * Add multiple resources to a collection resource.
 281         *
 282         * @param collectionHandle - handle to the collection resource
 283         * @param addedResourceHandleList reference to list of resource handles to be added to the
 284         *   collection resource
 285         *
 286         * @return OCStackResult return value of this API. Returns OC_STACK_OK if success. <br>
 287         * NOTE: OCStackResult is defined in ocstack.h. <br>
 288         * NOTE: bindResources must be used only after the both collection resource and
 289         * list of resources to add under a collection are created and respective handles
 290         * obtained <br>
 291         * <b> Example: </b> <br>
 292         * Step 1: registerResource(homeResourceHandle, "a/home", "home", Link_Interface,
 293         *   homeEntityHandler, OC_DISCOVERABLE | OC_OBSERVABLE);<br>
 294         * Step 2: registerResource(kitchenResourceHandle, "a/kitchen", "kitchen", Link_Interface,
 295         *   kitchenEntityHandler, OC_DISCOVERABLE | OC_OBSERVABLE);<br>
 296         * Step 3: registerResource(roomResourceHandle, "a/room", "room", Link_Interface,
 297         *   roomEntityHandler, OC_DISCOVERABLE | OC_OBSERVABLE);<br>
 298         * Step 4: std::vector<OCResourceHandle> rList; rList.push_back(kitchenResourceHandle);
 299         *   rList.push_back(roomResourceHandle);<br>
 300         * Step 5: bindResource(homeResourceHandle, rList);<br>
 301         * At the end of Step 5, resource "a/home" will contain a references to "a/kitchen" and
 302         *   "a/room" <br>
 303         */
 304         OCStackResult bindResources(const OCResourceHandle collectionHandle,
 305                 const std::vector<OCResourceHandle>& addedResourceHandleList);
 306
 307         /**
 308         * Unbind a resource from a collection resource.
 309         *
 310         * @param collectionHandle - handle to the collection resource
 311         * @param resourceHandle resource handle to be unbound from the collection resource
 312         *
 313         * @return OCStackResult return value of this API. Returns OC_STACK_OK if success. <br>
 314         * NOTE: OCStackResult is defined in ocstack.h.<br>
 315         * NOTE: unbindResource must be used only after the both collection resource and
 316         * resource to unbind from a collection are created and respective handles obtained<br>
 317         * <b> Example </b> <br>
 318         * Step 1: registerResource(homeResourceHandle, "a/home", "home", Link_Interface,
 319         *   entityHandler, OC_DISCOVERABLE | OC_OBSERVABLE);<br>
 320         * Step 2: registerResource(kitchenResourceHandle, "a/kitchen", "kitchen", Link_Interface,
 321         *   entityHandler, OC_DISCOVERABLE | OC_OBSERVABLE);<br>
 322         * Step 3: bindResource(homeResourceHandle, kitchenResourceHandle);<br>
 323         * Step 4: unbindResource(homeResourceHandle, kitchenResourceHandle);<br>
 324         * At the end of Step 4, resource "a/home" will no longer reference "a/kitchen". <br>
 325         */
 326         OCStackResult unbindResource(const OCResourceHandle collectionHandle,
 327                     const OCResourceHandle resourceHandle);
 328
 329         /**
 330         * Unbind resources from a collection resource.
 331         *
 332         * @param collectionHandle - handle to the collection resource
 333         * @param resourceHandleList List of resource handles to be unbound from the collection
 334         *   resource
 335         *
 336         * @return OCStackResult return value of this API. Returns OC_STACK_OK if success. <br>
 337         *
 338         * NOTE: OCStackResult is defined in ocstack.h.<br>
 339         * NOTE: unbindResources must be used only after the both collection resource and
 340         * list of resources resource to unbind from a collection are created and respective handles
 341         *   obtained. <br>
 342         * <b>Example</b> <br>
 343         * Step 1: registerResource(homeResourceHandle, "a/home", "home", Link_Interface,
 344         *   homeEntityHandler, OC_DISCOVERABLE | OC_OBSERVABLE);<br>
 345         * Step 2: registerResource(kitchenResourceHandle, "a/kitchen", "kitchen", Link_Interface,
 346         *   kitchenEntityHandler, OC_DISCOVERABLE | OC_OBSERVABLE);<br>
 347         * Step 3: registerResource(roomResourceHandle, "a/room", "room", Link_Interface,
 348         *   roomEntityHandler, OC_DISCOVERABLE | OC_OBSERVABLE);<br>
 349         * Step 4: std::vector<OCResourceHandle> rList; rList.push_back(kitchenResourceHandle);
 350         *   rList.push_back(roomResourceHandle);<br>
 351         * Step 5: bindResource(homeResourceHandle, rList);<br>
 352         * Step 6: unbindResources(homeResourceHandle, rList);<br>
 353         * At the end of Step 6, resource "a/home" will no longer reference to "a/kitchen" and
 354         *   "a/room"<br>
 355         */
 356         OCStackResult unbindResources(const OCResourceHandle collectionHandle,
 357                         const std::vector<OCResourceHandle>& resourceHandleList);
 358
 359         /**
 360         * Binds a type to a particular resource
 361         * @param resourceHandle - handle to the resource
 362         * @param resourceTypeName - new typename to bind to the resource
 363
 364         * @return OCStackResult - return value of the API. Returns OCSTACK_OK if success <br>
 365         */
 366         OCStackResult bindTypeToResource(const OCResourceHandle& resourceHandle,
 367                         const std::string& resourceTypeName);
 368
 369         /**
 370         * Binds an interface to a particular resource
 371         * @param resourceHandle - handle to the resource
 372         * @param resourceTypeName - new interface  to bind to the resource
 373
 374         * @return OCStackResult - return value of the API. Returns OCSTACK_OK if success <br>
 375         */
 376         OCStackResult bindInterfaceToResource(const OCResourceHandle& resourceHandle,
 377                         const std::string& resourceInterfaceName);
 378
 379
 380         /**
 381         * Start Presence announcements.
 382         *
 383         * @param ttl - time to live
 384         * Note: If ttl is '0', then the default stack value will be used (60 Seconds).
 385         *
 386         *       If ttl is greater than OC_MAX_PRESENCE_TTL_SECONDS, then the ttl will be set to
 387         *       OC_MAX_PRESENCE_TTL_SECONDS.
 388         *
 389         * @return OCStackResult - Returns OCSTACK_OK if success <br>
 390         *
 391         * Server can call this function when it comes online for the
 392         * first time, or when it comes back online from offline mode,
 393         * or when it re enters network.
 394         *
 395         */
 396         OCStackResult startPresence(const unsigned int ttl);
 397
 398         /**
 399         * Stop Presence announcements.
 400         *
 401         * @return OCStackResult - Returns OCSTACK_OK if success <br>
 402         *
 403         * Server can call this function when it is terminating,
 404         * going offline, or when going away from network.
 405         *
 406         */
 407         OCStackResult stopPresence();
 408
 409         /**
 410         * subscribes to a server's presence change events.  By making this subscription,
 411         * every time a server adds/removes/alters a resource, starts or is intentionally
 412         * stopped (potentially more to be added later).
 413         *
 414         * @param presenceHandle - a handle object that can be used to identify this subscription
 415         *               request.  It can be used to unsubscribe from these events in the future.
 416         *               It will be set upon successful return of this method.
 417         * @param host - The IP address/addressable name of the server to subscribe to.
 418         *               This should be in the format coap://address:port
 419         * @param connectivityType - @ref OCConnectivityType type of connectivity indicating the
 420         *                           interface. Example: OC_WIFI, OC_ETHERNET, OC_ALL
 421         * @param resourceType - a resource type specified as a filter for subscription callbacks.
 422         * @param presenceHandler - callback function that will receive notifications/subscription
 423         *               events
 424         *
 425         * @return OCStackResult - return value of the API.  Returns OCSTACK_OK if success <br>
 426         */
 427         OCStackResult subscribePresence(OCPresenceHandle& presenceHandle, const std::string& host,
 428                         OCConnectivityType connectivityType, SubscribeCallback presenceHandler);
 429         OCStackResult subscribePresence(OCPresenceHandle& presenceHandle, const std::string& host,
 430                         const std::string& resourceType, OCConnectivityType connectivityType,
 431                         SubscribeCallback presenceHandler);
 432
 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 connectivityType - @ref OCConnectivityType type of connectivity indicating the
 464         *                           interface. Example: OC_WIFI, OC_ETHERNET, OC_ALL
 465         *
 466         * @param isObservable - a boolean containing whether the resource supports observation
 467         *
 468         * @param resourceTypes - a collection of resource types implemented by the resource
 469         *
 470         * @param interfaces - a collection of interfaces that the resource supports/implements
 471         * @return OCResource::Ptr - a shared pointer to the new resource object
 472         */
 473         OCResource::Ptr constructResourceObject(const std::string& host,
 474                         const std::string& uri,
 475                         OCConnectivityType connectivityType, bool isObservable,
 476                         const std::vector<std::string>& resourceTypes,
 477                         const std::vector<std::string>& interfaces);
 478
 479         /**
 480         * Allows application entity handler to send response to an incoming request.
 481         *
 482         * @param pResponse - OCResourceResponse pointer that will permit to set values related
 483         * to resource response. <br>
 484         * @return OCStackResult - return value of the API. Returns OCSTACK_OK if success <br>
 485         */
 486         OCStackResult sendResponse(const std::shared_ptr<OCResourceResponse> pResponse);
 487     }
 488 }
 489
 490 #endif //__OCPLATFORM_H
 491
 492
 493