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, void* callbackParameter);
 294
 295 /**
 296  * This function sets device information.
 297  *
 298  * Upon call to OCInit, the default Device Type (i.e. "rt") has already been set to the default
 299  * Device Type "oic.wk.d". You do not have to specify "oic.wk.d" in the OCDeviceInfo.types linked
 300  * list. The default Device Type is mandatory and always specified by this Device as the first
 301  * Device Type.
 302  *
 303  * @deprecated Use OCSetPropertyValue instead.
 304  *
 305  * @param deviceInfo   Structure passed by the server application containing the device
 306  *                     information.
 307  *
 308  * @return
 309  *     ::OC_STACK_OK               no errors.
 310  *     ::OC_STACK_INVALID_PARAM    invalid parameter.
 311  *     ::OC_STACK_ERROR            stack process error.
 312  */
 313 OCStackResult OCSetDeviceInfo(OCDeviceInfo deviceInfo);
 314
 315 /**
 316  * This function sets platform information.
 317  *
 318  * @param platformInfo   Structure passed by the server application containing
 319  *                       the platform information.
 320  *
 321  *
 322  * @return
 323  *     ::OC_STACK_OK               no errors.
 324  *     ::OC_STACK_INVALID_PARAM    invalid parameter.
 325  *     ::OC_STACK_ERROR            stack process error.
 326  */
 327 OCStackResult OCSetPlatformInfo(OCPlatformInfo platformInfo);
 328
 329 /**
 330  * This function creates a resource.
 331  *
 332  * @param handle                Pointer to handle to newly created resource. Set by ocstack and
 333  *                              used to refer to resource.
 334  * @param resourceTypeName      Name of resource type.  Example: "core.led".
 335  * @param resourceInterfaceName Name of resource interface.  Example: "core.rw".
 336  * @param uri                   URI of the resource.  Example:  "/a/led".
 337  * @param entityHandler         Entity handler function that is called by ocstack to handle
 338  *                              requests, etc.
 339  *                              NULL for default entity handler.
 340  * @param callbackParam     parameter passed back when entityHandler is called.
 341  * @param resourceProperties    Properties supported by resource.
 342  *                              Example: ::OC_DISCOVERABLE|::OC_OBSERVABLE.
 343  *
 344  * @return ::OC_STACK_OK on success, some other value upon failure.
 345  */
 346 OCStackResult OCCreateResource(OCResourceHandle *handle,
 347                                const char *resourceTypeName,
 348                                const char *resourceInterfaceName,
 349                                const char *uri,
 350                                OCEntityHandler entityHandler,
 351                                void* callbackParam,
 352                                uint8_t resourceProperties);
 353
 354 /**
 355  * This function creates a resource.
 356  *
 357  * @param handle                Pointer to handle to newly created resource. Set by ocstack and
 358  *                              used to refer to resource.
 359  * @param resourceTypeName      Name of resource type.  Example: "core.led".
 360  * @param resourceInterfaceName Name of resource interface.  Example: "core.rw".
 361  * @param uri                   URI of the resource.  Example:  "/a/led".
 362  * @param entityHandler         Entity handler function that is called by ocstack to handle
 363  *                              requests, etc.
 364  *                              NULL for default entity handler.
 365  * @param callbackParam         parameter passed back when entityHandler is called.
 366  * @param resourceProperties    Properties supported by resource.
 367  *                              Example: ::OC_DISCOVERABLE|::OC_OBSERVABLE.
 368  * @param resourceTpsTypes      Transport Protocol Suites(TPS) types of resource for expose
 369                                 resource to specific transport adapter (e.g., TCP, UDP)
 370                                 with messaging protocol (e.g., COAP, COAPS).
 371                                 Example: "OC_COAP | OC_COAP_TCP"
 372  *
 373  * @note Only supported TPS types on stack will be mapped to resource.
 374          It means "OC_COAPS" and "OC_COAPS_TCP" flags will be ignored if secure option
 375          not enabled on stack. Also "COAP_TCP" and "COAPS_TCP" flags will be ignored
 376          if stack does not support tcp mode.
 377  *
 378  * @return ::OC_STACK_OK on success, some other value upon failure.
 379  */
 380 OCStackResult OCCreateResourceWithEp(OCResourceHandle *handle,
 381                                      const char *resourceTypeName,
 382                                      const char *resourceInterfaceName,
 383                                      const char *uri,
 384                                      OCEntityHandler entityHandler,
 385                                      void *callbackParam,
 386                                      uint8_t resourceProperties,
 387                                      OCTpsSchemeFlags resourceTpsTypes);
 388 /*
 389  * This function returns flags of supported endpoint TPS on stack.
 390  *
 391  * @return Bit combinations of supported OCTpsSchemeFlags.
 392  */
 393 OCTpsSchemeFlags OCGetSupportedEndpointTpsFlags();
 394
 395 /**
 396  * This function adds a resource to a collection resource.
 397  *
 398  * @param collectionHandle    Handle to the collection resource.
 399  * @param resourceHandle      Handle to resource to be added to the collection resource.
 400  *
 401  * @return ::OC_STACK_OK on success, some other value upon failure.
 402  */
 403 OCStackResult OCBindResource(OCResourceHandle collectionHandle, OCResourceHandle resourceHandle);
 404
 405 /**
 406  * This function removes a resource from a collection resource.
 407  *
 408  * @param collectionHandle   Handle to the collection resource.
 409  * @param resourceHandle     Handle to resource to be removed from the collection resource.
 410  *
 411  * @return ::OC_STACK_OK on success, some other value upon failure.
 412  */
 413 OCStackResult OCUnBindResource(OCResourceHandle collectionHandle, OCResourceHandle resourceHandle);
 414
 415 /**
 416  * This function binds a resource type to a resource.
 417  *
 418  * @param handle            Handle to the resource.
 419  * @param resourceTypeName  Name of resource type.  Example: "core.led".
 420  *
 421  * @return ::OC_STACK_OK on success, some other value upon failure.
 422  */
 423 OCStackResult OCBindResourceTypeToResource(OCResourceHandle handle,
 424                                            const char *resourceTypeName);
 425 /**
 426  * This function binds a resource interface to a resource.
 427  *
 428  * @param handle                  Handle to the resource.
 429  * @param resourceInterfaceName   Name of resource interface.  Example: "core.rw".
 430  *
 431  * @return ::OC_STACK_OK on success, some other value upon failure.
 432  */
 433 OCStackResult OCBindResourceInterfaceToResource(OCResourceHandle handle,
 434                                                 const char *resourceInterfaceName);
 435
 436 /**
 437  * This function binds an entity handler to the resource.
 438  *
 439  * @param handle            Handle to the resource that the contained resource is to be bound.
 440  * @param entityHandler     Entity handler function that is called by ocstack to handle requests.
 441  * @param callbackParameter Context parameter that will be passed to entityHandler.
 442  *
 443  * @return ::OC_STACK_OK on success, some other value upon failure.
 444  */
 445 OCStackResult OCBindResourceHandler(OCResourceHandle handle,
 446                                     OCEntityHandler entityHandler,
 447                                     void *callbackParameter);
 448
 449 /**
 450  * This function gets the number of resources that have been created in the stack.
 451  *
 452  * @param numResources    Pointer to count variable.
 453  *
 454  * @return ::OC_STACK_OK on success, some other value upon failure.
 455  */
 456 OCStackResult OCGetNumberOfResources(uint8_t *numResources);
 457
 458 /**
 459  * This function gets a resource handle by index.
 460  *
 461  * @param index   Index of resource, 0 to Count - 1.
 462  *
 463  * @return Found  resource handle or NULL if not found.
 464  */
 465 OCResourceHandle OCGetResourceHandle(uint8_t index);
 466
 467 /**
 468  * This function deletes resource specified by handle.  Deletes resource and all
 469  * resource type and resource interface linked lists.
 470  *
 471  * @note: OCDeleteResource() performs operations similar to OCNotifyAllObservers() to notify all
 472  * client observers that "this" resource is being deleted.
 473  *
 474  * @param handle          Handle of resource to be deleted.
 475  *
 476  * @return ::OC_STACK_OK on success, some other value upon failure.
 477  */
 478 OCStackResult OCDeleteResource(OCResourceHandle handle);
 479
 480 /**
 481  * Get a string representation the server instance ID.
 482  * The memory is managed internal to this function, so freeing externally will result
 483  * in a runtime error.
 484  * Note: This will NOT seed the RNG, so it must be called after the RNG is seeded.
 485  * This is done automatically during the OCInit process,
 486  * so ensure that this call is done after that.
 487  *
 488  * @return A string representation  the server instance ID.
 489  */
 490 const char* OCGetServerInstanceIDString(void);
 491
 492 /**
 493  * This function gets the URI of the resource specified by handle.
 494  *
 495  * @param handle     Handle of resource.
 496  *
 497  * @return URI string if resource found or NULL if not found.
 498  */
 499 const char *OCGetResourceUri(OCResourceHandle handle);
 500
 501 /**
 502  * This function gets the properties of the resource specified by handle.
 503  *
 504  * @param handle                Handle of resource.
 505  *
 506  * @return OCResourceProperty   Bitmask or -1 if resource is not found.
 507  *
 508  * @note that after a resource is created, the OC_ACTIVE property is set for the resource by the
 509  * stack.
 510  */
 511 OCResourceProperty OCGetResourceProperties(OCResourceHandle handle);
 512
 513 /**
 514  * This function sets the properties of the resource specified by handle.
 515  *
 516  * @param handle                Handle of resource.
 517  * @param resourceProperties    Properties supported by resource.
 518  *                              Example: ::OC_DISCOVERABLE|::OC_OBSERVABLE.
 519  *
 520  * @return ::OC_STACK_OK on success, some other value upon failure.
 521  */
 522 OCStackResult OCSetResourceProperties(OCResourceHandle handle, uint8_t resourceProperties);
 523
 524 /**
 525  * This function removes the properties of the resource specified by handle.
 526  *
 527  * @param handle                Handle of resource.
 528  * @param resourceProperties    Properties not supported by resource.
 529  *                              Example: ::OC_DISCOVERABLE|::OC_OBSERVABLE.
 530  *
 531  * @return ::OC_STACK_OK on success, some other value upon failure.
 532  */
 533 OCStackResult OCClearResourceProperties(OCResourceHandle handle, uint8_t resourceProperties);
 534
 535 /**
 536  * This function gets the number of resource types of the resource.
 537  *
 538  * @param handle            Handle of resource.
 539  * @param numResourceTypes  Pointer to count variable.
 540  *
 541  * @return ::OC_STACK_OK on success, some other value upon failure.
 542  */
 543 OCStackResult OCGetNumberOfResourceTypes(OCResourceHandle handle, uint8_t *numResourceTypes);
 544
 545 /**
 546  * This function gets name of resource type of the resource.
 547  *
 548  * @param handle       Handle of resource.
 549  * @param index        Index of resource, 0 to Count - 1.
 550  *
 551  * @return Resource type name if resource found or NULL if resource not found.
 552  */
 553 const char *OCGetResourceTypeName(OCResourceHandle handle, uint8_t index);
 554
 555 /**
 556  * This function gets the number of resource interfaces of the resource.
 557  *
 558  * @param handle                 Handle of resource.
 559  * @param numResourceInterfaces  Pointer to count variable.
 560  *
 561  * @return ::OC_STACK_OK on success, some other value upon failure.
 562  */
 563 OCStackResult OCGetNumberOfResourceInterfaces(OCResourceHandle handle,
 564         uint8_t *numResourceInterfaces);
 565
 566 /**
 567  * This function gets name of resource interface of the resource.
 568  *
 569  * @param handle      Handle of resource.
 570  * @param index       Index of resource, 0 to Count - 1.
 571  *
 572  * @return Resource interface name if resource found or NULL if resource not found.
 573  */
 574 const char *OCGetResourceInterfaceName(OCResourceHandle handle, uint8_t index);
 575
 576 /**
 577  * This function gets methods of resource interface of the resource.
 578  *
 579  * @param handle      Handle of resource.
 580  * @param index       Index of resource, 0 to Count - 1.
 581  *
 582  * @return Allowed methods if resource found or NULL if resource not found.
 583  */
 584 uint8_t OCGetResourceInterfaceAllowedMethods(OCResourceHandle handle, uint8_t index);
 585
 586 /**
 587  * This function gets resource handle from the collection resource by index.
 588  *
 589  * @param collectionHandle   Handle of collection resource.
 590  * @param index              Index of contained resource, 0 to Count - 1.
 591  *
 592  * @return Handle to contained resource if resource found or NULL if resource not found.
 593  */
 594 OCResourceHandle OCGetResourceHandleFromCollection(OCResourceHandle collectionHandle,
 595         uint8_t index);
 596
 597 /**
 598  * This function gets the entity handler for a resource.
 599  *
 600  * @param handle            Handle of resource.
 601  *
 602  * @return Entity handler if resource found or NULL resource not found.
 603  */
 604 OCEntityHandler OCGetResourceHandler(OCResourceHandle handle);
 605
 606 /**
 607  * This function notify all registered observers that the resource representation has
 608  * changed. If observation includes a query the client is notified only if the query is valid after
 609  * the resource representation has changed.
 610  *
 611  * @param handle   Handle of resource.
 612  * @param qos      Desired quality of service for the observation notifications.
 613  *
 614  * @return ::OC_STACK_OK on success, some other value upon failure.
 615  */
 616 OCStackResult OCNotifyAllObservers(OCResourceHandle handle, OCQualityOfService qos);
 617
 618 /**
 619  * Notify specific observers with updated value of representation.
 620  * Before this API is invoked by entity handler it has finished processing
 621  * queries for the associated observers.
 622  *
 623  * @param handle                    Handle of resource.
 624  * @param obsIdList                 List of observation IDs that need to be notified.
 625  * @param numberOfIds               Number of observation IDs included in obsIdList.
 626  * @param payload                   Object representing the notification
 627  * @param qos                       Desired quality of service of the observation notifications.
 628  *
 629  * @note: The memory for obsIdList and payload is managed by the entity invoking the API.
 630  * The maximum size of the notification is 1015 bytes for non-Arduino platforms. For Arduino
 631  * the maximum size is 247 bytes.
 632  *
 633  * @return ::OC_STACK_OK on success, some other value upon failure.
 634  */
 635 OCStackResult
 636 OCNotifyListOfObservers (OCResourceHandle handle,
 637                          OCObservationId  *obsIdList,
 638                          uint8_t          numberOfIds,
 639                          const OCRepPayload *payload,
 640                          OCQualityOfService qos);
 641
 642
 643 /**
 644  * This function sends a response to a request.
 645  * The response can be a normal, slow, or block (i.e. a response that
 646  * is too large to be sent in a single PDU and must span multiple transmissions).
 647  *
 648  * @param response   Pointer to structure that contains response parameters.
 649  *
 650  * @return ::OC_STACK_OK on success, some other value upon failure.
 651  */
 652 OCStackResult OCDoResponse(OCEntityHandlerResponse *response);
 653
 654 //#ifdef DIRECT_PAIRING
 655 /**
 656  * The function is responsible for discovery of direct-pairing device is current subnet. It will list
 657  * all the device in subnet which support direct-pairing.
 658  * Caller must NOT free returned constant pointer
 659  *
 660  * @param[in] timeout Timeout in seconds, value till which function will listen to responses from
 661  *                    client before returning the list of devices.
 662  * @return OCDirectPairingDev_t pointer in case of success and NULL otherwise.
 663  */
 664 const OCDPDev_t* OCDiscoverDirectPairingDevices(unsigned short waittime);
 665
 666 /**
 667  * The function is responsible for return of paired device list via direct-pairing. It will list
 668  * all the device which is previousely paired with client.
 669  * Caller must NOT free returned constant pointer
 670  *
 671  * @return OCDirectPairingDev_t pointer in case of success and NULL otherwise.
 672  */
 673 const OCDPDev_t* OCGetDirectPairedDevices();
 674
 675 /**
 676  * The function is responsible for establishment of direct-pairing. It will proceed mode negotiation
 677  * and connect PIN based dtls session.
 678  *
 679  * @param[in] peer Target device to establish direct-pairing.
 680  * @param[in] pmSel Selected mode of pairing.
 681  * @param[in] pinNumber PIN number for authentication, pin lenght is defined DP_PIN_LENGTH(8).
 682  * @param[in] resultCallback Callback fucntion to event status of process.
 683  * @return OTM_SUCCESS in case of success and other value otherwise.
 684  */
 685 OCStackResult OCDoDirectPairing(void *ctx, OCDPDev_t* peer, OCPrm_t pmSel, char *pinNumber,
 686                                 OCDirectPairingCB resultCallback);
 687
 688 /**
 689  * This function sets uri being used for proxy.
 690  *
 691  * @param uri            NULL terminated resource uri for CoAP-HTTP Proxy.
 692  */
 693 OCStackResult OCSetProxyURI(const char *uri);
 694
 695 #if defined(RD_CLIENT) || defined(RD_SERVER)
 696 /**
 697  * This function binds an resource unique id to the resource.
 698  *
 699  * @param handle            Handle to the resource that the contained resource is to be bound.
 700  * @param ins               Unique ID for resource.
 701  *
 702  * @return ::OC_STACK_OK on success, some other value upon failure.
 703  */
 704 OCStackResult OCBindResourceInsToResource(OCResourceHandle handle, uint8_t ins);
 705
 706 /**
 707  * This function gets the resource unique id for a resource.
 708  *
 709  * @param handle            Handle of resource.
 710  * @param ins               Unique ID for resource.
 711  *
 712  * @return Ins if resource found or 0 resource not found.
 713  */
 714 OCStackResult OCGetResourceIns(OCResourceHandle handle, uint8_t *ins);
 715
 716 #endif
 717
 718 /**
 719 * This function gets a resource handle by resource uri.
 720 *
 721 * @param uri   Uri of Resource to get Resource handle.
 722 *
 723 * @return Found  resource handle or NULL if not found.
 724 */
 725 OCResourceHandle OCGetResourceHandleAtUri(const char *uri);
 726
 727 #ifdef RD_SERVER
 728 /**
 729 * Search the RD database for queries.
 730 *
 731 * @param interfaceType is the interface type that is queried.
 732 * @param resourceType is the resource type that is queried.
 733 * @param discPayload NULL if no resource found or else OCDiscoveryPayload with the details
 734 * about the resources.
 735 *
 736 * @return ::OC_STACK_OK in case of success or else other value.
 737 */
 738 OCStackResult OCRDDatabaseDiscoveryPayloadCreate(const char *interfaceType, const char *resourceType,
 739     OCDiscoveryPayload **discPayload);
 740 #endif
 741 //#endif // DIRECT_PAIRING
 742
 743 /**
 744  *  Add a header option to the given header option array.
 745  *
 746  * @param ocHdrOpt            Pointer to existing options.
 747  * @param numOptions          Number of existing options.
 748  * @param optionID            COAP option ID.
 749  * @param optionData          Option data value.
 750  * @param optionDataLength    Size of Option data value.
 751  *
 752  * @return ::OC_STACK_OK on success and other value otherwise.
 753  */
 754 OCStackResult
 755 OCSetHeaderOption(OCHeaderOption* ocHdrOpt,
 756                   size_t* numOptions,
 757                   uint16_t optionID,
 758                   void* optionData,
 759                   size_t optionDataLength);
 760
 761 /**
 762  *  Get data value of the option with specified option ID from given header option array.
 763  *
 764  * @param ocHdrOpt            Pointer to existing options.
 765  * @param numOptions          Number of existing options.
 766  * @param optionID            COAP option ID.
 767  * @param optionData          Pointer to option data.
 768  * @param optionDataLength    Size of option data value.
 769  * @param receivedDatalLength Pointer to the actual length of received data.
 770  *
 771  * @return ::OC_STACK_OK on success and other value otherwise.
 772  */
 773 OCStackResult
 774 OCGetHeaderOption(OCHeaderOption* ocHdrOpt,
 775                   size_t numOptions,
 776                   uint16_t optionID,
 777                   void* optionData,
 778                   size_t optionDataLength,
 779                   uint16_t* receivedDatalLength);
 780
 781 /**
 782  * gets the deviceId of the client
 783  *
 784  * @param deviceId pointer.
 785  * @return Returns ::OC_STACK_OK if success.
 786  */
 787 OCStackResult OCGetDeviceId(OCUUIdentity *deviceId);
 788
 789 /**
 790  * sets the deviceId of the client
 791  *
 792  * @param deviceId pointer.
 793  * @return Returns ::OC_STACK_OK if success.
 794  */
 795 OCStackResult OCSetDeviceId(const OCUUIdentity *deviceId);
 796
 797  /**
 798  * Gets the bool state of "isOwned" property on the doxm resource.
 799  *
 800  * @param isOwned a pointer to be assigned to isOwned property
 801  * @return Returns ::OC_STACK_OK if success.
 802  */
 803 OCStackResult OCGetDeviceOwnedState(bool *isOwned);
 804
 805 /**
 806  * Encode an address string to match RFC 6874.
 807  *
 808  * @param outputAddress    a char array to be written with the encoded string.
 809  *
 810  * @param outputSize       size of outputAddress buffer.
 811  *
 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  *
 826  * @param outputSize       size of outputAddress buffer.
 827  *
 828  * @param inputAddress     a valid percent-encoded address string.
 829  *
 830  * @param end              NULL if the entire entire inputAddress is a null-terminated percent-
 831  *                         encoded address string.  Otherwise, a pointer to the first byte that
 832  *                         is not part of the address string (e.g., ']' in a URI).
 833  *
 834  * @return ::OC_STACK_OK on success and other value otherwise.
 835  */
 836 OCStackResult OCDecodeAddressForRFC6874(char* outputAddress,
 837                                         size_t outputSize,
 838                                         const char* inputAddress,
 839                                         const char* end);
 840
 841 /**
 842  * Set the value of /oic/d and /oic/p properties. This function is a generic function that sets for
 843  * all OCF defined properties.
 844  *
 845  * @param type the payload type for device and platform as defined in @ref OCPayloadType.
 846  * @param propName the pre-defined property as per OCF spec.
 847  * @param value the value of the property to be set.
 848  *
 849  * @return ::OC_STACK_OK on success and other value otherwise.
 850  */
 851 OCStackResult OCSetPropertyValue(OCPayloadType type, const char *propName, const void *value);
 852
 853 /**
 854  * Get the value of /oic/d and /oic/p properties. This function is a generic function that get value
 855  * for all OCF defined properties.
 856  *
 857  * @param type the payload type for device and platform as defined in @ref OCPayloadType.
 858  * @param propName the pre-defined as per OCF spec.
 859  * @param value this holds the return value.  In case of error will be set to NULL.
 860  *
 861  * @return ::OC_STACK_OK on success and other value otherwise.
 862  */
 863 OCStackResult OCGetPropertyValue(OCPayloadType type, const char *propName, void **value);
 864
 865 /**
 866 * Get the registered persistent storage handler. All modules must use this to obtain access to
 867 * persistent storage.
 868 *
 869 * @return pointer to OCPersistentStorage structure on success and NULL otherwise.
 870 */
 871 OCPersistentStorage *OCGetPersistentStorageHandler();
 872
 873 #ifdef __cplusplus
 874 }
 875 #endif // __cplusplus
 876
 877 #endif /* OCSTACK_H_ */