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