resource/csdk/stack/include/ocstack.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 /**
  23  * @file
  24  *
  25  * This file contains APIs for OIC Stack to be implemented.
  26  */
  27
  28 #ifndef OCSTACK_H_
  29 #define OCSTACK_H_
  30
  31 #include <stdio.h>
  32 #include <stdint.h>
  33 #include "octypes.h"
  34
  35 #include "platform_features.h"
  36
  37 #ifdef __cplusplus
  38 extern "C" {
  39 #endif // __cplusplus
  40
  41 /** Macro to use Random port.*/
  42 #define USE_RANDOM_PORT (0)
  43
  44 /*
  45  * Function prototypes
  46  */
  47
  48 /**
  49  * This function Initializes the OC Stack.  Must be called prior to starting the stack.
  50  *
  51  * @param mode            OCMode Host device is client, server, or client-server.
  52  * @param serverFlags     OCTransportFlags Default server transport flags.
  53  * @param clientFlags     OCTransportFlags Default client transport flags.
  54  *
  55  * @return ::OC_STACK_OK on success, some other value upon failure.
  56  */
  57 OCStackResult OC_CALL OCInit1(OCMode mode, OCTransportFlags serverFlags, OCTransportFlags clientFlags);
  58
  59 /**
  60  * This function Initializes the OC Stack.  Must be called prior to starting the stack.
  61  *
  62  * @param mode            OCMode Host device is client, server, or client-server.
  63  * @param serverFlags     OCTransportFlags Default server transport flags.
  64  * @param clientFlags     OCTransportFlags Default client transport flags.
  65  * @param transportType   OCTransportAdapter value to initialize.
  66  *
  67  * @return ::OC_STACK_OK on success, some other value upon failure.
  68  */
  69 OCStackResult OC_CALL OCInit2(OCMode mode, OCTransportFlags serverFlags, OCTransportFlags clientFlags,
  70                       OCTransportAdapter transportType);
  71
  72 /**
  73  * This function Initializes the OC Stack.  Must be called prior to starting the stack.
  74  *
  75  * @param ipAddr      IP Address of host device. Deprecated parameter.
  76  * @param port        Port of host device. Deprecated parameter.
  77  * @param mode        OCMode Host device is client, server, or client-server.
  78  *
  79  * @return ::OC_STACK_OK on success, some other value upon failure.
  80  */
  81 OCStackResult OC_CALL OCInit(const char *ipAddr, uint16_t port, OCMode mode);
  82
  83 #ifdef RA_ADAPTER
  84 /**
  85  * @brief   Set Remote Access information for XMPP Client.
  86  * @param[in] raInfo  remote access info.
  87  *
  88  * @return  ::OC_STACK_OK on success, some other value upon failure.
  89  */
  90 OCStackResult OC_CALL OCSetRAInfo(const OCRAInfo_t *raInfo);
  91 #endif
  92
  93 /**
  94  * This function Stops the OC stack.  Use for a controlled shutdown.
  95  *
  96  * @note: OCStop() performs operations similar to OCStopPresence(), as well as OCDeleteResource() on
  97  * all resources this server is hosting. OCDeleteResource() performs operations similar to
  98  * OCNotifyAllObservers() to notify all client observers that the respective resource is being
  99  * deleted.
 100  *
 101  * @return ::OC_STACK_OK on success, some other value upon failure.
 102  */
 103 OCStackResult OC_CALL OCStop(void);
 104
 105 /**
 106  * This function starts responding to multicast /oic/res requests.  This can be
 107  * only called when stack is in OC_STACK_INITIALIZED state but device is not
 108  * receiving multicast traffic.
 109  *
 110  * @return ::OC_STACK_OK on success, some other value upon failure.
 111  */
 112 OCStackResult OC_CALL OCStartMulticastServer(void);
 113
 114 /**
 115  * This function stops responding to multicast /oic/res requests.  This is to be
 116  * used for devices that uses other entity to push resources.
 117  *
 118  * Note that other multicast requests, such as those used during ownership
 119  * transfer, continue to be responded to.
 120  *
 121  * @return ::OC_STACK_OK on success, some other value upon failure.
 122  */
 123 OCStackResult OC_CALL OCStopMulticastServer(void);
 124
 125 /**
 126  * This function is Called in main loop of OC client or server.
 127  * Allows low-level processing of stack services.
 128  *
 129  * @return ::OC_STACK_OK on success, some other value upon failure.
 130  */
 131 OCStackResult OC_CALL OCProcess(void);
 132
 133 /**
 134  * This function discovers or Perform requests on a specified resource
 135  * (specified by that Resource's respective URI).
 136  *
 137  * @deprecated: Use OCDoRequest instead which does not free given payload.
 138  *
 139  * @param handle            To refer to the request sent out on behalf of
 140  *                          calling this API. This handle can be used to cancel this operation
 141  *                          via the OCCancel API.
 142  *                          @note: This reference is handled internally, and should not be free'd by
 143  *                          the consumer.  A NULL handle is permitted in the event where the caller
 144  *                          has no use for the return value.
 145  * @param method            To perform on the resource.
 146  * @param requestUri        URI of the resource to interact with. (Address prefix is deprecated in
 147  *                          favor of destination.)
 148  * @param destination       Complete description of destination.
 149  * @param payload           Encoded request payload,
 150                             OCDoResource will free given payload when return OC_STATUS_OK.
 151  * @param connectivityType  Modifier flags when destination is not given.
 152  * @param qos               Quality of service. Note that if this API is called on a URI with the
 153  *                          well-known multicast IP address, the qos will be forced to ::OC_LOW_QOS
 154  *                          since it is impractical to send other QOS levels on such addresses.
 155  * @param cbData            Asynchronous callback function that is invoked by the stack when
 156  *                          discovery or resource interaction is received. The discovery could be
 157  *                          related to filtered/scoped/particular resource. The callback is
 158  *                          generated for each response received.
 159  * @param options           The address of an array containing the vendor specific header options
 160  *                          to be sent with the request.
 161  * @param numOptions        Number of header options to be included.
 162  *
 163  * @note: Presence subscription amendments (i.e. adding additional resource type filters by calling
 164  * this API again) require the use of the same base URI as the original request to successfully
 165  * amend the presence filters.
 166  *
 167  * @return ::OC_STACK_OK on success, some other value upon failure.
 168  */
 169 OCStackResult OC_CALL OCDoResource(OCDoHandle *handle,
 170                            OCMethod method,
 171                            const char *requestUri,
 172                            const OCDevAddr *destination,
 173                            OCPayload* payload,
 174                            OCConnectivityType connectivityType,
 175                            OCQualityOfService qos,
 176                            OCCallbackData *cbData,
 177                            OCHeaderOption *options,
 178                            uint8_t numOptions);
 179
 180 /**
 181  * This function discovers or Perform requests on a specified resource
 182  * (specified by that Resource's respective URI).
 183  *
 184  * @param handle            To refer to the request sent out on behalf of
 185  *                          calling this API. This handle can be used to cancel this operation
 186  *                          via the OCCancel API.
 187  *                          @note: This reference is handled internally, and should not be free'd by
 188  *                          the consumer.  A NULL handle is permitted in the event where the caller
 189  *                          has no use for the return value.
 190  * @param method            To perform on the resource.
 191  * @param requestUri        URI of the resource to interact with. (Address prefix is deprecated in
 192  *                          favor of destination.)
 193  * @param destination       Complete description of destination.
 194  * @param payload           Encoded request payload.
 195                             OCDoRequest does not free given payload.
 196  * @param connectivityType  Modifier flags when destination is not given.
 197  * @param qos               Quality of service. Note that if this API is called on a URI with the
 198  *                          well-known multicast IP address, the qos will be forced to ::OC_LOW_QOS
 199  *                          since it is impractical to send other QOS levels on such addresses.
 200  * @param cbData            Asynchronous callback function that is invoked by the stack when
 201  *                          discovery or resource interaction is received. The discovery could be
 202  *                          related to filtered/scoped/particular resource. The callback is
 203  *                          generated for each response received.
 204  * @param options           The address of an array containing the vendor specific header options
 205  *                          to be sent with the request.
 206  * @param numOptions        Number of header options to be included.
 207  *
 208  * @note: Presence subscription amendments (i.e. adding additional resource type filters by calling
 209  * this API again) require the use of the same base URI as the original request to successfully
 210  * amend the presence filters.
 211  *
 212  * @return ::OC_STACK_OK on success, some other value upon failure.
 213  */
 214 OCStackResult OC_CALL OCDoRequest(OCDoHandle *handle,
 215                           OCMethod method,
 216                           const char *requestUri,
 217                           const OCDevAddr *destination,
 218                           OCPayload* payload,
 219                           OCConnectivityType connectivityType,
 220                           OCQualityOfService qos,
 221                           OCCallbackData *cbData,
 222                           OCHeaderOption *options,
 223                           uint8_t numOptions);
 224
 225 /**
 226  * This function cancels a request associated with a specific @ref OCDoResource invocation.
 227  *
 228  * @param handle       Used to identify a specific OCDoResource invocation.
 229  * @param qos          Used to specify Quality of Service(read below).
 230  * @param options      Used to specify vendor specific header options when sending
 231  *                     explicit observe cancellation.
 232  * @param numOptions   Number of header options to be included.
 233  *
 234  * @return ::OC_STACK_OK on success, some other value upon failure.
 235  */
 236 OCStackResult OC_CALL OCCancel(OCDoHandle handle,
 237                        OCQualityOfService qos,
 238                        OCHeaderOption * options,
 239                        uint8_t numOptions);
 240
 241 /**
 242  * Register Persistent storage callback.
 243  * @param   persistentStorageHandler  Pointers to open, read, write, close & unlink handlers.
 244  *
 245  * @return
 246  *     OC_STACK_OK                    No errors; Success.
 247  *     OC_STACK_INVALID_PARAM         Invalid parameter.
 248  */
 249 OCStackResult OC_CALL OCRegisterPersistentStorageHandler(OCPersistentStorage* persistentStorageHandler);
 250
 251 #ifdef WITH_PRESENCE
 252 /**
 253  * When operating in  OCServer or  OCClientServer mode,
 254  * this API will start sending out presence notifications to clients via multicast.
 255  * Once this API has been called with a success, clients may query for this server's presence and
 256  * this server's stack will respond via multicast.
 257  *
 258  * Server can call this function when it comes online for the first time, or when it comes back
 259  * online from offline mode, or when it re enters network.
 260  *
 261  * @param ttl         Time To Live in seconds.
 262  *                    @note: If ttl is '0', then the default stack value will be used (60 Seconds).
 263  *                    If ttl is greater than ::OC_MAX_PRESENCE_TTL_SECONDS, then the ttl will be
 264  *                    set to ::OC_MAX_PRESENCE_TTL_SECONDS.
 265  *
 266  * @return ::OC_STACK_OK on success, some other value upon failure.
 267  */
 268 OCStackResult OC_CALL OCStartPresence(const uint32_t ttl);
 269
 270 /**
 271  * When operating in OCServer or OCClientServer mode, this API will stop sending
 272  * out presence notifications to clients via multicast.
 273  * Once this API has been called with a success this server's stack will not respond to clients
 274  * querying for this server's presence.
 275  *
 276  * Server can call this function when it is terminating, going offline, or when going
 277  * away from network.
 278  *
 279  * @return ::OC_STACK_OK on success, some other value upon failure.
 280  */
 281
 282 OCStackResult OC_CALL OCStopPresence(void);
 283 #endif
 284
 285
 286 /**
 287  * This function sets default device entity handler.
 288  *
 289  * @param entityHandler      Entity handler function that is called by ocstack to handle requests
 290  *                           for any undefined resources or default actions.If NULL is passed it
 291  *                           removes the device default entity handler.
 292  * @param callbackParameter  Parameter passed back when entityHandler is called.
 293  *
 294  * @return ::OC_STACK_OK on success, some other value upon failure.
 295  */
 296 OCStackResult OC_CALL OCSetDefaultDeviceEntityHandler(OCDeviceEntityHandler entityHandler,
 297                                               void* callbackParameter);
 298
 299 /**
 300  * This function sets device information.
 301  *
 302  * Upon call to OCInit, the default Device Type (i.e. "rt") has already been set to the default
 303  * Device Type "oic.wk.d". You do not have to specify "oic.wk.d" in the OCDeviceInfo.types linked
 304  * list. The default Device Type is mandatory and always specified by this Device as the first
 305  * Device Type.
 306  *
 307  * @deprecated Use OCSetPropertyValue instead.
 308  *
 309  * @param deviceInfo   Structure passed by the server application containing the device
 310  *                     information.
 311  *
 312  * @return
 313  *     ::OC_STACK_OK               no errors.
 314  *     ::OC_STACK_INVALID_PARAM    invalid parameter.
 315  *     ::OC_STACK_ERROR            stack process error.
 316  */
 317 OCStackResult OC_CALL OCSetDeviceInfo(OCDeviceInfo deviceInfo);
 318
 319 /**
 320  * This function sets platform information.
 321  *
 322  * @param platformInfo   Structure passed by the server application containing
 323  *                       the platform information.
 324  *
 325  *
 326  * @return
 327  *     ::OC_STACK_OK               no errors.
 328  *     ::OC_STACK_INVALID_PARAM    invalid parameter.
 329  *     ::OC_STACK_ERROR            stack process error.
 330  */
 331 OCStackResult OC_CALL OCSetPlatformInfo(OCPlatformInfo platformInfo);
 332
 333 /**
 334  * This function creates a resource.
 335  *
 336  * @param handle                Pointer to handle to newly created resource. Set by ocstack and
 337  *                              used to refer to resource.
 338  * @param resourceTypeName      Name of resource type.  Example: "core.led".
 339  * @param resourceInterfaceName Name of resource interface.  Example: "core.rw".
 340  * @param uri                   URI of the resource.  Example:  "/a/led".
 341  * @param entityHandler         Entity handler function that is called by ocstack to handle
 342  *                              requests, etc.
 343  *                              NULL for default entity handler.
 344  * @param callbackParam     parameter passed back when entityHandler is called.
 345  * @param resourceProperties    Properties supported by resource.
 346  *                              Example: ::OC_DISCOVERABLE|::OC_OBSERVABLE.
 347  *
 348  * @return ::OC_STACK_OK on success, some other value upon failure.
 349  */
 350 OCStackResult OC_CALL OCCreateResource(OCResourceHandle *handle,
 351                                const char *resourceTypeName,
 352                                const char *resourceInterfaceName,
 353                                const char *uri,
 354                                OCEntityHandler entityHandler,
 355                                void* callbackParam,
 356                                uint8_t resourceProperties);
 357
 358 /**
 359  * This function creates a resource.
 360  *
 361  * @param handle                Pointer to handle to newly created resource. Set by ocstack and
 362  *                              used to refer to resource.
 363  * @param resourceTypeName      Name of resource type.  Example: "core.led".
 364  * @param resourceInterfaceName Name of resource interface.  Example: "core.rw".
 365  * @param uri                   URI of the resource.  Example:  "/a/led".
 366  * @param entityHandler         Entity handler function that is called by ocstack to handle
 367  *                              requests, etc.
 368  *                              NULL for default entity handler.
 369  * @param callbackParam         parameter passed back when entityHandler is called.
 370  * @param resourceProperties    Properties supported by resource.
 371  *                              Example: ::OC_DISCOVERABLE|::OC_OBSERVABLE.
 372  * @param resourceTpsTypes      Transport Protocol Suites(TPS) types of resource for expose
 373                                 resource to specific transport adapter (e.g., TCP, UDP)
 374                                 with messaging protocol (e.g., COAP, COAPS).
 375                                 Example: "OC_COAP | OC_COAP_TCP"
 376  *
 377  * @note Only supported TPS types on stack will be mapped to resource.
 378          It means "OC_COAPS" and "OC_COAPS_TCP" flags will be ignored if secure option
 379          not enabled on stack. Also "COAP_TCP" and "COAPS_TCP" flags will be ignored
 380          if stack does not support tcp mode.
 381  *
 382  * @return ::OC_STACK_OK on success, some other value upon failure.
 383  */
 384 OCStackResult OC_CALL OCCreateResourceWithEp(OCResourceHandle *handle,
 385                                      const char *resourceTypeName,
 386                                      const char *resourceInterfaceName,
 387                                      const char *uri,
 388                                      OCEntityHandler entityHandler,
 389                                      void *callbackParam,
 390                                      uint8_t resourceProperties,
 391                                      OCTpsSchemeFlags resourceTpsTypes);
 392 /*
 393  * This function returns flags of supported endpoint TPS on stack.
 394  *
 395  * @return Bit combinations of supported OCTpsSchemeFlags.
 396  */
 397 OCTpsSchemeFlags OC_CALL OCGetSupportedEndpointTpsFlags(void);
 398
 399 /**
 400  * This function adds a resource to a collection resource.
 401  *
 402  * @param collectionHandle    Handle to the collection resource.
 403  * @param resourceHandle      Handle to resource to be added to the collection resource.
 404  *
 405  * @return ::OC_STACK_OK on success, some other value upon failure.
 406  */
 407 OCStackResult OC_CALL OCBindResource(OCResourceHandle collectionHandle, OCResourceHandle resourceHandle);
 408
 409 /**
 410  * This function removes a resource from a collection resource.
 411  *
 412  * @param collectionHandle   Handle to the collection resource.
 413  * @param resourceHandle     Handle to resource to be removed from the collection resource.
 414  *
 415  * @return ::OC_STACK_OK on success, some other value upon failure.
 416  */
 417 OCStackResult OC_CALL OCUnBindResource(OCResourceHandle collectionHandle, OCResourceHandle resourceHandle);
 418
 419 /**
 420  * This function binds a resource type to a resource.
 421  *
 422  * @param handle            Handle to the resource.
 423  * @param resourceTypeName  Name of resource type.  Example: "core.led".
 424  *
 425  * @return ::OC_STACK_OK on success, some other value upon failure.
 426  */
 427 OCStackResult OC_CALL OCBindResourceTypeToResource(OCResourceHandle handle,
 428                                            const char *resourceTypeName);
 429 /**
 430  * This function binds a resource interface to a resource.
 431  *
 432  * @param handle                  Handle to the resource.
 433  * @param resourceInterfaceName   Name of resource interface.  Example: "core.rw".
 434  *
 435  * @return ::OC_STACK_OK on success, some other value upon failure.
 436  */
 437 OCStackResult OC_CALL OCBindResourceInterfaceToResource(OCResourceHandle handle,
 438                                                 const char *resourceInterfaceName);
 439
 440 /**
 441  * This function binds an entity handler to the resource.
 442  *
 443  * @param handle            Handle to the resource that the contained resource is to be bound.
 444  * @param entityHandler     Entity handler function that is called by ocstack to handle requests.
 445  * @param callbackParameter Context parameter that will be passed to entityHandler.
 446  *
 447  * @return ::OC_STACK_OK on success, some other value upon failure.
 448  */
 449 OCStackResult OC_CALL OCBindResourceHandler(OCResourceHandle handle,
 450                                     OCEntityHandler entityHandler,
 451                                     void *callbackParameter);
 452
 453 /**
 454  * This function gets the number of resources that have been created in the stack.
 455  *
 456  * @param numResources    Pointer to count variable.
 457  *
 458  * @return ::OC_STACK_OK on success, some other value upon failure.
 459  */
 460 OCStackResult OC_CALL OCGetNumberOfResources(uint8_t *numResources);
 461
 462 /**
 463  * This function gets a resource handle by index.
 464  *
 465  * @param index   Index of resource, 0 to Count - 1.
 466  *
 467  * @return Found  resource handle or NULL if not found.
 468  */
 469 OCResourceHandle OC_CALL OCGetResourceHandle(uint8_t index);
 470
 471 /**
 472  * This function deletes resource specified by handle.  Deletes resource and all
 473  * resource type and resource interface linked lists.
 474  *
 475  * @note: OCDeleteResource() performs operations similar to OCNotifyAllObservers() to notify all
 476  * client observers that "this" resource is being deleted.
 477  *
 478  * @param handle          Handle of resource to be deleted.
 479  *
 480  * @return ::OC_STACK_OK on success, some other value upon failure.
 481  */
 482 OCStackResult OC_CALL OCDeleteResource(OCResourceHandle handle);
 483
 484 /**
 485  * Get a string representation the server instance ID.
 486  * The memory is managed internal to this function, so freeing externally will result
 487  * in a runtime error.
 488  * Note: This will NOT seed the RNG, so it must be called after the RNG is seeded.
 489  * This is done automatically during the OCInit process,
 490  * so ensure that this call is done after that.
 491  *
 492  * @return A string representation  the server instance ID.
 493  */
 494 const char* OC_CALL OCGetServerInstanceIDString(void);
 495
 496 /**
 497  * This function gets the URI of the resource specified by handle.
 498  *
 499  * @param handle     Handle of resource.
 500  *
 501  * @return URI string if resource found or NULL if not found.
 502  */
 503 const char *OC_CALL OCGetResourceUri(OCResourceHandle handle);
 504
 505 /**
 506  * This function gets the properties of the resource specified by handle.
 507  *
 508  * @param handle                Handle of resource.
 509  *
 510  * @return OCResourceProperty   Bitmask or -1 if resource is not found.
 511  *
 512  * @note that after a resource is created, the OC_ACTIVE property is set for the resource by the
 513  * stack.
 514  */
 515 OCResourceProperty OC_CALL OCGetResourceProperties(OCResourceHandle handle);
 516
 517 /**
 518  * This function sets the properties of the resource specified by handle.
 519  *
 520  * @param handle                Handle of resource.
 521  * @param resourceProperties    Properties supported by resource.
 522  *                              Example: ::OC_DISCOVERABLE|::OC_OBSERVABLE.
 523  *
 524  * @return ::OC_STACK_OK on success, some other value upon failure.
 525  */
 526 OCStackResult OC_CALL OCSetResourceProperties(OCResourceHandle handle, uint8_t resourceProperties);
 527
 528 /**
 529  * This function removes the properties of the resource specified by handle.
 530  *
 531  * @param handle                Handle of resource.
 532  * @param resourceProperties    Properties not supported by resource.
 533  *                              Example: ::OC_DISCOVERABLE|::OC_OBSERVABLE.
 534  *
 535  * @return ::OC_STACK_OK on success, some other value upon failure.
 536  */
 537 OCStackResult OC_CALL OCClearResourceProperties(OCResourceHandle handle, uint8_t resourceProperties);
 538
 539 /**
 540  * This function gets the number of resource types of the resource.
 541  *
 542  * @param handle            Handle of resource.
 543  * @param numResourceTypes  Pointer to count variable.
 544  *
 545  * @return ::OC_STACK_OK on success, some other value upon failure.
 546  */
 547 OCStackResult OC_CALL OCGetNumberOfResourceTypes(OCResourceHandle handle, uint8_t *numResourceTypes);
 548
 549 /**
 550  * This function gets name of resource type of the resource.
 551  *
 552  * @param handle       Handle of resource.
 553  * @param index        Index of resource, 0 to Count - 1.
 554  *
 555  * @return Resource type name if resource found or NULL if resource not found.
 556  */
 557 const char *OC_CALL OCGetResourceTypeName(OCResourceHandle handle, uint8_t index);
 558
 559 /**
 560  * This function gets the number of resource interfaces of the resource.
 561  *
 562  * @param handle                 Handle of resource.
 563  * @param numResourceInterfaces  Pointer to count variable.
 564  *
 565  * @return ::OC_STACK_OK on success, some other value upon failure.
 566  */
 567 OCStackResult OC_CALL OCGetNumberOfResourceInterfaces(OCResourceHandle handle,
 568         uint8_t *numResourceInterfaces);
 569
 570 /**
 571  * This function gets name of resource interface of the resource.
 572  *
 573  * @param handle      Handle of resource.
 574  * @param index       Index of resource, 0 to Count - 1.
 575  *
 576  * @return Resource interface name if resource found or NULL if resource not found.
 577  */
 578 const char *OC_CALL OCGetResourceInterfaceName(OCResourceHandle handle, uint8_t index);
 579
 580 /**
 581  * This function gets resource handle from the collection resource by index.
 582  *
 583  * @param collectionHandle   Handle of collection resource.
 584  * @param index              Index of contained resource, 0 to Count - 1.
 585  *
 586  * @return Handle to contained resource if resource found or NULL if resource not found.
 587  */
 588 OCResourceHandle OC_CALL OCGetResourceHandleFromCollection(OCResourceHandle collectionHandle,
 589         uint8_t index);
 590
 591 /**
 592  * This function gets the entity handler for a resource.
 593  *
 594  * @param handle            Handle of resource.
 595  *
 596  * @return Entity handler if resource found or NULL resource not found.
 597  */
 598 OCEntityHandler OC_CALL OCGetResourceHandler(OCResourceHandle handle);
 599
 600 /**
 601  * This function notify all registered observers that the resource representation has
 602  * changed. If observation includes a query the client is notified only if the query is valid after
 603  * the resource representation has changed.
 604  *
 605  * @param handle   Handle of resource.
 606  * @param qos      Desired quality of service for the observation notifications.
 607  *
 608  * @return ::OC_STACK_OK on success, some other value upon failure.
 609  */
 610 OCStackResult OC_CALL OCNotifyAllObservers(OCResourceHandle handle, OCQualityOfService qos);
 611
 612 /**
 613  * Notify specific observers with updated value of representation.
 614  * Before this API is invoked by entity handler it has finished processing
 615  * queries for the associated observers.
 616  *
 617  * @param handle                    Handle of resource.
 618  * @param obsIdList                 List of observation IDs that need to be notified.
 619  * @param numberOfIds               Number of observation IDs included in obsIdList.
 620  * @param payload                   Object representing the notification
 621  * @param qos                       Desired quality of service of the observation notifications.
 622  *
 623  * @note: The memory for obsIdList and payload is managed by the entity invoking the API.
 624  * The maximum size of the notification is 1015 bytes.
 625  *
 626  * @return ::OC_STACK_OK on success, some other value upon failure.
 627  */
 628 OCStackResult OC_CALL OCNotifyListOfObservers (OCResourceHandle handle,
 629                                        OCObservationId  *obsIdList,
 630                                        uint8_t          numberOfIds,
 631                                        const OCRepPayload *payload,
 632                                        OCQualityOfService qos);
 633
 634 /**
 635  * This function sends a response to a request.
 636  * The response can be a normal, slow, or block (i.e. a response that
 637  * is too large to be sent in a single PDU and must span multiple transmissions).
 638  *
 639  * @param response   Pointer to structure that contains response parameters.
 640  *
 641  * @return ::OC_STACK_OK on success, some other value upon failure.
 642  */
 643 OCStackResult OC_CALL OCDoResponse(OCEntityHandlerResponse *response);
 644
 645 /**
 646  * This function sets URI being used for proxy.
 647  *
 648  * @param uri            NULL terminated resource URI for CoAP-HTTP Proxy.
 649  */
 650 OCStackResult OC_CALL OCSetProxyURI(const char *uri);
 651
 652 #if defined(RD_CLIENT) || defined(RD_SERVER)
 653 /**
 654  * This function binds an resource unique id to the resource.
 655  *
 656  * @param handle            Handle to the resource that the contained resource is to be bound.
 657  * @param ins               Unique ID for resource.
 658  *
 659  * @return ::OC_STACK_OK on success, some other value upon failure.
 660  */
 661 OCStackResult OC_CALL OCBindResourceInsToResource(OCResourceHandle handle, int64_t ins);
 662
 663 /**
 664  * This function gets the resource unique id for a resource.
 665  *
 666  * @param handle            Handle of resource.
 667  * @param ins               Unique ID for resource.
 668  *
 669  * @return Ins if resource found or 0 resource not found.
 670  */
 671 OCStackResult OC_CALL OCGetResourceIns(OCResourceHandle handle, int64_t *ins);
 672
 673 #ifdef RD_SERVER
 674 /**
 675  * Sets the filename to be used for database persistent storage.
 676  * @param[in] filename  the filename.
 677  *
 678  * @return  ::OC_STACK_OK on success, some other value upon failure.
 679  */
 680 OCStackResult OC_CALL OCRDDatabaseSetStorageFilename(const char *filename);
 681
 682 /**
 683  * Returns the filename to be used for database persistent storage.
 684  *
 685  * @return the filename
 686  */
 687 const char *OC_CALL OCRDDatabaseGetStorageFilename();
 688
 689 /**
 690 * Search the RD database for queries.
 691 *
 692 * @param interfaceType is the interface type that is queried.
 693 * @param resourceType is the resource type that is queried.
 694 * @param discPayload NULL if no resource found or else OCDiscoveryPayload with the details
 695 * about the resources.
 696 *
 697 * @return ::OC_STACK_OK in case of success or else other value.
 698 */
 699 OCStackResult OC_CALL OCRDDatabaseDiscoveryPayloadCreate(const char *interfaceType,
 700                                                  const char *resourceType,
 701                                                  OCDiscoveryPayload **discPayload);
 702
 703 /**
 704 * Search the RD database for queries.
 705 *
 706 * @param interfaceType is the interface type that is queried.
 707 * @param resourceType is the resource type that is queried.
 708 * @param endpoint is the requesting endpoint to filter created eps value against.
 709 * @param discPayload NULL if no resource found or else OCDiscoveryPayload with the details
 710 * about the resources.
 711 *
 712 * @return ::OC_STACK_OK in case of success or else other value.
 713 */
 714 OCStackResult OC_CALL OCRDDatabaseDiscoveryPayloadCreateWithEp(const char *interfaceType,
 715                                                  const char *resourceType,
 716                                                  OCDevAddr *endpoint,
 717                                                  OCDiscoveryPayload **discPayload);
 718 #endif // RD_SERVER
 719 #endif // RD_CLIENT || RD_SERVER
 720
 721 /**
 722 * This function gets a resource handle by resource uri.
 723 *
 724 * @param uri URI of Resource to get Resource handle.
 725 *
 726 * @return Found resource handle or NULL if not found.
 727 */
 728 OCResourceHandle OC_CALL OCGetResourceHandleAtUri(const char *uri);
 729
 730 /**
 731  *  Add a header option to the given header option array.
 732  *
 733  * @param ocHdrOpt            Pointer to existing options.
 734  * @param numOptions          Number of existing options.
 735  * @param optionID            COAP option ID.
 736  * @param optionData          Option data value.
 737  * @param optionDataLength    Size of Option data value.
 738  *
 739  * @return ::OC_STACK_OK on success and other value otherwise.
 740  */
 741 OCStackResult OC_CALL OCSetHeaderOption(OCHeaderOption* ocHdrOpt,
 742                                 size_t* numOptions,
 743                                 uint16_t optionID,
 744                                 void* optionData,
 745                                 size_t optionDataLength);
 746
 747 /**
 748  *  Get data value of the option with specified option ID from given header option array.
 749  *
 750  * @param ocHdrOpt            Pointer to existing options.
 751  * @param numOptions          Number of existing options.
 752  * @param optionID            COAP option ID.
 753  * @param optionData          Pointer to option data.
 754  * @param optionDataLength    Size of option data value.
 755  * @param receivedDatalLength Pointer to the actual length of received data.
 756  *
 757  * @return ::OC_STACK_OK on success and other value otherwise.
 758  */
 759 OCStackResult OC_CALL OCGetHeaderOption(OCHeaderOption* ocHdrOpt,
 760                                 size_t numOptions,
 761                                 uint16_t optionID,
 762                                 void* optionData,
 763                                 size_t optionDataLength,
 764                                 uint16_t* receivedDatalLength);
 765
 766 /**
 767  * gets the deviceId of the client
 768  *
 769  * @param deviceId pointer.
 770  * @return Returns ::OC_STACK_OK if success.
 771  */
 772 OCStackResult OC_CALL OCGetDeviceId(OCUUIdentity *deviceId);
 773
 774 /**
 775  * sets the deviceId of the client
 776  *
 777  * @param deviceId pointer.
 778  * @return Returns ::OC_STACK_OK if success.
 779  */
 780 OCStackResult OC_CALL OCSetDeviceId(const OCUUIdentity *deviceId);
 781
 782  /**
 783  * Gets the bool state of "isOwned" property on the doxm resource.
 784  *
 785  * @param isOwned a pointer to be assigned to isOwned property
 786  * @return Returns ::OC_STACK_OK if success.
 787  */
 788 OCStackResult OC_CALL OCGetDeviceOwnedState(bool *isOwned);
 789
 790 /**
 791  * Encode an address string to match RFC 6874.
 792  *
 793  * @param outputAddress    a char array to be written with the encoded string.
 794  * @param outputSize       size of outputAddress buffer.
 795  * @param inputAddress     a char array of size <= CA_MAX_URI_LENGTH
 796  *                         containing a valid IPv6 address string.
 797  *
 798  * @return ::OC_STACK_OK on success and other value otherwise.
 799  */
 800 OCStackResult OC_CALL OCEncodeAddressForRFC6874(char* outputAddress,
 801                                         size_t outputSize,
 802                                         const char* inputAddress);
 803
 804 /**
 805  * Decode an address string according to RFC 6874.
 806  *
 807  * @param outputAddress    a char array to be written with the decoded string.
 808  * @param outputSize       size of outputAddress buffer.
 809  * @param inputAddress     a valid percent-encoded address string.
 810  * @param end              NULL if the entire entire inputAddress is a null-terminated percent-
 811  *                         encoded address string.  Otherwise, a pointer to the first byte that
 812  *                         is not part of the address string (e.g., ']' in a URI).
 813  *
 814  * @return ::OC_STACK_OK on success and other value otherwise.
 815  */
 816 OCStackResult OC_CALL OCDecodeAddressForRFC6874(char* outputAddress,
 817                                         size_t outputSize,
 818                                         const char* inputAddress,
 819                                         const char* end);
 820
 821 /**
 822  * Set the value of /oic/d and /oic/p properties. This function is a generic function that sets for
 823  * all OCF defined properties.
 824  *
 825  * For PAYLOAD_TYPE_DEVICE and OC_RSRVD_DATA_MODEL_VERSION, value must be a const char* CSV string.
 826  * For PAYLOAD_TYPE_DEVICE and OC_RSRVD_DEVICE_DESCRIPTION, or OC_RSRVD_DEVICE_MFG_NAME, value must
 827  * be an OCStringLL* with pairs of language tag and value elements.  For all other
 828  * PAYLOAD_TYPE_DEVICE properties, value must be a const char* string.
 829  *
 830  * @param type the payload type for device and platform as defined in @ref OCPayloadType.
 831  * @param propName the pre-defined property as per OCF spec.
 832  * @param value the value of the property to be set.
 833  *
 834  * @return ::OC_STACK_OK on success and other value otherwise.
 835  */
 836 OCStackResult OC_CALL OCSetPropertyValue(OCPayloadType type, const char *propName, const void *value);
 837
 838 /**
 839  * Get the value of /oic/d and /oic/p properties. This function is a generic function that gets the
 840  * value for all OCF defined properties.
 841  *
 842  * For PAYLOAD_TYPE_DEVICE and OC_RSRVD_RESOURCE_TYPE, OC_RSRVD_INTERFACE,
 843  * OC_RSRVD_DATA_MODEL_VERSION, OC_RSRVD_DEVICE_DESCRIPTION, or OC_RSRVD_DEVICE_MFG_NAME, the value
 844  * will be an OCStringLL*. For all other PAYLOAD_TYPE_DEVICE properties, value will be a char*.
 845  *
 846  * When the returned value is non-NULL, the memory must be OCFreeOCStringLL()'d or OICFree()'d by
 847  * the caller (depending on the underlying type returned).
 848  *
 849  * @param type the payload type for device and platform as defined in @ref OCPayloadType.
 850  * @param propName the pre-defined as per OCF spec.
 851  * @param value this holds the return value.  In case of error will be set to NULL.
 852  *
 853  * @return ::OC_STACK_OK on success and other value otherwise.
 854  */
 855 OCStackResult OC_CALL OCGetPropertyValue(OCPayloadType type, const char *propName, void **value);
 856
 857 /**
 858 * Get the registered persistent storage handler. All modules must use this to obtain access to
 859 * persistent storage.
 860 *
 861 * @return pointer to OCPersistentStorage structure on success and NULL otherwise.
 862 */
 863 OCPersistentStorage *OC_CALL OCGetPersistentStorageHandler(void);
 864
 865 /**
 866 * This function return link local zone id related from ifindex.
 867 *
 868 * @param[in] ifindex     interface index.
 869 * @param[out] zoneId     pointer of zoneId string, caller should free
 870 *                        zoneId using OICFree() when it returned CA_STATUS_OK.
 871 * @return ::OC_STACK_OK if successful.
 872 */
 873 OCStackResult OC_CALL OCGetLinkLocalZoneId(uint32_t ifindex, char **zoneId);
 874
 875 /**
 876  * Select the cipher suite for dtls handshake.
 877  *
 878  * @param[in] cipher      cipher suite (Note : Make sure endianness).
 879  *                          TLS_RSA_WITH_AES_256_CBC_SHA256          0x3D
 880  *                          TLS_RSA_WITH_AES_128_GCM_SHA256          0x009C
 881  *                          TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256  0xC02B
 882  *                          TLS_ECDHE_ECDSA_WITH_AES_128_CCM_8       0xC0AE
 883  *                          TLS_ECDHE_ECDSA_WITH_AES_128_CCM         0xC0AC
 884  *                          TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256  0xC023
 885  *                          TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384  0xC024
 886  *                          TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384  0xC02C
 887  *                          TLS_ECDHE_PSK_WITH_AES_128_CBC_SHA256    0xC037
 888  *                          TLS_ECDH_anon_WITH_AES_128_CBC_SHA       0xC018
 889  * @param[in] adapterType transport adapter (TCP/IP/BLE)
 890  *
 891  * @return ::OC_STACK_OK if successful.
 892  */
 893 OCStackResult OC_CALL OCSelectCipherSuite(uint16_t cipher, OCTransportAdapter adapterType);
 894
 895 /**
 896  * Return the scope level of a given IP address.
 897  *
 898  * @param[in] addr          remote IP address.
 899  * @param[out] scope        scope level of given IP address.
 900  *
 901  * @return ::OC_STACK_OK if successful.
 902  */
 903 OCStackResult OC_CALL OCGetIpv6AddrScope(const char *addr, OCTransportFlags *scope);
 904
 905 /**
 906 * Return the Content Format from Entity Handler Request.
 907 *
 908 * @param[in] ehRequest          client request on entity handler
 909 * @param[out] pContentFormat    media content format enum OCPayloadFormat
 910 * @param[out] pAcceptVersion    accept version (e.g: 2048 for "1.0.0", NULL input is accepted)
 911 *
 912 * @return ::OC_STACK_OK if successful.
 913 */
 914 OCStackResult OC_CALL OCGetRequestPayloadVersion(OCEntityHandlerRequest *ehRequest,
 915                                   OCPayloadFormat* pContentFormat, uint16_t* pAcceptVersion);
 916
 917 #ifdef __cplusplus
 918 }
 919 #endif // __cplusplus
 920
 921 #endif /* OCSTACK_H_ */