sandbox / mbed-client-c

Important changes to repositories hosted on mbed.com

Mbed hosted mercurial repositories are deprecated and are due to be permanently deleted in July 2026.

To keep a copy of this software download the repository Zip archive or clone locally using Mercurial.

It is also possible to export all your personal repositories from the account settings page.

Fork of mbed-client-c by Christopher Haster

nsdl-c/sn_coap_protocol.h@1:43f5c94c6771, 2016-01-22 (annotated)

Committer:
Christopher Haster
Date:
Fri Jan 22 16:31:54 2016 -0600
Revision:
1:43f5c94c6771
Child:
4:5d91b0f5038c
Initial move of mbed-client-c to mercurial

Who changed what in which revision?

UserRevisionLine numberNew contents of line
Christopher Haster 1:43f5c94c6771 1 /*
Christopher Haster 1:43f5c94c6771 2 * Copyright (c) 2011-2015 ARM Limited. All rights reserved.
Christopher Haster 1:43f5c94c6771 3 * SPDX-License-Identifier: Apache-2.0
Christopher Haster 1:43f5c94c6771 4 * Licensed under the Apache License, Version 2.0 (the License); you may
Christopher Haster 1:43f5c94c6771 5 * not use this file except in compliance with the License.
Christopher Haster 1:43f5c94c6771 6 * You may obtain a copy of the License at
Christopher Haster 1:43f5c94c6771 7 *
Christopher Haster 1:43f5c94c6771 8 * http://www.apache.org/licenses/LICENSE-2.0
Christopher Haster 1:43f5c94c6771 9 *
Christopher Haster 1:43f5c94c6771 10 * Unless required by applicable law or agreed to in writing, software
Christopher Haster 1:43f5c94c6771 11 * distributed under the License is distributed on an AS IS BASIS, WITHOUT
Christopher Haster 1:43f5c94c6771 12 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
Christopher Haster 1:43f5c94c6771 13 * See the License for the specific language governing permissions and
Christopher Haster 1:43f5c94c6771 14 * limitations under the License.
Christopher Haster 1:43f5c94c6771 15 */
Christopher Haster 1:43f5c94c6771 16
Christopher Haster 1:43f5c94c6771 17 /**
Christopher Haster 1:43f5c94c6771 18 * \file sn_coap_protocol.h
Christopher Haster 1:43f5c94c6771 19 *
Christopher Haster 1:43f5c94c6771 20 * \brief CoAP C-library User protocol interface header file
Christopher Haster 1:43f5c94c6771 21 */
Christopher Haster 1:43f5c94c6771 22
Christopher Haster 1:43f5c94c6771 23 #ifdef __cplusplus
Christopher Haster 1:43f5c94c6771 24 extern "C" {
Christopher Haster 1:43f5c94c6771 25 #endif
Christopher Haster 1:43f5c94c6771 26
Christopher Haster 1:43f5c94c6771 27 #ifndef SN_COAP_PROTOCOL_H_
Christopher Haster 1:43f5c94c6771 28 #define SN_COAP_PROTOCOL_H_
Christopher Haster 1:43f5c94c6771 29
Christopher Haster 1:43f5c94c6771 30 #include "sn_coap_header.h"
Christopher Haster 1:43f5c94c6771 31
Christopher Haster 1:43f5c94c6771 32 /**
Christopher Haster 1:43f5c94c6771 33 * \fn struct coap_s *sn_coap_protocol_init(void* (*used_malloc_func_ptr)(uint16_t), void (*used_free_func_ptr)(void*),
Christopher Haster 1:43f5c94c6771 34 uint8_t (*used_tx_callback_ptr)(sn_nsdl_capab_e , uint8_t *, uint16_t, sn_nsdl_addr_s *),
Christopher Haster 1:43f5c94c6771 35 int8_t (*used_rx_callback_ptr)(sn_coap_hdr_s *, sn_nsdl_addr_s *)
Christopher Haster 1:43f5c94c6771 36 *
Christopher Haster 1:43f5c94c6771 37 * \brief Initializes CoAP Protocol part. When using libNsdl, sn_nsdl_init() calls this function.
Christopher Haster 1:43f5c94c6771 38 *
Christopher Haster 1:43f5c94c6771 39 * \param *used_malloc_func_ptr is function pointer for used memory allocation function.
Christopher Haster 1:43f5c94c6771 40 *
Christopher Haster 1:43f5c94c6771 41 * \param *used_free_func_ptr is function pointer for used memory free function.
Christopher Haster 1:43f5c94c6771 42 *
Christopher Haster 1:43f5c94c6771 43 * \param *used_tx_callback_ptr function callback pointer to tx function for sending coap messages
Christopher Haster 1:43f5c94c6771 44 *
Christopher Haster 1:43f5c94c6771 45 * \param *used_rx_callback_ptr used to return CoAP header struct with status COAP_STATUS_BUILDER_MESSAGE_SENDING_FAILED
Christopher Haster 1:43f5c94c6771 46 * when re-sendings exceeded. If set to NULL, no error message is returned.
Christopher Haster 1:43f5c94c6771 47 *
Christopher Haster 1:43f5c94c6771 48 * \return Pointer to handle when success
Christopher Haster 1:43f5c94c6771 49 * Null if failed
Christopher Haster 1:43f5c94c6771 50 */
Christopher Haster 1:43f5c94c6771 51
Christopher Haster 1:43f5c94c6771 52 extern struct coap_s *sn_coap_protocol_init(void *(*used_malloc_func_ptr)(uint16_t), void (*used_free_func_ptr)(void *),
Christopher Haster 1:43f5c94c6771 53 uint8_t (*used_tx_callback_ptr)(uint8_t *, uint16_t, sn_nsdl_addr_s *, void *),
Christopher Haster 1:43f5c94c6771 54 int8_t (*used_rx_callback_ptr)(sn_coap_hdr_s *, sn_nsdl_addr_s *, void *));
Christopher Haster 1:43f5c94c6771 55
Christopher Haster 1:43f5c94c6771 56 /**
Christopher Haster 1:43f5c94c6771 57 * \fn int8_t sn_coap_protocol_destroy(void)
Christopher Haster 1:43f5c94c6771 58 *
Christopher Haster 1:43f5c94c6771 59 * \brief Frees all memory from CoAP protocol part
Christopher Haster 1:43f5c94c6771 60 *
Christopher Haster 1:43f5c94c6771 61 * \param *handle Pointer to CoAP library handle
Christopher Haster 1:43f5c94c6771 62 *
Christopher Haster 1:43f5c94c6771 63 * \return Return value is always 0
Christopher Haster 1:43f5c94c6771 64 */
Christopher Haster 1:43f5c94c6771 65 extern int8_t sn_coap_protocol_destroy(struct coap_s *handle);
Christopher Haster 1:43f5c94c6771 66
Christopher Haster 1:43f5c94c6771 67 /**
Christopher Haster 1:43f5c94c6771 68 * \fn int16_t sn_coap_protocol_build(struct coap_s *handle, sn_nsdl_addr_s *dst_addr_ptr, uint8_t *dst_packet_data_ptr, sn_coap_hdr_s *src_coap_msg_ptr)
Christopher Haster 1:43f5c94c6771 69 *
Christopher Haster 1:43f5c94c6771 70 * \brief Builds Packet data from given CoAP header structure to be sent
Christopher Haster 1:43f5c94c6771 71 *
Christopher Haster 1:43f5c94c6771 72 * \param *dst_addr_ptr is pointer to destination address where CoAP message
Christopher Haster 1:43f5c94c6771 73 * will be sent (CoAP builder needs that information for message resending purposes)
Christopher Haster 1:43f5c94c6771 74 *
Christopher Haster 1:43f5c94c6771 75 * \param *dst_packet_data_ptr is pointer to destination of built Packet data
Christopher Haster 1:43f5c94c6771 76 *
Christopher Haster 1:43f5c94c6771 77 * \param *src_coap_msg_ptr is pointer to source of built Packet data
Christopher Haster 1:43f5c94c6771 78 *
Christopher Haster 1:43f5c94c6771 79 * \param param void pointer that will be passed to tx/rx function callback when those are called.
Christopher Haster 1:43f5c94c6771 80 *
Christopher Haster 1:43f5c94c6771 81 * \return Return value is byte count of built Packet data.\n
Christopher Haster 1:43f5c94c6771 82 * Note: If message is blockwised, all payload is not sent at the same time\n
Christopher Haster 1:43f5c94c6771 83 * In failure cases:\n
Christopher Haster 1:43f5c94c6771 84 * -1 = Failure in CoAP header structure\n
Christopher Haster 1:43f5c94c6771 85 * -2 = Failure in given pointer (= NULL)\n
Christopher Haster 1:43f5c94c6771 86 * -3 = Failure in Reset message\ŋ
Christopher Haster 1:43f5c94c6771 87 * If there is not enough memory (or User given limit exceeded) for storing
Christopher Haster 1:43f5c94c6771 88 * resending messages, situation is ignored.
Christopher Haster 1:43f5c94c6771 89 */
Christopher Haster 1:43f5c94c6771 90 extern int16_t sn_coap_protocol_build(struct coap_s *handle, sn_nsdl_addr_s *dst_addr_ptr, uint8_t *dst_packet_data_ptr, sn_coap_hdr_s *src_coap_msg_ptr, void *param);
Christopher Haster 1:43f5c94c6771 91
Christopher Haster 1:43f5c94c6771 92 /**
Christopher Haster 1:43f5c94c6771 93 * \fn sn_coap_hdr_s *sn_coap_protocol_parse(struct coap_s *handle, sn_nsdl_addr_s *src_addr_ptr, uint16_t packet_data_len, uint8_t *packet_data_ptr)
Christopher Haster 1:43f5c94c6771 94 *
Christopher Haster 1:43f5c94c6771 95 * \brief Parses received CoAP message from given Packet data
Christopher Haster 1:43f5c94c6771 96 *
Christopher Haster 1:43f5c94c6771 97 * \param *src_addr_ptr is pointer to source address of received CoAP message
Christopher Haster 1:43f5c94c6771 98 * (CoAP parser needs that information for Message acknowledgement)
Christopher Haster 1:43f5c94c6771 99 *
Christopher Haster 1:43f5c94c6771 100 * \param *handle Pointer to CoAP library handle
Christopher Haster 1:43f5c94c6771 101 *
Christopher Haster 1:43f5c94c6771 102 * \param packet_data_len is length of given Packet data to be parsed to CoAP message
Christopher Haster 1:43f5c94c6771 103 *
Christopher Haster 1:43f5c94c6771 104 * \param *packet_data_ptr is pointer to source of Packet data to be parsed to CoAP message
Christopher Haster 1:43f5c94c6771 105 *
Christopher Haster 1:43f5c94c6771 106 * \param param void pointer that will be passed to tx/rx function callback when those are called.
Christopher Haster 1:43f5c94c6771 107 *
Christopher Haster 1:43f5c94c6771 108 * \return Return value is pointer to parsed CoAP message structure. This structure includes also coap_status field.\n
Christopher Haster 1:43f5c94c6771 109 * In following failure cases NULL is returned:\n
Christopher Haster 1:43f5c94c6771 110 * -Given NULL pointer\n
Christopher Haster 1:43f5c94c6771 111 * -Failure in parsed header of non-confirmable message\ŋ
Christopher Haster 1:43f5c94c6771 112 * -Out of memory (malloc() returns NULL)
Christopher Haster 1:43f5c94c6771 113 */
Christopher Haster 1:43f5c94c6771 114 extern sn_coap_hdr_s *sn_coap_protocol_parse(struct coap_s *handle, sn_nsdl_addr_s *src_addr_ptr, uint16_t packet_data_len, uint8_t *packet_data_ptr, void *);
Christopher Haster 1:43f5c94c6771 115
Christopher Haster 1:43f5c94c6771 116 /**
Christopher Haster 1:43f5c94c6771 117 * \fn int8_t sn_coap_protocol_exec(struct coap_s *handle, uint32_t current_time)
Christopher Haster 1:43f5c94c6771 118 *
Christopher Haster 1:43f5c94c6771 119 * \brief Sends CoAP messages from re-sending queue, if there is any.
Christopher Haster 1:43f5c94c6771 120 * Cleans also old messages from the duplication list and from block receiving list
Christopher Haster 1:43f5c94c6771 121 *
Christopher Haster 1:43f5c94c6771 122 * This function can be called e.g. once in a second but also more frequently.
Christopher Haster 1:43f5c94c6771 123 *
Christopher Haster 1:43f5c94c6771 124 * \param *handle Pointer to CoAP library handle
Christopher Haster 1:43f5c94c6771 125 *
Christopher Haster 1:43f5c94c6771 126 * \param current_time is System time in seconds. This time is
Christopher Haster 1:43f5c94c6771 127 * used for message re-sending timing and to identify old saved data.
Christopher Haster 1:43f5c94c6771 128 *
Christopher Haster 1:43f5c94c6771 129 * \return 0 if success
Christopher Haster 1:43f5c94c6771 130 * -1 if failed
Christopher Haster 1:43f5c94c6771 131 */
Christopher Haster 1:43f5c94c6771 132
Christopher Haster 1:43f5c94c6771 133 extern int8_t sn_coap_protocol_exec(struct coap_s *handle, uint32_t current_time);
Christopher Haster 1:43f5c94c6771 134
Christopher Haster 1:43f5c94c6771 135 /**
Christopher Haster 1:43f5c94c6771 136 * \fn int8_t sn_coap_protocol_set_block_size(uint16_t block_size)
Christopher Haster 1:43f5c94c6771 137 *
Christopher Haster 1:43f5c94c6771 138 * \brief If block transfer is enabled, this function changes the block size.
Christopher Haster 1:43f5c94c6771 139 *
Christopher Haster 1:43f5c94c6771 140 * \param uint16_t block_size maximum size of CoAP payload. Valid sizes are 16, 32, 64, 128, 256, 512 and 1024 bytes
Christopher Haster 1:43f5c94c6771 141 * \return 0 = success
Christopher Haster 1:43f5c94c6771 142 * -1 = failure
Christopher Haster 1:43f5c94c6771 143 */
Christopher Haster 1:43f5c94c6771 144 extern int8_t sn_coap_protocol_set_block_size(uint16_t block_size);
Christopher Haster 1:43f5c94c6771 145
Christopher Haster 1:43f5c94c6771 146 /**
Christopher Haster 1:43f5c94c6771 147 * \fn int8_t sn_coap_protocol_set_duplicate_buffer_size(uint8_t message_count)
Christopher Haster 1:43f5c94c6771 148 *
Christopher Haster 1:43f5c94c6771 149 * \brief If dublicate message detection is enabled, this function changes buffer size.
Christopher Haster 1:43f5c94c6771 150 *
Christopher Haster 1:43f5c94c6771 151 * \param uint8_t message_count max number of messages saved for duplicate control
Christopher Haster 1:43f5c94c6771 152 * \return 0 = success
Christopher Haster 1:43f5c94c6771 153 * -1 = failure
Christopher Haster 1:43f5c94c6771 154 */
Christopher Haster 1:43f5c94c6771 155 extern int8_t sn_coap_protocol_set_duplicate_buffer_size(uint8_t message_count);
Christopher Haster 1:43f5c94c6771 156
Christopher Haster 1:43f5c94c6771 157 /**
Christopher Haster 1:43f5c94c6771 158 * \fn int8_t sn_coap_protocol_set_retransmission_parameters(uint8_t resending_count, uint8_t resending_intervall)
Christopher Haster 1:43f5c94c6771 159 *
Christopher Haster 1:43f5c94c6771 160 * \brief If re-transmissions are enabled, this function changes resending count and interval.
Christopher Haster 1:43f5c94c6771 161 *
Christopher Haster 1:43f5c94c6771 162 * \param uint8_t resending_count max number of resendings for message
Christopher Haster 1:43f5c94c6771 163 * \param uint8_t resending_intervall message resending intervall in seconds
Christopher Haster 1:43f5c94c6771 164 * \return 0 = success
Christopher Haster 1:43f5c94c6771 165 * -1 = failure
Christopher Haster 1:43f5c94c6771 166 */
Christopher Haster 1:43f5c94c6771 167 extern int8_t sn_coap_protocol_set_retransmission_parameters(uint8_t resending_count, uint8_t resending_interval);
Christopher Haster 1:43f5c94c6771 168
Christopher Haster 1:43f5c94c6771 169 /**
Christopher Haster 1:43f5c94c6771 170 * \fn int8_t sn_coap_protocol_set_retransmission_buffer(uint8_t buffer_size_messages, uint16_t buffer_size_bytes)
Christopher Haster 1:43f5c94c6771 171 *
Christopher Haster 1:43f5c94c6771 172 * \brief If re-transmissions are enabled, this function changes message retransmission queue size.
Christopher Haster 1:43f5c94c6771 173 * Set size to '0' to disable feature. If both are set to '0', then re-sendings are disabled.
Christopher Haster 1:43f5c94c6771 174 *
Christopher Haster 1:43f5c94c6771 175 * \param uint8_t buffer_size_messages queue size - maximum number of messages to be saved to queue
Christopher Haster 1:43f5c94c6771 176 * \param uint8_t buffer_size_bytes queue size - maximum size of messages saved to queue
Christopher Haster 1:43f5c94c6771 177 * \return 0 = success
Christopher Haster 1:43f5c94c6771 178 * -1 = failure
Christopher Haster 1:43f5c94c6771 179 */
Christopher Haster 1:43f5c94c6771 180 extern int8_t sn_coap_protocol_set_retransmission_buffer(uint8_t buffer_size_messages, uint16_t buffer_size_bytes);
Christopher Haster 1:43f5c94c6771 181
Christopher Haster 1:43f5c94c6771 182 /**
Christopher Haster 1:43f5c94c6771 183 * \fn void sn_coap_protocol_clear_retransmission_buffer(struct coap_s *handle)
Christopher Haster 1:43f5c94c6771 184 *
Christopher Haster 1:43f5c94c6771 185 * \param *handle Pointer to CoAP library handle
Christopher Haster 1:43f5c94c6771 186 *
Christopher Haster 1:43f5c94c6771 187 * \brief If re-transmissions are enabled, this function removes all messages from the retransmission queue.
Christopher Haster 1:43f5c94c6771 188 */
Christopher Haster 1:43f5c94c6771 189 extern void sn_coap_protocol_clear_retransmission_buffer(struct coap_s *handle);
Christopher Haster 1:43f5c94c6771 190
Christopher Haster 1:43f5c94c6771 191 #endif /* SN_COAP_PROTOCOL_H_ */
Christopher Haster 1:43f5c94c6771 192
Christopher Haster 1:43f5c94c6771 193 #ifdef __cplusplus
Christopher Haster 1:43f5c94c6771 194 }
Christopher Haster 1:43f5c94c6771 195 #endif
Christopher Haster 1:43f5c94c6771 196