/**
* 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__
/** @} */