resource/include/OCPlatform.h

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