owner-nrf52sdk/nRF5_SDK_15.3.0/components/iot/coap/coap_api.h

/**
 * Copyright (c) 2014 - 2019, Nordic Semiconductor ASA
 *
 * All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without modification,
 * are permitted provided that the following conditions are met:
 *
 * 1. Redistributions of source code must retain the above copyright notice, this
 *    list of conditions and the following disclaimer.
 *
 * 2. Redistributions in binary form, except as embedded into a Nordic
 *    Semiconductor ASA integrated circuit in a product or a software update for
 *    such product, must reproduce the above copyright notice, this list of
 *    conditions and the following disclaimer in the documentation and/or other
 *    materials provided with the distribution.
 *
 * 3. Neither the name of Nordic Semiconductor ASA nor the names of its
 *    contributors may be used to endorse or promote products derived from this
 *    software without specific prior written permission.
 *
 * 4. This software, with or without modification, must only be used with a
 *    Nordic Semiconductor ASA integrated circuit.
 *
 * 5. Any software provided in binary form under this license must not be reverse
 *    engineered, decompiled, modified and/or disassembled.
 *
 * THIS SOFTWARE IS PROVIDED BY NORDIC SEMICONDUCTOR ASA "AS IS" AND ANY EXPRESS
 * OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
 * OF MERCHANTABILITY, NONINFRINGEMENT, AND FITNESS FOR A PARTICULAR PURPOSE ARE
 * DISCLAIMED. IN NO EVENT SHALL NORDIC SEMICONDUCTOR ASA OR CONTRIBUTORS BE
 * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
 * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE
 * GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
 * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
 * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
 * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 *
 */
/** @file coap_api.h
 *
 * @defgroup iot_sdk_coap_api CoAP Application Programming Interface
 * @ingroup iot_sdk_coap
 * @{
 * @brief Public API of Nordic's CoAP implementation.
 *
 */

#ifndef COAP_API_H__
#define COAP_API_H__

#include <stdint.h>
#include "coap_transport.h"
#include "coap_codes.h"
#include "sdk_config.h"

