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