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.
 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 /**
 249  * When operating in  OCServer or  OCClientServer mode,
 250  * this API will start sending out presence notifications to clients via multicast.
 251  * Once this API has been called with a success, clients may query for this server's presence and
 252  * this server's stack will respond via multicast.
 253  *
 254  * Server can call this function when it comes online for the first time, or when it comes back
 255  * online from offline mode, or when it re enters network.
 256  *
 257  * @param ttl         Time To Live in seconds.
 258  *                    @note: If ttl is '0', then the default stack value will be used (60 Seconds).
 259  *                    If ttl is greater than ::OC_MAX_PRESENCE_TTL_SECONDS, then the ttl will be
 260  *                    set to ::OC_MAX_PRESENCE_TTL_SECONDS.
 261  *
 262  * @return ::OC_STACK_OK on success, some other value upon failure.
 263  */
 264 OCStackResult OCStartPresence(const uint32_t ttl);
 265
 266 /**
 267  * When operating in OCServer or OCClientServer mode, this API will stop sending
 268  * out presence notifications to clients via multicast.
 269  * Once this API has been called with a success this server's stack will not respond to clients
 270  * querying for this server's presence.
 271  *
 272  * Server can call this function when it is terminating, going offline, or when going
 273  * away from network.
 274  *
 275  * @return ::OC_STACK_OK on success, some other value upon failure.
 276  */
 277
 278 OCStackResult OCStopPresence();
 279
 280 /**
 281  * This function sets default device entity handler.
 282  *
 283  * @param entityHandler      Entity handler function that is called by ocstack to handle requests
 284  *                           for any undefined resources or default actions.If NULL is passed it
 285  *                           removes the device default entity handler.
 286  * @param callbackParameter  Parameter passed back when entityHandler is called.
 287  *
 288  * @return ::OC_STACK_OK on success, some other value upon failure.
 289  */
 290 OCStackResult OCSetDefaultDeviceEntityHandler(OCDeviceEntityHandler entityHandler, void* callbackParameter);
 291
 292 /**
 293  * This function sets device information.
 294  *
 295  * Upon call to OCInit, the default Device Type (i.e. "rt") has already been set to the default
 296  * Device Type "oic.wk.d". You do not have to specify "oic.wk.d" in the OCDeviceInfo.types linked
 297  * list. The default Device Type is mandatory and always specified by this Device as the first
 298  * Device Type.
 299  *
 300  * @param deviceInfo   Structure passed by the server application containing the device
 301  *                     information.
 302  *
 303  * @return
 304  *     ::OC_STACK_OK               no errors.
 305  *     ::OC_STACK_INVALID_PARAM    invalid parameter.
 306  *     ::OC_STACK_ERROR            stack process error.
 307  */
 308 OCStackResult OCSetDeviceInfo(OCDeviceInfo deviceInfo);
 309
 310 /**
 311  * This function sets platform information.
 312  *
 313  * @param platformInfo   Structure passed by the server application containing
 314  *                       the platform information.
 315  *
 316  *
 317  * @return
 318  *     ::OC_STACK_OK               no errors.
 319  *     ::OC_STACK_INVALID_PARAM    invalid parameter.
 320  *     ::OC_STACK_ERROR            stack process error.
 321  */
 322 OCStackResult OCSetPlatformInfo(OCPlatformInfo platformInfo);
 323
 324 /**
 325  * This function creates a resource.
 326  *
 327  * @param handle                Pointer to handle to newly created resource. Set by ocstack and
 328  *                              used to refer to resource.
 329  * @param resourceTypeName      Name of resource type.  Example: "core.led".
 330  * @param resourceInterfaceName Name of resource interface.  Example: "core.rw".
 331  * @param uri                   URI of the resource.  Example:  "/a/led".
 332  * @param entityHandler         Entity handler function that is called by ocstack to handle
 333  *                              requests, etc.
 334  *                              NULL for default entity handler.
 335  * @param callbackParam     parameter passed back when entityHandler is called.
 336  * @param resourceProperties    Properties supported by resource.
 337  *                              Example: ::OC_DISCOVERABLE|::OC_OBSERVABLE.
 338  *
 339  * @return ::OC_STACK_OK on success, some other value upon failure.
 340  */
 341 OCStackResult OCCreateResource(OCResourceHandle *handle,
 342                                const char *resourceTypeName,
 343                                const char *resourceInterfaceName,
 344                                const char *uri,
 345                                OCEntityHandler entityHandler,
 346                                void* callbackParam,
 347                                uint8_t resourceProperties);
 348
 349 /**
 350  * This function adds a resource to a collection resource.
 351  *
 352  * @param collectionHandle    Handle to the collection resource.
 353  * @param resourceHandle      Handle to resource to be added to the collection resource.
 354  *
 355  * @return ::OC_STACK_OK on success, some other value upon failure.
 356  */
 357 OCStackResult OCBindResource(OCResourceHandle collectionHandle, OCResourceHandle resourceHandle);
 358
 359 /**
 360  * This function removes a resource from a collection resource.
 361  *
 362  * @param collectionHandle   Handle to the collection resource.
 363  * @param resourceHandle     Handle to resource to be removed from the collection resource.
 364  *
 365  * @return ::OC_STACK_OK on success, some other value upon failure.
 366  */
 367 OCStackResult OCUnBindResource(OCResourceHandle collectionHandle, OCResourceHandle resourceHandle);
 368
 369 /**
 370  * This function binds a resource type to a resource.
 371  *
 372  * @param handle            Handle to the resource.
 373  * @param resourceTypeName  Name of resource type.  Example: "core.led".
 374  *
 375  * @return ::OC_STACK_OK on success, some other value upon failure.
 376  */
 377 OCStackResult OCBindResourceTypeToResource(OCResourceHandle handle,
 378                                            const char *resourceTypeName);
 379
 380 /**
 381  * This function clears all bound resource types and bind newly passing
 382  * resource type to resource.
 383  *
 384  * @param handle            Handle to the resource.
 385  * @param newResourceType   Name of resource type.  Example: "core.led".
 386  *
 387  * @return ::OC_STACK_OK on success, some other value upon failure.
 388  */
 389 OCStackResult OCResetResourceTypes(OCResourceHandle handle,
 390                                    const char *newResourceType);
 391
 392 /**
 393  * This function binds a resource interface to a resource.
 394  *
 395  * @param handle                  Handle to the resource.
 396  * @param resourceInterfaceName   Name of resource interface.  Example: "core.rw".
 397  *
 398  * @return ::OC_STACK_OK on success, some other value upon failure.
 399  */
 400 OCStackResult OCBindResourceInterfaceToResource(OCResourceHandle handle,
 401                                                 const char *resourceInterfaceName);
 402
 403 /**
 404  * This function clears all bound interfaces and bind newly passing
 405  * interface to resource.
 406  *
 407  * @param handle                  Handle to the resource.
 408  * @param newResourceInterface    Name of resource interface.  Example: "core.rw".
 409  *
 410  * @return ::OC_STACK_OK on success, some other value upon failure.
 411  */
 412 OCStackResult OCResetResourceInterfaces(OCResourceHandle handle,
 413                                         const char *newResourceInterface);
 414
 415 /**
 416  * This function binds an entity handler to the resource.
 417  *
 418  * @param handle            Handle to the resource that the contained resource is to be bound.
 419  * @param entityHandler     Entity handler function that is called by ocstack to handle requests.
 420  * @param callbackParameter Context parameter that will be passed to entityHandler.
 421  *
 422  * @return ::OC_STACK_OK on success, some other value upon failure.
 423  */
 424 OCStackResult OCBindResourceHandler(OCResourceHandle handle,
 425                                     OCEntityHandler entityHandler,
 426                                     void *callbackParameter);
 427
 428 /**
 429  * This function gets the number of resources that have been created in the stack.
 430  *
 431  * @param numResources    Pointer to count variable.
 432  *
 433  * @return ::OC_STACK_OK on success, some other value upon failure.
 434  */
 435 OCStackResult OCGetNumberOfResources(uint8_t *numResources);
 436
 437 /**
 438  * This function gets a resource handle by index.
 439  *
 440  * @param index   Index of resource, 0 to Count - 1.
 441  *
 442  * @return Found  resource handle or NULL if not found.
 443  */
 444 OCResourceHandle OCGetResourceHandle(uint8_t index);
 445
 446 /**
 447  * This function deletes resource specified by handle.  Deletes resource and all
 448  * resource type and resource interface linked lists.
 449  *
 450  * @note: OCDeleteResource() performs operations similar to OCNotifyAllObservers() to notify all
 451  * client observers that "this" resource is being deleted.
 452  *
 453  * @param handle          Handle of resource to be deleted.
 454  *
 455  * @return ::OC_STACK_OK on success, some other value upon failure.
 456  */
 457 OCStackResult OCDeleteResource(OCResourceHandle handle);
 458
 459 /**
 460  * Get a string representation the server instance ID.
 461  * The memory is managed internal to this function, so freeing externally will result
 462  * in a runtime error.
 463  * Note: This will NOT seed the RNG, so it must be called after the RNG is seeded.
 464  * This is done automatically during the OCInit process,
 465  * so ensure that this call is done after that.
 466  *
 467  * @return A string representation  the server instance ID.
 468  */
 469 const char* OCGetServerInstanceIDString(void);
 470
 471 /**
 472  * This function gets the URI of the resource specified by handle.
 473  *
 474  * @param handle     Handle of resource.
 475  *
 476  * @return URI string if resource found or NULL if not found.
 477  */
 478 const char *OCGetResourceUri(OCResourceHandle handle);
 479
 480 /**
 481  * This function gets the properties of the resource specified by handle.
 482  *
 483  * @param handle                Handle of resource.
 484  *
 485  * @return OCResourceProperty   Bitmask or -1 if resource is not found.
 486  *
 487  * @note that after a resource is created, the OC_ACTIVE property is set for the resource by the
 488  * stack.
 489  */
 490 OCResourceProperty OCGetResourceProperties(OCResourceHandle handle);
 491
 492 /**
 493  * This function gets the number of resource types of the resource.
 494  *
 495  * @param handle            Handle of resource.
 496  * @param numResourceTypes  Pointer to count variable.
 497  *
 498  * @return ::OC_STACK_OK on success, some other value upon failure.
 499  */
 500 OCStackResult OCGetNumberOfResourceTypes(OCResourceHandle handle, uint8_t *numResourceTypes);
 501
 502 /**
 503  * This function gets name of resource type of the resource.
 504  *
 505  * @param handle       Handle of resource.
 506  * @param index        Index of resource, 0 to Count - 1.
 507  *
 508  * @return Resource type name if resource found or NULL if resource not found.
 509  */
 510 const char *OCGetResourceTypeName(OCResourceHandle handle, uint8_t index);
 511
 512 /**
 513  * This function gets the number of resource interfaces of the resource.
 514  *
 515  * @param handle                 Handle of resource.
 516  * @param numResourceInterfaces  Pointer to count variable.
 517  *
 518  * @return ::OC_STACK_OK on success, some other value upon failure.
 519  */
 520 OCStackResult OCGetNumberOfResourceInterfaces(OCResourceHandle handle,
 521         uint8_t *numResourceInterfaces);
 522
 523 /**
 524  * This function gets name of resource interface of the resource.
 525  *
 526  * @param handle      Handle of resource.
 527  * @param index       Index of resource, 0 to Count - 1.
 528  *
 529  * @return Resource interface name if resource found or NULL if resource not found.
 530  */
 531 const char *OCGetResourceInterfaceName(OCResourceHandle handle, uint8_t index);
 532
 533 /**
 534  * This function gets methods of resource interface of the resource.
 535  *
 536  * @param handle      Handle of resource.
 537  * @param index       Index of resource, 0 to Count - 1.
 538  *
 539  * @return Allowed methods if resource found or NULL if resource not found.
 540  */
 541 uint8_t OCGetResourceInterfaceAllowedMethods(OCResourceHandle handle, uint8_t index);
 542
 543 /**
 544  * This function gets resource handle from the collection resource by index.
 545  *
 546  * @param collectionHandle   Handle of collection resource.
 547  * @param index              Index of contained resource, 0 to Count - 1.
 548  *
 549  * @return Handle to contained resource if resource found or NULL if resource not found.
 550  */
 551 OCResourceHandle OCGetResourceHandleFromCollection(OCResourceHandle collectionHandle,
 552         uint8_t index);
 553
 554 /**
 555  * This function gets the entity handler for a resource.
 556  *
 557  * @param handle            Handle of resource.
 558  *
 559  * @return Entity handler if resource found or NULL resource not found.
 560  */
 561 OCEntityHandler OCGetResourceHandler(OCResourceHandle handle);
 562
 563 /**
 564  * This function notify all registered observers that the resource representation has
 565  * changed. If observation includes a query the client is notified only if the query is valid after
 566  * the resource representation has changed.
 567  *
 568  * @param handle   Handle of resource.
 569  * @param qos      Desired quality of service for the observation notifications.
 570  *
 571  * @return ::OC_STACK_OK on success, some other value upon failure.
 572  */
 573 OCStackResult OCNotifyAllObservers(OCResourceHandle handle, OCQualityOfService qos);
 574
 575 /**
 576  * Notify specific observers with updated value of representation.
 577  * Before this API is invoked by entity handler it has finished processing
 578  * queries for the associated observers.
 579  *
 580  * @param handle                    Handle of resource.
 581  * @param obsIdList                 List of observation IDs that need to be notified.
 582  * @param numberOfIds               Number of observation IDs included in obsIdList.
 583  * @param payload                   Object representing the notification
 584  * @param qos                       Desired quality of service of the observation notifications.
 585  *
 586  * @note: The memory for obsIdList and payload is managed by the entity invoking the API.
 587  * The maximum size of the notification is 1015 bytes for non-Arduino platforms. For Arduino
 588  * the maximum size is 247 bytes.
 589  *
 590  * @return ::OC_STACK_OK on success, some other value upon failure.
 591  */
 592 OCStackResult
 593 OCNotifyListOfObservers (OCResourceHandle handle,
 594                          OCObservationId  *obsIdList,
 595                          uint8_t          numberOfIds,
 596                          const OCRepPayload *payload,
 597                          OCQualityOfService qos);
 598
 599
 600 /**
 601  * This function sends a response to a request.
 602  * The response can be a normal, slow, or block (i.e. a response that
 603  * is too large to be sent in a single PDU and must span multiple transmissions).
 604  *
 605  * @param response   Pointer to structure that contains response parameters.
 606  *
 607  * @return ::OC_STACK_OK on success, some other value upon failure.
 608  */
 609 OCStackResult OCDoResponse(OCEntityHandlerResponse *response);
 610
 611 //#ifdef DIRECT_PAIRING
 612 /**
 613  * The function is responsible for discovery of direct-pairing device is current subnet. It will list
 614  * all the device in subnet which support direct-pairing.
 615  * Caller must NOT free returned constant pointer
 616  *
 617  * @param[in] timeout Timeout in seconds, value till which function will listen to responses from
 618  *                    client before returning the list of devices.
 619  * @return OCDirectPairingDev_t pointer in case of success and NULL otherwise.
 620  */
 621 const OCDPDev_t* OCDiscoverDirectPairingDevices(unsigned short waittime);
 622
 623 /**
 624  * The function is responsible for return of paired device list via direct-pairing. It will list
 625  * all the device which is previousely paired with client.
 626  * Caller must NOT free returned constant pointer
 627  *
 628  * @return OCDirectPairingDev_t pointer in case of success and NULL otherwise.
 629  */
 630 const OCDPDev_t* OCGetDirectPairedDevices();
 631
 632 /**
 633  * The function is responsible for establishment of direct-pairing. It will proceed mode negotiation
 634  * and connect PIN based dtls session.
 635  *
 636  * @param[in] peer Target device to establish direct-pairing.
 637  * @param[in] pmSel Selected mode of pairing.
 638  * @param[in] pinNumber PIN number for authentication, pin lenght is defined DP_PIN_LENGTH(8).
 639  * @param[in] resultCallback Callback fucntion to event status of process.
 640  * @return OTM_SUCCESS in case of success and other value otherwise.
 641  */
 642 OCStackResult OCDoDirectPairing(void *ctx, OCDPDev_t* peer, OCPrm_t pmSel, char *pinNumber,
 643                                 OCDirectPairingCB resultCallback);
 644
 645 #ifdef WITH_CHPROXY
 646 /**
 647  * This function sets uri being used for proxy.
 648  *
 649  * @param uri            NULL terminated resource uri for CoAP-HTTP Proxy.
 650  */
 651 OCStackResult OCSetProxyURI(const char *uri);
 652 #endif
 653
 654 #if defined(RD_CLIENT) || defined(RD_SERVER)
 655 /**
 656  * This function binds an resource unique id to the resource.
 657  *
 658  * @param handle            Handle to the resource that the contained resource is to be bound.
 659  * @param ins               Unique ID for resource.
 660  *
 661  * @return ::OC_STACK_OK on success, some other value upon failure.
 662  */
 663 OCStackResult OCBindResourceInsToResource(OCResourceHandle handle, int64_t ins);
 664
 665 /**
 666  * This function gets the resource unique id for a resource.
 667  *
 668  * @param handle            Handle of resource.
 669  * @param ins               Unique ID for resource.
 670  *
 671  * @return Ins if resource found or 0 resource not found.
 672  */
 673 OCStackResult OCGetResourceIns(OCResourceHandle handle, int64_t *ins);
 674
 675 #endif
 676
 677 /**
 678 * This function gets a resource handle by resource uri.
 679 *
 680 * @param uri   Uri of Resource to get Resource handle.
 681 *
 682 * @return Found  resource handle or NULL if not found.
 683 */
 684 OCResourceHandle OCGetResourceHandleAtUri(const char *uri);
 685
 686
 687 #ifdef RD_SERVER
 688 /**
 689 * Search the RD database for queries.
 690 *
 691 * @param interfaceType is the interface type that is queried.
 692 * @param resourceType is the resource type that is queried.
 693 * @param discPayload is NULL if no resource found or else OCDiscoveryPayload with the details
 694 * about the resource.
 695 *
 696 * @return ::OC_STACK_OK in case of success or else other value.
 697 */
 698 OCStackResult OCRDDatabaseCheckResources(const char *interfaceType, const char *resourceType,
 699     OCDiscoveryPayload *discPayload);
 700 #endif
 701 //#endif // DIRECT_PAIRING
 702
 703 /**
 704  *  Add a header option to the given header option array.
 705  *
 706  * @param ocHdrOpt            Pointer to existing options.
 707  * @param numOptions          Number of existing options.
 708  * @param optionID            COAP option ID.
 709  * @param optionData          Option data value.
 710  * @param optionDataLength    Size of Option data value.
 711  *
 712  * @return ::OC_STACK_OK on success and other value otherwise.
 713  */
 714 OCStackResult
 715 OCSetHeaderOption(OCHeaderOption* ocHdrOpt,
 716                   size_t* numOptions,
 717                   uint16_t optionID,
 718                   const void* optionData,
 719                   size_t optionDataLength);
 720
 721 /**
 722  *  Get data value of the option with specified option ID from given header option array.
 723  *
 724  * @param ocHdrOpt            Pointer to existing options.
 725  * @param numOptions          Number of existing options.
 726  * @param optionID            COAP option ID.
 727  * @param optionData          Pointer to option data.
 728  * @param optionDataLength    Size of option data value.
 729  * @param receivedDatalLength Pointer to the actual length of received data.
 730  *
 731  * @return ::OC_STACK_OK on success and other value otherwise.
 732  */
 733 OCStackResult
 734 OCGetHeaderOption(OCHeaderOption* ocHdrOpt,
 735                   size_t numOptions,
 736                   uint16_t optionID,
 737                   void* optionData,
 738                   size_t optionDataLength,
 739                   uint16_t* receivedDatalLength);
 740
 741 /**
 742  * gets the deviceId of the client
 743  *
 744  * @param deviceId pointer.
 745  * @return Returns ::OC_STACK_OK if success.
 746  */
 747 OCStackResult OCGetDeviceId(OCUUIdentity *deviceId);
 748
 749 /**
 750  * sets the deviceId of the client
 751  *
 752  * @param deviceId pointer.
 753  * @return Returns ::OC_STACK_OK if success.
 754  */
 755 OCStackResult OCSetDeviceId(const OCUUIdentity *deviceId);
 756
 757  /**
 758  * Gets the bool state of "isOwned" property on the doxm resource.
 759  *
 760  * @param isOwned a pointer to be assigned to isOwned property
 761  * @return Returns ::OC_STACK_OK if success.
 762  */
 763 OCStackResult OCGetDeviceOwnedState(bool *isOwned);
 764
 765 /**
 766  * Encode an address string to match RFC 6874.
 767  *
 768  * @param outputAddress    a char array to be written with the encoded string.
 769  *
 770  * @param outputSize       size of outputAddress buffer.
 771  *
 772  * @param inputAddress     a char array of size <= CA_MAX_URI_LENGTH
 773  *                         containing a valid IPv6 address string.
 774  *
 775  * @return ::OC_STACK_OK on success and other value otherwise.
 776  */
 777 OCStackResult OCEncodeAddressForRFC6874(char* outputAddress,
 778                                         size_t outputSize,
 779                                         const char* inputAddress);
 780
 781 /**
 782  * Decode an address string according to RFC 6874.
 783  *
 784  * @param outputAddress    a char array to be written with the decoded string.
 785  *
 786  * @param outputSize       size of outputAddress buffer.
 787  *
 788  * @param inputAddress     a valid percent-encoded address string.
 789  *
 790  * @param end              NULL if the entire entire inputAddress is a null-terminated percent-
 791  *                         encoded address string.  Otherwise, a pointer to the first byte that
 792  *                         is not part of the address string (e.g., ']' in a URI).
 793  *
 794  * @return ::OC_STACK_OK on success and other value otherwise.
 795  */
 796 OCStackResult OCDecodeAddressForRFC6874(char* outputAddress,
 797                                         size_t outputSize,
 798                                         const char* inputAddress,
 799                                         const char* end);
 800
 801 /**
 802  * Set the value of /oic/d and /oic/p properties. This function is a generic function that sets for
 803  * all OCF defined properties.
 804  *
 805  * @param type the payload type for device and platform as defined in @ref OCPayloadType.
 806  * @param propName the pre-defined property as per OCF spec.
 807  * @param value the value of the property to be set.
 808  *
 809  * @return ::OC_STACK_OK on success and other value otherwise.
 810  */
 811 OCStackResult OCSetPropertyValue(OCPayloadType type, const char *propName, const void *value);
 812
 813 /**
 814  * Get the value of /oic/d and /oic/p properties. This function is a generic function that get value
 815  * for all OCF defined properties.
 816  *
 817  * @param type the payload type for device and platform as defined in @ref OCPayloadType.
 818  * @param propName the pre-defined as per OCF spec.
 819  * @param value this holds the return value.  In case of error will be set to NULL.
 820  *
 821  * @return ::OC_STACK_OK on success and other value otherwise.
 822  */
 823 OCStackResult OCGetPropertyValue(OCPayloadType type, const char *propName, void **value);
 824
 825 /**
 826 * Delete client callback info all.
 827 */
 828 void OCClearCallBackList();
 829
 830 /**
 831  * Delete observer info all.
 832  */
 833 void OCClearObserverlist();
 834
 835 /**
 836  * API to encrypt the un-encrypted DB file before OCRegisterPersistentStorageHandler
 837  * If the API is successful, un-encrypted file will be removed, and if the encrypted file
 838  * is currupted, then it restores encrypted file using rescue file.
 839  *
 840  * @param[in] key key used for encryption
 841  * @param[in] psPlain OCPersistentStorage for the plain DB
 842  * @param[in] psEnc OCPersistentStorage for the encrypted DB
 843  * @param[in] psRescue OCPersistentStorage for the rescue DB
 844  *
 845  * @return ::OC_STACK_OK on success and other value otherwise.
 846  */
 847 OCStackResult OCSetSecurePSI(const unsigned char *key, const OCPersistentStorage *psPlain,
 848         const OCPersistentStorage *psEnc, const OCPersistentStorage *psRescue);
 849
 850 /**
 851  * Generic Encryption function to encrypt data buffer in pt
 852  * and update in ct and len in ct_len. (AES-CBC-HMAC)
 853  *
 854  * @param[in] pt plaintext to be encrypted
 855  * @param[in] pt_len length of plaintext
 856  * @param[out] ct ciphered text
 857  * @param[out] ct_len is length of the ciphered text.
 858  *
 859  * @return ::0 for Success.
 860  */
 861 int OCEncrypt(const unsigned char *pt, size_t pt_len,
 862         unsigned char **ct, size_t *ct_len);
 863
 864 /**
 865  * Generic Decryption fucntion to decrypt data buffer in ct
 866  * and update in pt and len in pt_len. (AES-CBC-HMAC)
 867  *
 868  * @param[in] ct ciphered to be decrypted
 869  * @param[in] ct_len length of cipher text
 870  * @param[out] pt plaintext text
 871  * @param[out] pt_len is length of the palintext text.
 872  *
 873  * @return ::0 for Success.
 874  */
 875 int OCDecrypt(const unsigned char *ct, size_t ct_len,
 876         unsigned char **pt, size_t *pt_len);
 877
 878 /**
 879  * API to set key to psi
 880  *
 881  * @param[in] key key used for encryption
 882  * @return ::OC_STACK_OK for Success, otherwise some error value.
 883  */
 884 OCStackResult OCSetKey(const unsigned char* key);
 885
 886 /**
 887  * API to get key from psi
 888  *
 889  * @param[out] key key used for encryption
 890  * @return ::OC_STACK_OK for Success, otherwise some error value.
 891  */
 892 OCStackResult OCGetKey(unsigned char* key);
 893
 894 /**
 895  * API to register OTM event handler
 896  *
 897  * @param[in] ctx user context returned in the callback
 898  * @param[in] cb callback function to receive the OTM event on server side
 899  * @return ::OC_STACK_OK for Success, otherwise some error value.
 900  */
 901 OCStackResult OCSetOtmEventHandler(void *ctx, OCOtmEventHandler cb);
 902
 903  /**
 904  * Gets the bool state of "isOp" property on the pstat resource
 905  * @param isOp a pointer to be assigned to isop property
 906  * @return Returns ::OC_STACK_OK.
 907  */
 908
 909 OCStackResult OCGetDeviceOperationalState(bool* isOp);
 910
 911 #ifdef __cplusplus
 912 }
 913 #endif // __cplusplus
 914
 915 #endif /* OCSTACK_H_ */