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 OC_PLATFORM_H_
  29 #define OC_PLATFORM_H_
  30 #include <OCApi.h>
  31 #include <OCPlatform_impl.h>
  32 namespace OC
  33 {
  34     /**
  35     * 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 stop Base layer including resource and connectivity abstraction.
  54          * The API is reference counted. The calls to start and stop need to be balanced.
  55          *
  56          * @return Returns ::OC_STACK_OK if success.
  57          */
  58         OCStackResult stop();
  59
  60         /**
  61          * API for start Base layer including resource and connectivity abstraction.
  62          * OCInit will be invoked.
  63          * The API is reference counted. The calls to start and stop need to be balanced.
  64          *
  65          * @return Returns ::OC_STACK_OK if success.
  66          */
  67         OCStackResult start();
  68
  69         /**
  70          * API for notifying base that resource's attributes have changed.
  71          *
  72          * @param resourceHandle resource handle of the resource
  73          *
  74          * @return Returns ::OC_STACK_OK if success.
  75          * @note This API is for server side only.
  76          * @note OCResourceHandle is defined in ocstack.h
  77          * @note OCStackResult is defined in ocstack.h.
  78          * @see notifyAllObservers(OCResourceHandle, QualityOfService)
  79          */
  80         OCStackResult notifyAllObservers(OCResourceHandle resourceHandle);
  81
  82         /**
  83          * @overload
  84          *
  85          * @param resourceHandle resource handle of the resource
  86          * @param QoS the quality of communication
  87          * @see notifyAllObservers(OCResourceHandle)
  88          */
  89         OCStackResult notifyAllObservers(OCResourceHandle resourceHandle, QualityOfService QoS);
  90
  91         /**
  92          * API for notifying only specific clients that resource's attributes have changed.
  93          *
  94          * @param resourceHandle resource handle of the resource
  95          * @param observationIds std vector of observationIds. These set of ids are ones which
  96          * which will be notified upon resource change.
  97          * @param responsePtr OCResourceResponse pointer used by app to fill the response for this
  98          * resource change.
  99          *
 100          * @return Returns ::OC_STACK_OK if success.
 101          * @note This API is for server side only.
 102          * @note OCResourceHandle is defined in ocstack.h.
 103          * @note OCStackResult is defined in ocstack.h.
 104          * @see notifyListOfObservers(OCResourceHandle, ObservationIds&, const std::shared_ptr<OCResourceResponse>, QualityOfService)
 105          */
 106         OCStackResult notifyListOfObservers(
 107                     OCResourceHandle resourceHandle,
 108                     ObservationIds& observationIds,
 109                     const std::shared_ptr<OCResourceResponse> responsePtr);
 110         /**
 111          * @overload
 112          *
 113          * @param resourceHandle resource handle of the resource
 114          * @param observationIds std vector of observationIds. These set of ids are ones which
 115          * which will be notified upon resource change.
 116          * @param responsePtr OCResourceResponse pointer used by app to fill the response for this
 117          * resource change.
 118          * @param QoS the quality of communication
 119          * @see notifyListOfObservers(OCResourceHandle, ObservationIds&, const std::shared_ptr<OCResourceResponse>)
 120          */
 121         OCStackResult notifyListOfObservers(
 122                     OCResourceHandle resourceHandle,
 123                     ObservationIds& observationIds,
 124                     const std::shared_ptr<OCResourceResponse> responsePtr,
 125                     QualityOfService QoS);
 126
 127         /**
 128         * Gets a resource handle by resource uri.
 129         *
 130         * @param uri   Uri of Resource to get Resource handle.
 131         *
 132         * @return Found  resource handle or NULL if not found.
 133         */
 134         OCResourceHandle getResourceHandleAtUri(const std::string& uri);
 135
 136         /**
 137          * API for Service and Resource Discovery.
 138          * @note This API applies to client side only.
 139          *
 140          * @param host Host IP Address of a service to direct resource discovery query. If null or
 141          *        empty, performs multicast resource discovery query
 142          * @param resourceURI name of the resource. If null or empty, performs search for all
 143          *       resource names
 144          * @param connectivityType ::OCConnectivityType type of connectivity indicating the
 145          *                           interface. Example: CT_DEFAULT, CT_ADAPTER_IP, CT_ADAPTER_TCP.
 146          * @param resourceHandler Handles callbacks, success states and failure states.
 147          *
 148          *        Four modes of discovery defined as follows:
 149          *        (NULL/Empty, NULL/Empty) - Performs ALL service discovery AND ALL resource
 150          *           discovery.
 151          *        (NULL/Empty, Not Empty) - Performs query for a filtered/scoped/particular
 152          *                                   resource(s) from ALL services.
 153          *        (Not Empty, NULL/Empty) - Performs ALL resource discovery on a particular service.
 154          *        (Not Empty, Not Empty) - Performs query for a filtered/scoped/particular
 155          *                                   resource(s)
 156          *                                  from a particular service.
 157          *
 158          * @return Returns ::OC_STACK_OK if success.
 159          * @note First parameter 'host' currently represents an IP address. This will change in
 160          * future and will refer to endpoint interface so that we can refer to other transports such
 161          * as BTH etc.
 162          * @note OCStackResult is defined in ocstack.h.
 163          * @see findResource(const std::string&, const std::string&, OCConnectivityType, FindCallback, QualityOfService)
 164          * @note To get the tcpPort information, user must call getAllHosts() from the OCResource
 165            object in FindCallback. To use a TCP endpoint that has been received by getAllHosts(),
 166            user must use the setHost() function.
 167          */
 168         OCStackResult findResource(const std::string& host, const std::string& resourceURI,
 169                     OCConnectivityType connectivityType, FindCallback resourceHandler);
 170         /**
 171          * @overload
 172          *
 173          * @param host Host IP Address of a service to direct resource discovery query. If null or
 174          *        empty, performs multicast resource discovery query
 175          * @param resourceURI name of the resource. If null or empty, performs search for all
 176          *       resource names
 177          * @param connectivityType ::OCConnectivityType type of connectivity indicating the
 178          *                           interface. Example: CT_DEFAULT, CT_ADAPTER_IP, CT_ADAPTER_TCP.
 179          * @param resourceHandler Handles callbacks, success states and failure states.
 180          *
 181          *        Four modes of discovery defined as follows:
 182          *        (NULL/Empty, NULL/Empty) - Performs ALL service discovery AND ALL resource
 183          *           discovery.
 184          *        (NULL/Empty, Not Empty) - Performs query for a filtered/scoped/particular
 185          *                                   resource(s) from ALL services.
 186          *        (Not Empty, NULL/Empty) - Performs ALL resource discovery on a particular service.
 187          *        (Not Empty, Not Empty) - Performs query for a filtered/scoped/particular
 188          *                                   resource(s)
 189          *                                  from a particular service.
 190          * @param QoS QualityOfService the quality of communication
 191          * @see findResource(const std::string&, const std::string&, OCConnectivityType, FindCallback)
 192          * @note To get the tcpPort information, user must call getAllHosts() from the OCResource
 193            object in FindCallback. To use a TCP endpoint that has been received by getAllHosts(),
 194            user must use the setHost() function.
 195          */
 196         OCStackResult findResource(const std::string& host, const std::string& resourceURI,
 197                     OCConnectivityType connectivityType, FindCallback resourceHandler,
 198                     QualityOfService QoS);
 199
 200         OCStackResult findResource(const std::string& host, const std::string& resourceURI,
 201                     OCConnectivityType connectivityType, FindCallback resourceHandler,
 202                     FindErrorCallback errorHandler);
 203
 204         OCStackResult findResource(const std::string& host, const std::string& resourceURI,
 205                     OCConnectivityType connectivityType, FindCallback resourceHandler,
 206                     FindErrorCallback errorHandler, QualityOfService QoS);
 207
 208         OCStackResult findResourceList(const std::string& host, const std::string& resourceURI,
 209                     OCConnectivityType connectivityType, FindResListCallback resourceHandler,
 210                     QualityOfService QoS = QualityOfService::LowQos);
 211
 212         OCStackResult findResourceList(const std::string& host, const std::string& resourceURI,
 213                     OCConnectivityType connectivityType, FindResListCallback resourceHandler,
 214                     FindErrorCallback errorHandler, QualityOfService QoS = QualityOfService::LowQos);
 215
 216         OCStackResult setPropertyValue(OCPayloadType type, const std::string& tag,
 217                     const std::string& value);
 218         OCStackResult setPropertyValue(OCPayloadType type, const std::string& tag,
 219                     const std::vector<std::string>& value);
 220         OCStackResult getPropertyValue(OCPayloadType type, const std::string& tag,
 221                     std::string& value);
 222         OCStackResult getPropertyValue(OCPayloadType type, const std::string& tag,
 223                     std::vector<std::string>& value);
 224         /**
 225          * API for Device Discovery
 226          *
 227          *
 228          * @param host Host IP Address. If null or empty, Multicast is performed.
 229          * @param deviceURI Uri containing address to the virtual device in C Stack
 230                                 ("/oic/d")
 231          * @param connectivityType ::OCConnectivityType type of connectivity indicating the
 232          *                           interface. Example: CT_DEFAULT, CT_ADAPTER_IP, CT_ADAPTER_TCP.
 233          * @param deviceInfoHandler device discovery callback
 234          *
 235          * @return Returns ::OC_STACK_OK if success.
 236          * @note OCStackResult is defined in ocstack.h.
 237          * @see getDeviceInfo(const std::string&, const std::string&, OCConnectivityType, FindDeviceCallback, QualityOfService)
 238          */
 239         OCStackResult getDeviceInfo(const std::string& host, const std::string& deviceURI,
 240                     OCConnectivityType connectivityType, FindDeviceCallback deviceInfoHandler);
 241         /**
 242          * @overload
 243          *
 244          * @param host Host IP Address. If null or empty, Multicast is performed.
 245          * @param deviceURI Uri containing address to the virtual device in C Stack
 246                                 ("/oic/d")
 247          * @param connectivityType ::OCConnectivityType type of connectivity indicating the
 248          *                           interface. Example: CT_DEFAULT, CT_ADAPTER_IP, CT_ADAPTER_TCP.
 249          * @param deviceInfoHandler device discovery callback
 250          * @param QoS the quality of communication
 251          * @see getDeviceInfo(const std::string&, const std::string&, OCConnectivityType, FindDeviceCallback)
 252          */
 253         OCStackResult getDeviceInfo(const std::string& host, const std::string& deviceURI,
 254                     OCConnectivityType connectivityType, FindDeviceCallback deviceInfoHandler,
 255                     QualityOfService QoS);
 256
 257         /**
 258          * API for Platform Discovery
 259          *
 260          *
 261          * @param host Host IP Address. If null or empty, Multicast is performed.
 262          * @param platformURI Uri containing address to the virtual platform in C Stack
 263                                 ("/oic/p")
 264          * @param connectivityType ::OCConnectivityType type of connectivity indicating the
 265          *                           interface. Example: CT_DEFAULT, CT_ADAPTER_IP, CT_ADAPTER_TCP.
 266          * @param platformInfoHandler platform discovery callback
 267          *
 268          * @return Returns ::OC_STACK_OK if success.
 269          *
 270          * @note OCStackResult is defined in ocstack.h.
 271          * @see getPlatformInfo(const std::string&, const std::string&, OCConnectivityType, FindPlatformCallback, QualityOfService)
 272          */
 273         OCStackResult getPlatformInfo(const std::string& host, const std::string& platformURI,
 274                     OCConnectivityType connectivityType, FindPlatformCallback platformInfoHandler);
 275         /**
 276          * @overload
 277          *
 278          * @param host Host IP Address. If null or empty, Multicast is performed.
 279          * @param platformURI Uri containing address to the virtual platform in C Stack
 280                                 ("/oic/p")
 281          * @param connectivityType ::OCConnectivityType type of connectivity indicating the
 282          *                           interface. Example: CT_DEFAULT, CT_ADAPTER_IP, CT_ADAPTER_TCP.
 283          * @param platformInfoHandler platform discovery callback
 284          * @param QoS the quality of communication
 285          * @see getPlatformInfo(const std::string&, const std::string&, OCConnectivityType, FindPlatformCallback)
 286          */
 287         OCStackResult getPlatformInfo(const std::string& host, const std::string& platformURI,
 288                     OCConnectivityType connectivityType, FindPlatformCallback platformInfoHandler,
 289                     QualityOfService QoS);
 290
 291         /**
 292          * This function returns flags of supported endpoint TPS on stack.
 293          *
 294          * @param[out] supportedTps Bit combinations of supported OCTpsSchemeFlags.
 295          *
 296          * @return Returns ::OC_STACK_OK if success.
 297          */
 298         OCStackResult getSupportedTransportsInfo(OCTpsSchemeFlags& supportedTps);
 299
 300         /**
 301         * This API registers a resource with the server
 302         * @note This API applies to server side only.
 303         *
 304         * @param resourceHandle Upon successful registration, resourceHandle will be filled
 305         * @param resourceURI The URI of the resource. Example: "a/light". See NOTE below
 306         * @param resourceTypeName The resource type. Example: "core.light"
 307         * @param resourceInterface The resource interface (whether it is collection etc).
 308         * @param entityHandler entity handler callback.
 309         * @param resourceProperty indicates the property of the resource. Defined in octypes.h.
 310         * setting resourceProperty as OC_DISCOVERABLE will allow Discovery of this resource
 311         * setting resourceProperty as OC_OBSERVABLE will allow observation
 312         * setting resourceProperty as OC_DISCOVERABLE | OC_OBSERVABLE will allow both discovery
 313         * and observation
 314         *
 315         * @return Returns ::OC_STACK_OK if success.
 316         * @note "a/light" is a relative reference to URI.
 317         * Above relative reference to URI will be prepended (by core) with a host IP
 318         * Therefore, fully qualified URI format would be
 319         * "CoAP(s)+protocol-URI-Scheme://HostIP-Address/relativeURI"
 320         * Example, a relative reference to URI: 'a/light' will result in a fully qualified URI:
 321         *   "coap://192.168.1.1:5246/a/light", "coaps://192.168.1.1:5246/a/light"
 322         * @note OCStackResult is defined in octypes.h.
 323         * @note entity handler callback :
 324         * When you set specific return value like OC_EH_CHANGED, OC_EH_CONTENT,
 325         * OC_EH_SLOW and etc in entity handler callback,
 326         * ocstack will be not send response automatically to client
 327         * except for error return value like OC_EH_ERROR
 328         * If you want to send response to client with specific result,
 329         * OCDoResponse API should be called with the result value.
 330         */
 331         OCStackResult registerResource(OCResourceHandle& resourceHandle,
 332                         std::string& resourceURI,
 333                         const std::string& resourceTypeName,
 334                         const std::string& resourceInterface,
 335                         EntityHandler entityHandler,
 336                         uint8_t resourceProperty);
 337
 338         /**
 339         * This API registers a resource with the server
 340         * @note This API applies to server side only.
 341         *
 342         * @param resourceHandle Upon successful registration, resourceHandle will be filled
 343         * @param resourceURI The URI of the resource. Example: "a/light". See NOTE below
 344         * @param resourceTypeName The resource type. Example: "core.light"
 345         * @param resourceInterface The resource interface (whether it is collection etc).
 346         * @param entityHandler Entity handler callback.
 347         * @param resourceProperty indicates the property of the resource. Defined in octypes.h.
 348         * @param resourceTpsTypes Transport Protocol Suites(TPS) types of resource for
 349                                   open resource to specific transport adapter (e.g., TCP, UDP)
 350                                   with messaging protocol(e.g., COAP, COAPS).
 351                                   Example: "OC_COAP | OC_COAP_TCP"
 352         * setting resourceProperty as OC_DISCOVERABLE will allow Discovery of this resource
 353         * setting resourceProperty as OC_OBSERVABLE will allow observation
 354         * setting resourceProperty as OC_DISCOVERABLE | OC_OBSERVABLE will allow both discovery
 355         * and observation
 356         *
 357         * @return Returns ::OC_STACK_OK if success.
 358         * @note "a/light" is a relative reference to URI.
 359         * Above relative reference to URI will be prepended (by core) with a host IP
 360         * Therefore, fully qualified URI format would be
 361         * "CoAP(s)+protocol-URI-Scheme://HostIP-Address/relativeURI"
 362         * Example, a relative reference to URI: 'a/light' will result in a fully qualified URI:
 363         *   "coap://192.168.1.1:5246/a/light", "coaps://192.168.1.1:5246/a/light"
 364         * @note OCStackResult is defined in octypes.h.
 365         * @note entity handler callback :
 366         * When you set specific return value like OC_EH_CHANGED, OC_EH_CONTENT,
 367         * OC_EH_SLOW and etc in entity handler callback,
 368         * ocstack will be not send response automatically to client
 369         * except for error return value like OC_EH_ERROR
 370         * If you want to send response to client with specific result,
 371         * OCDoResponse API should be called with the result value.
 372         */
 373         OCStackResult registerResource(OCResourceHandle& resourceHandle,
 374                         std::string& resourceURI,
 375                         const std::string& resourceTypeName,
 376                         const std::string& resourceInterface,
 377                         EntityHandler entityHandler,
 378                         uint8_t resourceProperty,
 379                         OCTpsSchemeFlags resourceTpsTypes);
 380
 381         /**
 382          * This API registers a resource with the server
 383          * @note This API applies to server & client side.
 384          *
 385          * @param resourceHandle Upon successful registration, resourceHandle will be filled
 386          * @param resource The instance of OCResource that all data filled.
 387          *
 388          * @return Returns ::OC_STACK_OK if success.
 389          * @note OCStackResult is defined in ocstack.h.
 390          */
 391         OCStackResult registerResource(OCResourceHandle& resourceHandle,
 392                         const std::shared_ptr< OCResource > resource);
 393
 394         /**
 395         * Register Device Info
 396         *
 397         * @deprecated: Use setPropertyValue instead.
 398         *
 399         * @param deviceInfo structure containing all the device specific information
 400         * @return Returns ::OC_STACK_OK  if no errors and ::OC_STACK_ERROR in case of stack process error
 401         */
 402         OCStackResult registerDeviceInfo(const OCDeviceInfo deviceInfo);
 403
 404         /**
 405         * Register Platform Info
 406         *
 407         * @param platformInfo structure containing all the platform specific information
 408         * @return Returns ::OC_STACK_OK if no errors and ::OC_STACK_ERROR in case of stack process error
 409         */
 410         OCStackResult registerPlatformInfo(const OCPlatformInfo platformInfo);
 411
 412         /**
 413         * Set default device entity handler
 414         *
 415         * @param entityHandler entity handler to handle requests for
 416         *                      any undefined resources or default actions.
 417         *                      if NULL is passed it removes the device default entity handler.
 418         * @return Returns ::OC_STACK_OK  if no errors and ::OC_STACK_ERROR in case of stack process error
 419         * @note entity handler callback :
 420         * When you set specific return value like OC_EH_CHANGED, OC_EH_CONTENT,
 421         * OC_EH_SLOW and etc in entity handler callback,
 422         * ocstack will be not send response automatically to client
 423         * except for error return value like OC_EH_ERROR
 424         * If you want to send response to client with specific result,
 425         * sendResponse API should be called with the result value.
 426         */
 427         OCStackResult setDefaultDeviceEntityHandler(EntityHandler entityHandler);
 428
 429         /**
 430         * This API unregisters a resource with the server
 431         * @note This API applies to server side only.
 432         *
 433         * @param resourceHandle This is the resource handle which we need to unregister from the
 434         * server
 435         *
 436         * @return Returns ::OC_STACK_OK if success.
 437         * @note OCStackResult is defined in ocstack.h.
 438         */
 439         OCStackResult unregisterResource(const OCResourceHandle& resourceHandle);
 440
 441         /**
 442         * Add a resource to a collection resource.
 443         *
 444         * @param collectionHandle handle to the collection resource
 445         * @param resourceHandle handle to resource to be added to the collection resource
 446         *
 447         * @return Returns ::OC_STACK_OK if success.
 448         * @note OCStackResult is defined in ocstack.h.
 449         * @note bindResource must be used only after the both collection resource and
 450         * resource to add under a collections are created and respective handles obtained
 451         *
 452         * @par Example:
 453         * -# registerResource(homeResourceHandle, "a/home", "home", Link_Interface,
 454         *   entityHandler, OC_DISCOVERABLE | OC_OBSERVABLE);
 455         * -# registerResource(kitchenResourceHandle, "a/kitchen", "kitchen", Link_Interface,
 456         *   entityHandler, OC_DISCOVERABLE | OC_OBSERVABLE);
 457         * -# bindResource(homeResourceHandle, kitchenResourceHandle);
 458         * @par
 459         * At the end of Step 3, resource "a/home" will contain a reference to "a/kitchen".
 460         */
 461         OCStackResult bindResource(const OCResourceHandle collectionHandle,
 462                 const OCResourceHandle resourceHandle);
 463
 464         /**
 465         * Add multiple resources to a collection resource.
 466         *
 467         * @param collectionHandle handle to the collection resource
 468         * @param addedResourceHandleList reference to list of resource handles to be added to the
 469         *   collection resource
 470         *
 471         * @return Returns ::OC_STACK_OK if success.
 472         * @note OCStackResult is defined in ocstack.h.
 473         * @note bindResources must be used only after the both collection resource and
 474         * list of resources to add under a collection are created and respective handles
 475         * obtained.
 476         *
 477         * @par Example:
 478         * -# registerResource(homeResourceHandle, "a/home", "home", Link_Interface,
 479         *   homeEntityHandler, OC_DISCOVERABLE | OC_OBSERVABLE);
 480         * -# registerResource(kitchenResourceHandle, "a/kitchen", "kitchen", Link_Interface,
 481         *   kitchenEntityHandler, OC_DISCOVERABLE | OC_OBSERVABLE);
 482         * -# registerResource(roomResourceHandle, "a/room", "room", Link_Interface,
 483         *   roomEntityHandler, OC_DISCOVERABLE | OC_OBSERVABLE);
 484         * -# std::vector<OCResourceHandle> rList; rList.push_back(kitchenResourceHandle);
 485         *   rList.push_back(roomResourceHandle);
 486         * -# bindResource(homeResourceHandle, rList);
 487         * @par
 488         * At the end of Step 5, resource "a/home" will contain a references to "a/kitchen" and
 489         *   "a/room"
 490         */
 491         OCStackResult bindResources(const OCResourceHandle collectionHandle,
 492                 const std::vector<OCResourceHandle>& addedResourceHandleList);
 493
 494         /**
 495         * Unbind a resource from a collection resource.
 496         *
 497         * @param collectionHandle handle to the collection resource
 498         * @param resourceHandle resource handle to be unbound from the collection resource
 499         *
 500         * @return Returns ::OC_STACK_OK if success.
 501         * @note OCStackResult is defined in ocstack.h.
 502         * @note unbindResource must be used only after the both collection resource and
 503         * resource to unbind from a collection are created and respective handles obtained
 504         *
 505         * @par Example:
 506         * -# registerResource(homeResourceHandle, "a/home", "home", Link_Interface,
 507         *   entityHandler, OC_DISCOVERABLE | OC_OBSERVABLE);
 508         * -# registerResource(kitchenResourceHandle, "a/kitchen", "kitchen", Link_Interface,
 509         *   entityHandler, OC_DISCOVERABLE | OC_OBSERVABLE);
 510         * -# bindResource(homeResourceHandle, kitchenResourceHandle);
 511         * -# unbindResource(homeResourceHandle, kitchenResourceHandle);
 512         * @par
 513         * At the end of Step 4, resource "a/home" will no longer reference "a/kitchen".
 514         */
 515         OCStackResult unbindResource(const OCResourceHandle collectionHandle,
 516                     const OCResourceHandle resourceHandle);
 517
 518         /**
 519         * Unbind resources from a collection resource.
 520         *
 521         * @param collectionHandle handle to the collection resource
 522         * @param resourceHandleList List of resource handles to be unbound from the collection
 523         *   resource
 524         *
 525         * @return Returns ::OC_STACK_OK if success.
 526         * @note OCStackResult is defined in ocstack.h.
 527         * @note unbindResources must be used only after the both collection resource and
 528         * list of resources resource to unbind from a collection are created and respective handles
 529         *   obtained.
 530         *
 531         * @par Example:
 532         * -# registerResource(homeResourceHandle, "a/home", "home", Link_Interface,
 533         *   homeEntityHandler, OC_DISCOVERABLE | OC_OBSERVABLE);
 534         * -# registerResource(kitchenResourceHandle, "a/kitchen", "kitchen", Link_Interface,
 535         *   kitchenEntityHandler, OC_DISCOVERABLE | OC_OBSERVABLE);
 536         * -# registerResource(roomResourceHandle, "a/room", "room", Link_Interface,
 537         *   roomEntityHandler, OC_DISCOVERABLE | OC_OBSERVABLE);
 538         * -# std::vector<OCResourceHandle> rList; rList.push_back(kitchenResourceHandle);
 539         *   rList.push_back(roomResourceHandle);
 540         * -# bindResource(homeResourceHandle, rList);
 541         * -# unbindResources(homeResourceHandle, rList);
 542         * @par
 543         * At the end of Step 6, resource "a/home" will no longer reference to "a/kitchen" and
 544         *   "a/room"
 545         */
 546         OCStackResult unbindResources(const OCResourceHandle collectionHandle,
 547                         const std::vector<OCResourceHandle>& resourceHandleList);
 548
 549         /**
 550         * Binds a type to a particular resource
 551         * @param resourceHandle handle to the resource
 552         * @param resourceTypeName new typename to bind to the resource
 553         *
 554         * @return Returns ::OC_STACK_OK if success.
 555         */
 556         OCStackResult bindTypeToResource(const OCResourceHandle& resourceHandle,
 557                         const std::string& resourceTypeName);
 558
 559         /**
 560         * Binds an interface to a particular resource
 561         * @param resourceHandle handle to the resource
 562         * @param resourceInterfaceName new interface  to bind to the resource
 563         *
 564         * @return Returns ::OC_STACK_OK if success.
 565         */
 566         OCStackResult bindInterfaceToResource(const OCResourceHandle& resourceHandle,
 567                         const std::string& resourceInterfaceName);
 568
 569
 570         /**
 571         * Start Presence announcements.
 572         *
 573         * @param ttl time to live
 574         * @par
 575         * If ttl is '0', then the default stack value will be used (60 Seconds).
 576         * If ttl is greater than OC_MAX_PRESENCE_TTL_SECONDS, then the ttl will be set to
 577         * OC_MAX_PRESENCE_TTL_SECONDS.
 578         * @par
 579         * @return Returns ::OC_STACK_OK if success.
 580         *
 581         * Server can call this function when it comes online for the
 582         * first time, or when it comes back online from offline mode,
 583         * or when it re enters network.
 584         *
 585         */
 586         OCStackResult startPresence(const unsigned int ttl);
 587
 588         /**
 589         * Stop Presence announcements.
 590         *
 591         * @return Returns ::OC_STACK_OK if success.
 592         *
 593         * Server can call this function when it is terminating,
 594         * going offline, or when going away from network.
 595         *
 596         */
 597         OCStackResult stopPresence();
 598
 599         /**
 600          * subscribes to a server's presence change events.  By making this subscription,
 601          * every time a server adds/removes/alters a resource, starts or is intentionally
 602          * stopped (potentially more to be added later).
 603          *
 604          * @param presenceHandle a handle object that can be used to identify this subscription
 605          *               request.  It can be used to unsubscribe from these events in the future.
 606          *               It will be set upon successful return of this method.
 607          * @param host The IP address/addressable name of the server to subscribe to.
 608          *               This should be in the format coap://address:port
 609          *               If empty, the multicast subscribe presence is performed.
 610          * @param connectivityType ::OCConnectivityType type of connectivity indicating the
 611          *                           interface. Example: CT_DEFAULT, CT_ADAPTER_IP, CT_ADAPTER_TCP.
 612          * @param presenceHandler callback function that will receive notifications/subscription
 613          *               events
 614          *
 615          * @return Returns ::OC_STACK_OK if success.
 616          */
 617         OCStackResult subscribePresence(OCPresenceHandle& presenceHandle, const std::string& host,
 618                         OCConnectivityType connectivityType, SubscribeCallback presenceHandler);
 619         /**
 620          * @overload
 621          *
 622          * subscribes to a server's presence change events.  By making this subscription,
 623          * every time a server adds/removes/alters a resource, starts or is intentionally
 624          * stopped (potentially more to be added later).
 625          *
 626          * @param presenceHandle a handle object that can be used to identify this subscription
 627          *               request.  It can be used to unsubscribe from these events in the future.
 628          *               It will be set upon successful return of this method.
 629          * @param host The IP address/addressable name of the server to subscribe to.
 630          *               This should be in the format coap://address:port
 631          *               If empty, the multicast subscribe presence is performed.
 632          * @param resourceType a resource type specified as a filter for subscription callbacks.
 633          * @param connectivityType ::OCConnectivityType type of connectivity indicating the
 634          *                           interface. Example: CT_DEFAULT, CT_ADAPTER_IP, CT_ADAPTER_TCP.
 635          * @param presenceHandler callback function that will receive notifications/subscription
 636          *               events
 637          *
 638          * @see subscribePresence(OCPresenceHandle&, const std::string&, OCConnectivityType, SubscribeCallback)
 639          */
 640         OCStackResult subscribePresence(OCPresenceHandle& presenceHandle, const std::string& host,
 641                         const std::string& resourceType, OCConnectivityType connectivityType,
 642                         SubscribeCallback presenceHandler);
 643
 644         /**
 645          * unsubscribes from a previously subscribed server's presence events. Note that
 646          * you may for a short time still receive events from the server since it may take time
 647          * for the unsubscribe to take effect.
 648          *
 649          * @param presenceHandle the handle object provided by the subscribePresence call that
 650          *               identifies this subscription.
 651          *
 652          * @return Returns ::OC_STACK_OK if success.
 653          */
 654         OCStackResult unsubscribePresence(OCPresenceHandle presenceHandle);
 655
 656 #ifdef WITH_CLOUD
 657         /**
 658          * Subscribes to a server's device presence change events.
 659          *
 660          * @param presenceHandle a handle object that can be used to identify this subscription
 661          *               request.  It can be used to unsubscribe from these events in the future.
 662          *               It will be set upon successful return of this method.
 663          * @param host The IP address/addressable name of the server to subscribe to.
 664          *               This should be in the format coap://address:port
 665          * @param di Vector which can have the devices id.
 666          * @param connectivityType ::OCConnectivityType type of connectivity indicating the
 667          *                           interface. Example: CT_DEFAULT, CT_ADAPTER_IP, CT_ADAPTER_TCP.
 668          * @param observeHandler handles callback
 669          *        The callback function will be invoked with a map of attribute name and values.
 670          *        The callback function will also have the result from this observe operation
 671          *        This will have error codes
 672          *
 673          * @return Returns ::OC_STACK_OK if success.
 674          */
 675         OCStackResult subscribeDevicePresence(OCPresenceHandle& presenceHandle,
 676                                               const std::string& host,
 677                                               const std::vector<std::string>& di,
 678                                               OCConnectivityType connectivityType,
 679                                               ObserveCallback callback);
 680 #endif
 681
 682         /**
 683          * Creates a resource proxy object so that get/put/observe functionality
 684          * can be used without discovering the object in advance.  Note that the
 685          * consumer of this method needs to provide all of the details required to
 686          * correctly contact and observe the object. If the consumer lacks any of
 687          * this information, they should discover the resource object normally.
 688          * Additionally, you can only create this object if OCPlatform was initialized
 689          * to be a Client or Client/Server.  Otherwise, this will return an empty
 690          * shared ptr.
 691          *
 692          * @param host a string containing a resolvable "coap(s)", "coap(s)+protocol" uri scheme
 693          *        of the server holding the resource.
 694          *        Currently this should be in the format coap(s)://address:port or
 695          *        coap(s)+protocol://address:port, though in the future, we expect this to
 696          *        change to //address:port
 697          *
 698          * @param uri the rest of the resource's URI that will permit messages to be
 699          *           properly routed.  Example: /a/light
 700          *
 701          * @param connectivityType ::OCConnectivityType type of connectivity indicating the
 702          *                           transport method and IP address scope.
 703          *                           Example: CT_DEFAULT, CT_ADAPTER_IP, CT_ADAPTER_TCP.
 704          *                           if you want to use a specific Flag like IPv4,
 705          *                           you should apply OR operation for the flag in here.
 706          *                           Example: static_cast<OCConnectivityType>(CT_ADAPTER_TCP
 707          *                                                                    | OC_IP_USE_V4)
 708          *
 709          * @param isObservable a boolean containing whether the resource supports observation
 710          *
 711          * @param resourceTypes a collection of resource types implemented by the resource
 712          *
 713          * @param interfaces a collection of interfaces that the resource supports/implements
 714          * @return OCResource::Ptr a shared pointer to the new resource object
 715          */
 716         OCResource::Ptr constructResourceObject(const std::string& host,
 717                         const std::string& uri,
 718                         OCConnectivityType connectivityType, bool isObservable,
 719                         const std::vector<std::string>& resourceTypes,
 720                         const std::vector<std::string>& interfaces);
 721
 722         /**
 723          * Allows application entity handler to send response to an incoming request.
 724          *
 725          * @param pResponse OCResourceResponse pointer that will permit to set values related
 726          * to resource response.
 727          *
 728          * @return Returns ::OC_STACK_OK if success.
 729          */
 730         OCStackResult sendResponse(const std::shared_ptr<OCResourceResponse> pResponse);
 731
 732 #ifdef WITH_CLOUD
 733         /**
 734          * Create an account manager object that can be used for doing request to account server.
 735          * You can only create this object if OCPlatform was initialized to be a Client or
 736          * Client/Server. Otherwise, this will return an empty shared ptr.
 737          *
 738          * @note For now, OCPlatform SHOULD be initialized to be a Client/Server(Both) for the
 739          *       methods of this object to work since device id is not generated on Client mode.
 740          *
 741          * @param host Host IP Address of a account server.
 742          * @param connectivityType ::OCConnectivityType type of connectivity indicating the
 743          *                           interface. Example: CT_DEFAULT, CT_ADAPTER_IP, CT_ADAPTER_TCP.
 744          *                           if you want to use a specific Flag like IPv4,
 745          *                           you should apply OR operation for the flag in here.
 746          *                           Example: static_cast<OCConnectivityType>(CT_ADAPTER_TCP
 747          *                                                                    | OC_IP_USE_V4)
 748          *
 749          * @return OCAccountManager::Ptr a shared pointer to the new account manager object
 750          */
 751         OCAccountManager::Ptr constructAccountManagerObject(const std::string& host,
 752                                                             OCConnectivityType connectivityType);
 753 #endif // WITH_CLOUD
 754
 755         /**
 756          * gets the deviceId of the client
 757          *
 758          * @param deviceId pointer.
 759          * @return Returns ::OC_STACK_OK if success.
 760          */
 761         OCStackResult getDeviceId(OCUUIdentity *deviceId);
 762
 763         /**
 764          * sets the deviceId of the client
 765          *
 766          * @param deviceId pointer.
 767          * @return Returns ::OC_STACK_OK if success.
 768          */
 769         OCStackResult setDeviceId(const OCUUIdentity *deviceId);
 770     }
 771 }
 772
 773 #endif // OC_PLATFORM_H_