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