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