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