diff options
Diffstat (limited to 'thirdparty/nRF5_SDK_15.0.0_a53641a/components/iot/coap/coap_api.h')
| -rw-r--r-- | thirdparty/nRF5_SDK_15.0.0_a53641a/components/iot/coap/coap_api.h | 663 |
1 files changed, 663 insertions, 0 deletions
diff --git a/thirdparty/nRF5_SDK_15.0.0_a53641a/components/iot/coap/coap_api.h b/thirdparty/nRF5_SDK_15.0.0_a53641a/components/iot/coap/coap_api.h new file mode 100644 index 0000000..9bc0222 --- /dev/null +++ b/thirdparty/nRF5_SDK_15.0.0_a53641a/components/iot/coap/coap_api.h @@ -0,0 +1,663 @@ +/** + * Copyright (c) 2014 - 2018, 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__ + +/** @} */ |