#ifdef __cplusplus
extern "C" {
#endif

/**@defgroup COAP_CONTENT_TYPE_MASK Resource content type bitmask values
 * @{ */
#define COAP_CT_MASK_PLAIN_TEXT          0x01                     /**< Content type Plain text supported in the endpoint resource. */
#define COAP_CT_MASK_CHARSET_UTF8        0x02                     /**< Content type Charset-UTF8 supported in the endpoint resource. */
#define COAP_CT_MASK_APP_LINK_FORMAT     0x04                     /**< Content type Application/link-format supported in the endpoint resource. */
#define COAP_CT_MASK_APP_XML             0x08                     /**< Content type Application/xml supported in the endpoint resource. */
#define COAP_CT_MASK_APP_OCTET_STREAM    0x10                     /**< Content type Application/octet-stream supported in the endpoint resource. */
#define COAP_CT_MASK_APP_EXI             0x20                     /**< Content type Application/exi supported in the endpoint resource. */
#define COAP_CT_MASK_APP_JSON            0x40                     /**< Content type Application/json supported in the endpoint resource. */
/**@} */

/**@defgroup COAP_METHOD_PERMISSION Resource method permission bitmask values
 * @{ */
#define COAP_PERM_NONE                   0x0000                   /**< Permission by default. Do not allow any method in the COAP/COAPS endpoint resource. */
#define COAP_PERM_GET                    0x0001                   /**< Permission to allow GET method in the COAP endpoint resource. */
#define COAP_PERM_POST                   0x0002                   /**< Permission to allow POST method in the COAP endpoint resource.  */
#define COAP_PERM_PUT                    0x0004                   /**< Permission to allow PUT method in the COAP endpoint resource.  */
#define COAP_PERM_DELETE                 0x0008                   /**< Permission to allow DELETE method in the COAP endpoint resource.  */
#define COAPS_PERM_GET                   0x0010                   /**< Permission to allow GET method in the COAPS endpoint resource.  */
#define COAPS_PERM_POST                  0x0020                   /**< Permission to allow POST method in the COAPS endpoint resource.  */
#define COAPS_PERM_PUT                   0x0040                   /**< Permission to allow PUT method in the COAPS endpoint resource.  */
#define COAPS_PERM_DELETE                0x0080                   /**< Permission to allow DELETE method in the COAPS endpoint resource.  */
#define COAP_PERM_OBSERVE                0x0100                   /**< Permission to allow OBSERVE of the endpoint resource. */
/**@} */

/**@cond */
// Forward declare structs.
typedef struct coap_message_t  coap_message_t;
typedef struct coap_resource_t coap_resource_t;
/**@endcond */

/**@brief Callback function to call upon undefined behaviour.
 *
 * @param[in] error_code Error code from CoAP module.
 * @param[in] p_message  CoAP message processed when error ocoured. Could be NULL.
 */
typedef void (*coap_error_callback_t)(uint32_t error_code, coap_message_t * p_message);

/**@brief Callback function to be registered with CoAP messages.
 *
 * @param[in]  status    Response status. Possible status codes:
 *                       NRF_SUCCESS If response was successfully received,
 *                       COAP_TRANSMISSION_RESET_BY_PEER if a reset response was recieved or,
 *                       COAP_TRANSMISSION_TIMEOUT if transmission
 * @param[in]  p_arg     Miscellaneous pointer to application provided data that is associated with
 *                       the message.
 * @param[in]  p_message Pointer to a CoAP Response message.
 */
typedef void (*coap_response_callback_t)(uint32_t status, void * p_arg, coap_message_t * p_message);

/**@brief Handler function for manually handling all incoming requests.
 *
 * @details If the function is set, the error code given back will trigger error messages
 *          to be sent back by CoAP to indicate failure. Default error message will be 4.00
 *          BAD REQUEST. On success, it is expected that the callback has already sent a
 *          response message.
 *
 * @param[in] p_request Pointer to a CoAP Request message.
 *
 * @retval NRF_SUCCESS         If the message was successfully has been handled.
 * @retval NRF_ERROR_NOT_FOUND If the message did not match any recognized resources, and a
 *                             4.04 NOT FOUND error message should be sent back to the requester.
 * @retval NRF_ERROR_NULL      If the message resolved the resource and operation not permitted,
 *                             and a 4.05 METHOD NOT ALLOWED error message should be sent back to
 *                             the reqester.
 *
 */
typedef uint32_t (*coap_request_handler_t)(coap_message_t * p_request);

#ifdef COAP_AUTOMODE

/**@brief Callback function to be registered with CoAP endpoint resources. in auto-mode.
 *
 * @details The callback needs to implement any action based on the request. The p_response message
 *          will automatically be sent as response when the callback function returns. The memory
 *          is allocated by the caller, so the application does not have to free up the memory used
 *          for the response.
 *
 * @param[in]  p_resource  Pointer to the request message's target resource.
 * @param[in]  p_request   Pointer to the request message.
 * @param[out] p_response  Pointer to the prepared response message. The Application can override
 *                         its values.
 */
typedef void (*coap_method_callback_t) (coap_resource_t * p_resource, coap_message_t * p_request, coap_message_t * p_response);

#else // COAP_AUTOMODE

/**@brief Callback function to be registered with CoAP endpoint resources. in auto-mode.
 *
 * @details The callback needs to implement any action based on the request. The callback is
 *          responsible of handling the sending of any response back to the requester. The memory
 *          for p_request will be freed up by the coap module after the callback has been
 *          completed.
 *
 * @param[in]  p_resource  Pointer to the request message's target resource.
 * @param[in]  p_request   Pointer to the request message.
 */
typedef void (*coap_method_callback_t) (coap_resource_t * p_resource, coap_message_t * p_request);

#endif // COAP_AUTOMODE

/**@brief Enumeration of CoAP content types. */
typedef enum
{
    COAP_CT_PLAIN_TEXT       = 0,                                 /**< Plain text content format number. Default. */
    COAP_CT_APP_LINK_FORMAT  = 40,                                /**< Application/link-format content format number. */
    COAP_CT_APP_XML          = 41,                                /**< Application/xml content format number. */
    COAP_CT_APP_OCTET_STREAM = 42,                                /**< Application/octet-stream content format number. */
    COAP_CT_APP_EXI          = 47,                                /**< Application/exi content format number. */
    COAP_CT_APP_JSON         = 50                                 /**< Application/json content format number. */
} coap_content_type_t;

/**@brief Enumeration of CoAP options numbers. */

#define COAP_OPT_RESERVED0         0                              /**< Reserved option number. */
#define COAP_OPT_IF_MATCH          1                              /**< If-Match option number. */
#define COAP_OPT_URI_HOST          3                              /**< URI-Host option number. */
#define COAP_OPT_ETAG              4                              /**< ETag option number. */
#define COAP_OPT_IF_NONE_MATCH     5                              /**< If-None-Match option number. */
#define COAP_OPT_URI_PORT          7                              /**< URI-Port option number. */
#define COAP_OPT_LOCATION_PATH     8                              /**< Location-Path option number. */
#define COAP_OPT_URI_PATH          11                             /**< URI-Path option number. */
#define COAP_OPT_CONTENT_FORMAT    12                             /**< Content-Format option number. */
#define COAP_OPT_MAX_AGE           14                             /**< Max-Age option number. */
#define COAP_OPT_URI_QUERY         15                             /**< URI-Query option number. */
#define COAP_OPT_ACCEPT            17                             /**< Accept option number. */
#define COAP_OPT_LOCATION_QUERY    20                             /**< Location-Query option number. */
#define COAP_OPT_BLOCK2            23                             /**< Block2 option number. */
#define COAP_OPT_BLOCK1            27                             /**< Block1 option number. */
#define COAP_OPT_SIZE2             28                             /**< Size2 option number. */
#define COAP_OPT_PROXY_URI         35                             /**< Proxy-URI option number. */
#define COAP_OPT_PROXY_SCHEME      39                             /**< Proxy-Scheme option number. */
#define COAP_OPT_SIZE1             60                             /**< Size1 option number. */
#define COAP_OPT_RESERVED1         128                            /**< Reserved option number. */
#define COAP_OPT_RESERVED2         132                            /**< Reserved option number. */
#define COAP_OPT_RESERVED3         136                            /**< Reserved option number. */
#define COAP_OPT_RESERVED4         140                            /**< Reserved option number. */


/**@brief Enumeration of CoAP message types. */
typedef enum
{
    COAP_TYPE_CON = 0,                                            /**< Confirmable Message type. */
    COAP_TYPE_NON,                                                /**< Non-Confirmable Message type. */
    COAP_TYPE_ACK,                                                /**< Acknowledge Message type. */
    COAP_TYPE_RST                                                 /**< Reset Message type. */
} coap_msg_type_t;

/**@brief Structure to hold a CoAP option.
 */
typedef struct
{
    uint16_t                 number;                              /**< Option number (including the extended delta value if any). */
    uint16_t                 length;                              /**< Option length (including the extended length value in any). */
    uint8_t *                p_data;                              /**< Pointer to the memory where the data of the option is located. */
} coap_option_t;



/**@brief Structure to hold a CoAP message configuration.
 *
 * @details The structure is used when calling the \ref coap_message_new API function.
 *          All data supplied will be copied to the created message.
 */
typedef struct
{
    coap_response_callback_t response_callback;                   /**< Callback function to be called when a response matching the token is identified. */
    uint8_t                  token[8];                            /**< Message token. token_len must be set to indicate how many of the bytes should be used in the token. */
    uint8_t                  token_len;                           /**< Token size in bytes. */
    uint16_t                 id;                                  /**< Message ID. If 0 is given, the library will replace this number with an autogenerated value. */
    coap_msg_type_t          type;                                /**< Message type: COAP_TYPE_CON, COAP_TYPE_NON, COAP_TYPE_ACK, or COAP_TYPE_RST. */
    coap_msg_code_t          code;                                /**< Message code (definitions found in coap_msg_code_t). */
    coap_port_t              port;                                /**< Transport layer variable to associate the message with an underlying Transport Layer socket descriptor. */
} coap_message_conf_t;

/**@brief Structure to hold a CoAP message header.
 *
 * @details This structure holds the 4-byte mandatory CoAP header. The structure uses bitfields
 *          to save memory footprint.
 */
typedef struct
{
    uint8_t                  version   :2;                        /**< CoAP version number. The current specification RFC7252 mandates this to be version 1. The version number can be modified in sdk_config.h. */
    uint8_t                  type      :2;                        /**< Message type: COAP_TYPE_CON, COAP_TYPE_NON, COAP_TYPE_ACK, or COAP_TYPE_RST. */
    uint8_t                  token_len :4;                        /**< Length of the message token. */
    uint8_t                  code;                                /**< Message code (definitions found in @ref coap_msg_code_t). */
    uint16_t                 id;                                  /**< Message ID in little-endian format. Convertion to Network Byte Order will be handled by the library. */
} coap_message_header_t;

/**@brief Structure to hold a CoAP message.
 *
 * @details The CoAP message structure contains both internal and public members to
 *          serialize and deserialize data supplied from the application to a byte buffer sent
 *          over UDP. The message structure is used both in transmission and reception, which
 *          makes it easy to handle in an application. Updating the message should be done
 *          using the provided APIs, not by manually assigning new values to the members directly.
 *          Reading the members, on the other hand, is fine.
 */
struct coap_message_t
{
    coap_remote_t            remote;                              /**< Public. Structure containing address information and port number to the remote. */
    coap_remote_t            local;                               /**< Public. Structure containing local destination address information and port number. */
    coap_message_header_t    header;                              /**< Public. Header structure containing the mandatory CoAP 4-byte header fields. */
    uint8_t *                p_payload;                           /**< Public. Pointer to the payload buffer in the message. */
    uint16_t                 payload_len;                         /**< Public. Size of the payload in the message. */
    uint8_t                  options_count;                       /**< Public. The number of options in the message. */
    coap_option_t            options[COAP_MAX_NUMBER_OF_OPTIONS]; /**< Public. Array options in the message. */
    void *                   p_arg;                               /**< Public. Miscellaneous pointer to application provided data that is associated with the message. */

    coap_response_callback_t response_callback;                   /**< Internal. Function callback set by the application to be called when a response to this message is received. Should be set by the application through a configuration parameter. */
    uint8_t                  token[8];                            /**< Internal. Array holding the variable-sized message token. Should be set by the application through a configuration parameter. */
    coap_port_t              port;                                /**< Internal. Transport layer variable to associate the message with an underlying Transport Layer socket descriptor. */
    uint16_t                 options_len;                         /**< Internal. Length of the options including the mandatory header with extension bytes and option data. Accumulated every time a new options is added. */
    uint16_t                 options_offset;                      /**< Internal. Index to where the next option or payload can be added in the message's data buffer */
    uint16_t                 options_delta;                       /**< Internal. Current option number. Used to calculate the next option delta when adding new options to the message. */
    uint8_t *                p_data;                              /**< Internal. Data buffer for adding dynamically sized options and payload. */
    uint16_t                 data_len;                            /**< Internal. Length of the provided data buffer for options and payload. */
};


/**@brief Structure to hold a CoAP endpoint resource.
*/
struct coap_resource_t
{
    uint8_t                  child_count;                         /**< Number of children in the linked list. */
    uint16_t                 permission;                          /**< Bitmask to tell which methods are permitted on the resource. Bit values available can be seen in \ref COAP_METHOD_PERMISSION. */
    coap_resource_t *        p_sibling;                           /**< Sibling pointer to the next element in the list. */
    coap_resource_t *        p_front;                             /**< Pointer to the beginning of the linked list. */
    coap_resource_t *        p_tail;                              /**< Pointer to the last added child in the list. */
    coap_method_callback_t   callback;                            /**< Callback to the resource handler. */
    uint32_t                 ct_support_mask;                     /**< Bitmask to tell which content types are supported by the resource. Bit values available can be seen in \ref COAP_CONTENT_TYPE_MASK. */
    uint32_t                 max_age;                             /**< Max age of resource endpoint value. */
    uint32_t                 expire_time;                         /**< Number of seconds until expire. */
    char                     name[COAP_RESOURCE_MAX_NAME_LEN+1];  /**< Name of the resource. Must be zero terminated. */
};

/**@brief Initializes the CoAP module.
 *
 * @details Initializes the library module and resets internal queues and resource registrations.
 *
 * @param[in] token_rand_seed    Random number seed to be used to generate the token numbers.
 * @param[in] p_transport_params Pointer to transport parameters. Providing the list of ports
 *                               to be used by CoAP.
 *
 * @retval NRF_SUCCESS If initialization succeeded.
 */
uint32_t coap_init(uint32_t token_rand_seed, coap_transport_init_t * p_transport_params);

/**@brief Register error handler callback to the CoAP module.
 *
 * @param[in] error_callback  Function to be called upon unknown messages and failure.
 *
 * @retval NRF_SUCCESS If registration was successful.
 */
uint32_t coap_error_handler_register(coap_error_callback_t error_callback);

/**@brief Register request handler which should handle all incoming requests.
 *
 * @details Setting this request handler redirects all requests to the application provided
 *          callback routine. The callback handler might be cleared by NULL, making coap
 *          module handle the requests and do resource lookup in order to process the
 *          requests.
 *
 * @param[in] p_request_handler Function pointer to the provided request handler.
 *
 * @retval NRF_SUCCESS If registration was successful.
 */
uint32_t coap_request_handler_register(coap_request_handler_t p_request_handler);

/**@brief Sends a CoAP message.
 *
 * @details Sends out a request using the underlying transport layer. Before sending, the
 *          \ref coap_message_t structure is serialized and added to an internal message queue
 *          in the library.  The handle returned can be used to abort the message from being
 *          retransmitted at any time.
 *
 * @param[out] p_handle  Handle to the message if CoAP CON/ACK messages has been used. Returned
 *                       by reference.
 * @param[in]  p_message Message to be sent.
 *
 * @retval NRF_SUCCESS If the message was successfully encoded and scheduled for transmission.
 */
uint32_t coap_message_send(uint32_t * p_handle, coap_message_t * p_message);

/**@brief Abort a CoAP message.
 *
 * @details Aborts an ongoing transmission. If the message has not yet been sent, it will be
 *          deleted from the message queue as well as stop any ongoing re-transmission of the
 *          message.
 *
 * @param[in] handle Handle of the message to abort.
 *
 * @retval NRF_SUCCESS         If the message was successfully aborted and removed from the
 *                             message queue.
 * @retval NRF_ERROR_NOT_FOUND If the message with the given handle was not located in the
 *                             message queue.
 */
uint32_t coap_message_abort(uint32_t handle);

/**@brief Creates CoAP message, initializes, and allocates the needed memory.
 *
 * @details Creates a CoAP message. This is an intermediate representation of the message,
 *          because the message will be serialized by the library before it is transmitted. The structure
 *          is verbose to facilitate configuring the message. Options, payload, and
 *          remote address information can be added using API function calls.
 *
 * @param[inout] p_request Pointer to be filled by the allocated CoAP message structures.
 * @param[in]    p_config  Configuration for the message to be created. Manual configuration
 *                         can be performed after the message creation, except for the CLIENT port
 *                         association.
 *
 * @retval NRF_SUCCESS             If the request was successfully allocated and initialized.
 * @retval NRF_ERROR_INVALID_PARAM If local port number was not configured.
 */
uint32_t coap_message_new(coap_message_t ** p_request, coap_message_conf_t * p_config);

/**@brief Deletes the CoAP request message.
 *
 * @details Frees up memory associated with the request message.
 *
 * @param[in] p_message Pointer to the request message to delete.
 */
uint32_t coap_message_delete(coap_message_t * p_message);

/**@brief Adds a payload to a CoAP message.
 *
 * @details Sets a data payload to a request or response message.
 *
 * This function must be called after all CoAP options have been added.
 *       Due to internal buffers in the library, the payload will be added after any options
 *       in the buffer. If an option is added after the payload, this option will over-write
 *       the payload in the internal buffer.
 *
 * @param[inout] p_message Pointer to the message to add the payload to.
 * @param[in] p_payload Pointer to the payload to be added.
 * @param[in] payload_len Size of the payload to be added.
 *
 * @retval NRF_SUCCESS         If the payload was successfully added to the message.
 * @retval NRF_ERROR_NO_MEM    If the payload could not fit within the allocated payload memory
 *                             defined by sdk_config.h COAP_MESSAGE_DATA_MAX_SIZE.
 */
uint32_t coap_message_payload_set(coap_message_t * p_message,
                                  void *           p_payload,
                                  uint16_t         payload_len);

/**@brief Adds an empty CoAP option to the message.
 *
 * Option numbers must be in ascending order, adding the one with the smallest number
 *       first and greatest last. If the order is incorrect, the delta number calculation will
 *       result in an invalid or wrong delta number for the option.
 *
 * @param[inout] p_message  Pointer to the message to add the option to. Should not be NULL.
 * @param[in]    option_num The option number to add to the message.
 *
 * @retval NRF_SUCCESS         If the empty option was successfully added to the message.
 * @retval NRF_ERROR_DATA_SIZE If the data exceeds the available message buffer data size.
 * @retval NRF_ERROR_NO_MEM    If the maximum number of options that can be added to a message has been reached.
 */
uint32_t coap_message_opt_empty_add(coap_message_t * p_message, uint16_t option_num);

/**@brief Adds a uint CoAP option to the message.
 *
 * Option numbers must be in ascending order, adding the one with the smallest number
 *       first and greatest last. If the order is incorrect, the delta number calculation will
 *       result in an invalid or wrong delta number for the option.
 *
 * @param[inout] p_message  Pointer to the message to add the option to. Should not be NULL.
 * @param[in]    option_num The option number to add to the message.
 * @param[in]    data       An unsigned value (8-bit, 16-bit, or 32-bit) casted to uint32_t.
 *                          The value of the data is used to determine how many bytes
 *                          CoAP must use to represent this option value.
 *
 * @retval NRF_SUCCESS         If the unsigned integer option was successfully added to the message.
 * @retval NRF_ERROR_DATA_SIZE If the data exceeds the available message buffer data size.
 * @retval NRF_ERROR_NO_MEM    If the maximum number of options that can be added to a message has been reached.
 */
uint32_t coap_message_opt_uint_add(coap_message_t * p_message, uint16_t option_num, uint32_t data);

/**@brief Adds a string CoAP option to the message.
 *
 * Option numbers must be in ascending order, adding the one with the smallest number
 *       first and greatest last. If the order is incorrect, the delta number calculation will
 *       result in an invalid or wrong delta number for the option.
 *
 * @param[inout] p_message  Pointer to the message to add the option to. Should not be NULL.
 * @param[in]    option_num The option number to add to the message.
 * @param[in]    p_data     Pointer to a string buffer to be used as value for the option.
 *                          Should not be NULL.
 * @param[in]    length     Length of the string buffer provided.
 *
 * @retval NRF_SUCCESS         If the string option was successfully added to the message.
 * @retval NRF_ERROR_DATA_SIZE If the data exceeds the available message buffer data size.
 * @retval NRF_ERROR_NO_MEM    If the maximum number of options that can be added to a message has been reached.
 */
uint32_t coap_message_opt_str_add(coap_message_t * p_message, uint16_t option_num, uint8_t * p_data, uint16_t length);

/**@brief Adds an opaque CoAP option to the message.
 *
 * Option numbers must be in ascending order, adding the one with the smallest number
 *       first and greatest last. If the order is incorrect, the delta number calculation will
 *       result in an invalid or wrong delta number for the option.
 *
 * @param[inout] p_message  Pointer to the message to add the option to. Should not be NULL.
 * @param[in]    option_num The option number to add to the message.
 * @param[in]    p_data     Pointer to an opaque buffer to be used as value for the option.
 *                          Should not be NULL.
 * @param[in]    length     Length of the opaque buffer provided.
 *
 * @retval NRF_SUCCESS         If the opaque option was successfully added to the message.
 * @retval NRF_ERROR_DATA_SIZE If the data exceeds the available message buffer data size.
 * @retval NRF_ERROR_NO_MEM    If the maximum number of options that can be added to a message has been reached.
 */
uint32_t coap_message_opt_opaque_add(coap_message_t * p_message, uint16_t option_num, uint8_t * p_data, uint16_t length);

/**@brief Sets a remote address and port number to a CoAP message.
 *
 * @details Copies the content of the provided pointer into the CoAP message.
 *
 * @param[inout] p_message  Pointer to the message to add the address information to.
 *                          Should not be NULL.
 * @param[in]    p_address  Pointer to a structure holding the address information for the remote server or client.
 *                          Should not be NULL.
 *
 * @retval  NRF_SUCCESS     When copying the content has finished.
 */
uint32_t coap_message_remote_addr_set(coap_message_t * p_message, coap_remote_t * p_address);

/**@brief Creates a CoAP endpoint resource.
 *
 * @details Initializes the \ref coap_resource_t members.
 *
 * The first resource that is created will be set as the root of the resource
 *       hierarchy.
 *
 * @param[in] p_resource       Pointer to coap_resource_t passed in by reference.
 *                             This variable must be stored in non-volatile memory.
 *                             Should not be NULL.
 * @param[in] name             Verbose name of the service (zero-terminated
 *                             string). The maximum length of a name is defined
 *                             by COAP_RESOURCE_MAX_NAME_LEN in @c sdk_config.h
 *                             and can be adjusted if needed. Should not be NULL.
 * @retval NRF_ERROR_DATA_SIZE If the provided name is larger than the available name buffer.
 * @retval NRF_ERROR_NULL      If the pointer to the resource or the provided
 *                             name buffer is NULL.
 */
uint32_t coap_resource_create(coap_resource_t * p_resource, const char * name);

/**@brief Adds a child resource.
 *
 * @details The hierarchy is constructed as a linked list with a maximum number of children.
 *          COAP_RESOURCE_MAX_DEPTH in @c sdk_config.h sets the maximum depth. The maximum
 *          number of children can be adjusted if more levels are needed.
 *
 * @param[in] p_parent     Resource to attach the child to. Should not be NULL.
 * @param[in] p_child      Child resource to attach. Should not be NULL.
 *
 * @retval NRF_SUCCESS                  If the child was successfully added.
 * @retval COAP_ERROR_MAX_DEPTH_REACHED If the child is exceeding the maximum depth defined.
 */
uint32_t coap_resource_child_add(coap_resource_t * p_parent, coap_resource_t * p_child);

/**@brief Generates .well-known/core string.
 *
 * @details This is a helper function for generating a CoRE link-format encoded string used for
 *          CoAP discovery. The function traverse the resource hierarchy recursively.
 *          The result will be resources listed in link-format. This function can be called when
 *          all resources have been added by the application.
 *
 * @param[inout] string Buffer to use for the .well-known/core string. Should not be NULL.
 * @param[inout] length Length of the string buffer. Returns the used number of bytes from
 *                      the provided buffer.
 *
 * @retval NRF_SUCCESS             If string generation was successful.
 * @retval NRF_ERROR_NULL          If the string buffer was a NULL pointer.
 * @retval NRF_ERROR_DATA_SIZE     If the size of the generated string exceeds the given buffer size.
 * @retval NRF_ERROR_INVALID_STATE If no resource has been registered.
 */
uint32_t coap_resource_well_known_generate(uint8_t * string, uint16_t * length);

/**@brief Get the root resource pointer.
 *
 * @param[out] pp_resource Pointer to be filled with pointer to the root resource.
 *
 * @retval NRF_SUCCESS         If root resource was located.
 * @retval NRF_ERROR_NOT_FOUND If root resource was not located.
 * @retval NRF_ERROR_NULL      If output pointer was NULL.
 */
uint32_t coap_resource_root_get(coap_resource_t ** pp_resource);

/**@brief Check whether a message contains a given CoAP Option.
 *
 * @param[in]  p_message Pointer to the to check for the CoAP Option.
 *                       Should not be NULL.
 * @param[in]  option    CoAP Option to check for in the CoAP message.
 *
 * @retval NRF_SUCCESS         If the CoAP Option is present in the message.
 * @retval NRF_ERROR_NULL      If the pointer to the message is NULL.
 * @retval NRF_ERROR_NOT_FOUND If the CoAP Option is not present in the message.
 */
uint32_t coap_message_opt_present(coap_message_t * p_message, uint16_t option);

/**@brief Check whether a message contains a given CoAP Option and return the index of the entry
 *        in the message option list.
 *
 * @param[in]  p_index   Value by reference to fill the resolved index into. Should not be NULL.
 * @param[in]  p_message Pointer to the to check for the CoAP Option.
 *                       Should not be NULL.
 * @param[in]  option    CoAP Option to check for in the CoAP message.
 *
 * @retval NRF_SUCCESS         If the CoAP Option is present in the message.
 * @retval NRF_ERROR_NULL      If the pointer to the message or the p_index is NULL.
 * @retval NRF_ERROR_NOT_FOUND If the CoAP Option is not present in the message.
 */
uint32_t coap_message_opt_index_get(uint8_t * p_index, coap_message_t * p_message, uint16_t option);

/**@brief Find common content type between the CoAP message and the resource.
 *
 * @details The return value will be the first match between the ACCEPT options and the supported
 *          content types in the resource. The priority is by content-format ID starting going
 *          from the lowest value to the highest.
 *
 * @param[out] p_ct       Resolved content type given by reference. Should not be NULL.
 * @param[in]  p_message  Pointer to the message. Should not be NULL.
 * @param[in]  p_resource Pointer to the resource. Should not be NULL.
 *
 * @retval NRF_SUCCESS         If match was found.
 * @retval NRF_ERROR_NOT_FOUND If no match was found.
 */
uint32_t coap_message_ct_match_select(coap_content_type_t * p_ct, coap_message_t * p_message, coap_resource_t * p_resource);

/**@brief CoAP time tick used for retransmitting any message in the queue if needed.
 *
 * @retval NRF_SUCCESS         If time tick update was successfully handled.
 */
uint32_t coap_time_tick(void);

#if (COAP_DISABLE_DTLS_API == 0)
/**@brief Setup secure DTLS session.
 *
 * @details For the client role, this API triggers a DTLS handshake. Until the handshake is complete
 *          with the remote, \ref coap_message_send will fail.
 *          For the server role, this API does not create any DTLS session. A DTLS session is
 *          created each time a new client remote endpoint sends a request on the local port of the
 *          server.
 *
 * @note The success of this function does not imply that the DTLS handshake is successfull.
 *
 * @note Only one DTLS session is permitted between a local and remote endpoint. Therefore, in case
 *       a DTLS session was established between the local and remote endpoint, the existing DTLS
 *       session will be reused irrespective of the role and number of times this API was called.
 *       In case the application desires a fresh security setup, it must first call the
 *       \ref coap_security_destroy to tear down the existing setup.
 *
 * @param[in] local_port Local port to bind the session to.
 * @param[in] role       Role of the session. DTLS server or client defined in the enumeration
 *                       \ref nrf_tls_role_t.
 * @param[in] p_remote   Pointer to a structure holding the address information for the remote
 *                       endpoint. If a the device is acting as a server, a NULL pointer shall be
 *                       given as a parameter. Rationale: The server is not envisioned to be
 *                       bound a pre-known client endpoint. Therefore, security server settings
 *                       shall be setup irrespective of the remote client.
 * @param[in] p_settings Pointer to a structure holding the DTLS credentials.
 *
 * @retval NRF_SUCCESS If setup of the secure DTLS session was successfull.
 */
uint32_t coap_security_setup(uint16_t                       local_port,
                             nrf_tls_role_t                 role,
                             coap_remote_t          * const p_remote,
                             nrf_tls_key_settings_t * const p_settings);


/**@brief Destroy a secure DTLS session.
 *
 * @details Terminate and clean up any session associated with the local port and the remote.
 *
 * @param[in] local_port Local port to unbind the session from.
 * @param[in] p_remote   Pointer to a structure holding the address information for the remote
 *                       endpoint. Providing a NULL as p_remote will clean up all DTLS sessions
 *                       associated with the local port.
 *
 * @retval NRF_SUCCESS If the destruction of the secure DTLS session was successfull.
 */
uint32_t coap_security_destroy(uint16_t              local_port,
                               coap_remote_t * const p_remote);

#endif // COAP_DISABLE_DTLS_API

/**@brief Process loop when using coap BSD socket transport implementation.
 *
 * @details This is blocking call. The function unblock is only
 *          triggered upon an socket event registered to select() by coap transport.
 *          This function must be called as often as possible in order to dispatch incoming
 *          socket events. Preferred to be put in the application's main loop or similar.
 **/
void coap_input(void);

#ifdef __cplusplus
}
#endif

#endif // COAP_API_H__

/** @} */