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