Timothy Beight / Mbed 2 deprecated 6_songs-from-the-cloud

This is a fork due to permission issues

Dependencies:   mbed Socket lwip-eth lwip-sys lwip

Fork of 6_songs-from-the-cloud by MakingMusicWorkshop

mbed-client/mbed-client-c/nsdl-c/sn_coap_protocol.h@0:f7c60d3e7b8a, 2016-05-18 (annotated)

Committer:
maclobdell
Date:
Wed May 18 19:06:32 2016 +0000
Revision:
0:f7c60d3e7b8a
clean version

Who changed what in which revision?

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