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