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