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