sn_coap_protocol.h

00001 /*
00002  * Copyright (c) 2011-2015 ARM Limited. All rights reserved.
00003  * SPDX-License-Identifier: Apache-2.0
00004  * Licensed under the Apache License, Version 2.0 (the License); you may
00005  * not use this file except in compliance with the License.
00006  * You may obtain a copy of the License at
00007  *
00008  * http://www.apache.org/licenses/LICENSE-2.0
00009  *
00010  * Unless required by applicable law or agreed to in writing, software
00011  * distributed under the License is distributed on an AS IS BASIS, WITHOUT
00012  * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
00013  * See the License for the specific language governing permissions and
00014  * limitations under the License.
00015  */
00016 
00017 /**
00018  * \file sn_coap_protocol.h
00019  *
00020  * \brief CoAP C-library User protocol interface header file
00021  */
00022 
00023 #ifdef __cplusplus
00024 extern "C" {
00025 #endif
00026 
00027 #ifndef SN_COAP_PROTOCOL_H_
00028 #define SN_COAP_PROTOCOL_H_
00029 
00030 #include "sn_coap_header.h"
00031 
00032 /**
00033  * \fn struct coap_s *sn_coap_protocol_init(void* (*used_malloc_func_ptr)(uint16_t), void (*used_free_func_ptr)(void*),
00034         uint8_t (*used_tx_callback_ptr)(sn_nsdl_capab_e , uint8_t *, uint16_t, sn_nsdl_addr_s *),
00035         int8_t (*used_rx_callback_ptr)(sn_coap_hdr_s *, sn_nsdl_addr_s *)
00036  *
00037  * \brief Initializes CoAP Protocol part. When using libNsdl, sn_nsdl_init() calls this function.
00038  *
00039  * \param *used_malloc_func_ptr is function pointer for used memory allocation function.
00040  *
00041  * \param *used_free_func_ptr is function pointer for used memory free function. Note: the implementation
00042  *          must handle NULL parameter and ignore it just as typical libc's free() does.
00043  *
00044  * \param *used_tx_callback_ptr function callback pointer to tx function for sending coap messages
00045  *
00046  * \param *used_rx_callback_ptr used to return CoAP header struct with status COAP_STATUS_BUILDER_MESSAGE_SENDING_FAILED
00047  *        when re-sendings exceeded. If set to NULL, no error message is returned.
00048  *
00049  * \return  Pointer to handle when success
00050  *          Null if failed
00051  */
00052 
00053 extern struct coap_s *sn_coap_protocol_init(void *(*used_malloc_func_ptr)(uint16_t), void (*used_free_func_ptr)(void *),
00054         uint8_t (*used_tx_callback_ptr)(uint8_t *, uint16_t, sn_nsdl_addr_s *, void *),
00055         int8_t (*used_rx_callback_ptr)(sn_coap_hdr_s *, sn_nsdl_addr_s *, void *));
00056 
00057 /**
00058  * \fn int8_t sn_coap_protocol_destroy(void)
00059  *
00060  * \brief Frees all memory from CoAP protocol part
00061  *
00062  * \param *handle Pointer to CoAP library handle
00063  *
00064  * \return Return value is always 0
00065  */
00066 extern int8_t sn_coap_protocol_destroy(struct coap_s *handle);
00067 
00068 /**
00069  * \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, void *param)
00070  *
00071  * \brief Builds Packet data from given CoAP header structure to be sent
00072  *
00073  * \param *dst_addr_ptr is pointer to destination address where CoAP message
00074  *        will be sent (CoAP builder needs that information for message resending purposes)
00075  *
00076  * \param *dst_packet_data_ptr is pointer to destination of built Packet data
00077  *
00078  * \param *src_coap_msg_ptr is pointer to source of built Packet data
00079  *
00080  * \param param void pointer that will be passed to tx/rx function callback when those are called.
00081  *
00082  * \return Return value is byte count of built Packet data.\n
00083  *         Note: If message is blockwised, all payload is not sent at the same time\n
00084  *         In failure cases:\n
00085  *          -1 = Failure in CoAP header structure\n
00086  *          -2 = Failure in given pointer (= NULL)\n
00087  *          -3 = Failure in Reset message\n
00088  *          -4 = Failure in Resending message store\n
00089  *         If there is not enough memory (or User given limit exceeded) for storing
00090  *         resending messages, situation is ignored.
00091  */
00092 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);
00093 
00094 /**
00095  * \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)
00096  *
00097  * \brief Parses received CoAP message from given Packet data
00098  *
00099  * \param *src_addr_ptr is pointer to source address of received CoAP message
00100  *        (CoAP parser needs that information for Message acknowledgement)
00101  *
00102  * \param *handle Pointer to CoAP library handle
00103  *
00104  * \param packet_data_len is length of given Packet data to be parsed to CoAP message
00105  *
00106  * \param *packet_data_ptr is pointer to source of Packet data to be parsed to CoAP message
00107  *
00108  * \param param void pointer that will be passed to tx/rx function callback when those are called.
00109  *
00110  * \return Return value is pointer to parsed CoAP message structure. This structure includes also coap_status field.\n
00111  *         In following failure cases NULL is returned:\n
00112  *          -Given NULL pointer\n
00113  *          -Failure in parsed header of non-confirmable message\ŋ
00114  *          -Out of memory (malloc() returns NULL)
00115  */
00116 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 *);
00117 
00118 /**
00119  * \fn int8_t sn_coap_protocol_exec(struct coap_s *handle, uint32_t current_time)
00120  *
00121  * \brief Sends CoAP messages from re-sending queue, if there is any.
00122  *        Cleans also old messages from the duplication list and from block receiving list
00123  *
00124  *        This function can be called e.g. once in a second but also more frequently.
00125  *
00126  * \param *handle Pointer to CoAP library handle
00127  *
00128  * \param current_time is System time in seconds. This time is
00129  *        used for message re-sending timing and to identify old saved data.
00130  *
00131  * \return  0 if success
00132  *          -1 if failed
00133  */
00134 
00135 extern int8_t sn_coap_protocol_exec(struct coap_s *handle, uint32_t current_time);
00136 
00137 /**
00138  * \fn int8_t sn_coap_protocol_set_block_size(uint16_t block_size)
00139  *
00140  * \brief If block transfer is enabled, this function changes the block size.
00141  *
00142  * \param uint16_t block_size maximum size of CoAP payload. Valid sizes are 16, 32, 64, 128, 256, 512 and 1024 bytes
00143  * \return  0 = success
00144  *          -1 = failure
00145  */
00146 extern int8_t sn_coap_protocol_set_block_size(struct coap_s *handle, uint16_t block_size);
00147 
00148 /**
00149  * \fn int8_t sn_coap_protocol_set_duplicate_buffer_size(uint8_t message_count)
00150  *
00151  * \brief If dublicate message detection is enabled, this function changes buffer size.
00152  *
00153  * \param uint8_t message_count max number of messages saved for duplicate control
00154  * \return  0 = success
00155  *          -1 = failure
00156  */
00157 extern int8_t sn_coap_protocol_set_duplicate_buffer_size(struct coap_s *handle, uint8_t message_count);
00158 
00159 /**
00160  * \fn int8_t sn_coap_protocol_set_retransmission_parameters(uint8_t resending_count, uint8_t resending_intervall)
00161  *
00162  * \brief  If re-transmissions are enabled, this function changes resending count and interval.
00163  *
00164  * \param uint8_t resending_count max number of resendings for message
00165  * \param uint8_t resending_intervall message resending intervall in seconds
00166  * \return  0 = success, -1 = failure
00167  */
00168 extern int8_t sn_coap_protocol_set_retransmission_parameters(struct coap_s *handle,
00169         uint8_t resending_count, uint8_t resending_interval);
00170 
00171 /**
00172  * \fn int8_t sn_coap_protocol_set_retransmission_buffer(uint8_t buffer_size_messages, uint16_t buffer_size_bytes)
00173  *
00174  * \brief If re-transmissions are enabled, this function changes message retransmission queue size.
00175  *  Set size to '0' to disable feature. If both are set to '0', then re-sendings are disabled.
00176  *
00177  * \param uint8_t buffer_size_messages queue size - maximum number of messages to be saved to queue
00178  * \param uint8_t buffer_size_bytes queue size - maximum size of messages saved to queue
00179  * \return  0 = success, -1 = failure
00180  */
00181 extern int8_t sn_coap_protocol_set_retransmission_buffer(struct coap_s *handle,
00182         uint8_t buffer_size_messages, uint16_t buffer_size_bytes);
00183 
00184 /**
00185  * \fn void sn_coap_protocol_clear_retransmission_buffer(struct coap_s *handle)
00186  *
00187  * \param *handle Pointer to CoAP library handle
00188  *
00189  * \brief If re-transmissions are enabled, this function removes all messages from the retransmission queue.
00190  */
00191 extern void sn_coap_protocol_clear_retransmission_buffer(struct coap_s *handle);
00192 
00193 /**
00194  * \fn sn_coap_protocol_block_remove
00195  *
00196  * \brief Remove saved block data. Can be used to remove the data from RAM to enable storing it to other place.
00197  *
00198  * \param handle Pointer to CoAP library handle
00199  * \param source_address Addres from where the block has been received.
00200  * \param payload_length Length of the coap payload of the block.
00201  * \param payload Coap payload of the block.
00202  *
00203  */
00204 extern void sn_coap_protocol_block_remove(struct coap_s *handle, sn_nsdl_addr_s *source_address, uint16_t payload_length, void *payload);
00205 
00206 /**
00207  * \fn sn_coap_protocol_remove_sent_blockwise_message
00208  *
00209  * \brief Remove sent blockwise message from the linked list.
00210  *
00211  * \param handle Pointer to CoAP library handle
00212  * \param message_id Message id to be removed.
00213  *
00214  */
00215 extern void sn_coap_protocol_remove_sent_blockwise_message(struct coap_s *handle, uint16_t message_id);
00216 
00217 /**
00218  * \fn void sn_coap_protocol_delete_retransmission(struct coap_s *handle)
00219  *
00220  * \param *handle Pointer to CoAP library handle
00221  * \msg_id message ID to be removed
00222  * \return returns 0 when success, -1 for invalid parameter, -2 if message was not found
00223  *
00224  * \brief If re-transmissions are enabled, this function removes message from retransmission buffer.
00225  */
00226 extern int8_t sn_coap_protocol_delete_retransmission(struct coap_s *handle, uint16_t msg_id);
00227 
00228 /**
00229  * \fn void sn_coap_protocol_delete_retransmission_by_token(struct coap_s *handle)
00230  *
00231  * \param *handle Pointer to CoAP library handle
00232  * \token Token to be removed
00233  * \token_len Length of the token
00234  * \return returns 0 when success, -1 for invalid parameter, -2 if message was not found
00235  *
00236  * \brief If re-transmissions are enabled, this function removes message from retransmission buffer.
00237  */
00238 extern int8_t sn_coap_protocol_delete_retransmission_by_token(struct coap_s *handle, const uint8_t *token, uint8_t token_len);
00239 
00240 /**
00241  * \fn int8_t sn_coap_convert_block_size(uint16_t block_size)
00242  *
00243  * \brief Utility function to convert block size.
00244  *
00245  * \param block_size Block size to convert.
00246  *
00247  * \return Value of range 0 - 6
00248  */
00249 extern int8_t sn_coap_convert_block_size(uint16_t block_size);
00250 
00251 /**
00252  * \fn int8_t sn_coap_protocol_handle_block2_response_internally(struct coap_s *handle, uint8_t handle_response)
00253  *
00254  * \brief This function change the state whether CoAP library sends the block 2 response automatically or not.
00255  *
00256  * \param *handle Pointer to CoAP library handle
00257  * \param handle_response 1 if CoAP library handles the response sending otherwise 0.
00258  *
00259  * \return  0 = success, -1 = failure
00260  */
00261 extern int8_t sn_coap_protocol_handle_block2_response_internally(struct coap_s *handle, uint8_t handle_response);
00262 
00263 /**
00264  * \fn void sn_coap_protocol_clear_sent_blockwise_messages(struct coap_s *handle)
00265  *
00266  * \brief This function clears all the sent blockwise messages from the linked list.
00267  *
00268  * \param *handle Pointer to CoAP library handle
00269  */
00270 extern void sn_coap_protocol_clear_sent_blockwise_messages(struct coap_s *handle);
00271 
00272 /**
00273  * \fn void sn_coap_protocol_clear_received_blockwise_messages(struct coap_s *handle)
00274  *
00275  * \brief This function clears all the received blockwise messages from the linked list.
00276  *
00277  * \param *handle Pointer to CoAP library handle
00278  */
00279 extern void sn_coap_protocol_clear_received_blockwise_messages(struct coap_s *handle);
00280 
00281 /**
00282  * \fn void sn_coap_protocol_send_rst(struct coap_s *handle, uint16_t msg_id, sn_nsdl_addr_s *addr_ptr, void *param)
00283  *
00284  * \brief This function sends a RESET message.
00285  *
00286  * \param *handle Pointer to CoAP library handle
00287  * \param msg_id Message id.
00288  * \param addr_ptr Pointer to destination address where CoAP message will be sent
00289  * \param param Pointer that will be passed to tx function callback
00290  */
00291 extern void sn_coap_protocol_send_rst(struct coap_s *handle, uint16_t msg_id, sn_nsdl_addr_s *addr_ptr, void *param);
00292 
00293 /**
00294  * \fn uint16_t sn_coap_protocol_get_configured_blockwise_size(struct coap_s *handle)
00295  *
00296  * \brief Get configured CoAP payload blockwise size
00297  *
00298  * \param *handle Pointer to CoAP library handle
00299  */
00300 extern uint16_t sn_coap_protocol_get_configured_blockwise_size(struct coap_s *handle);
00301 
00302 /**
00303  * \fn void sn_coap_protocol_linked_list_duplication_info_remove(struct coap_s *handle, const uint8_t *src_addr_ptr, const uint16_t port, const uint16_t msg_id);
00304  *
00305  * \brief Removes stored Duplication info from Linked list.
00306  *
00307  * \param *handle Pointer to CoAP library handle
00308  * \param *addr_ptr is pointer to Address key to be removed
00309  * \param port is Port key to be removed
00310  * \param msg_id is Message ID key to be removed
00311  */
00312 extern void sn_coap_protocol_linked_list_duplication_info_remove(struct coap_s *handle,
00313                                                                  const uint8_t *src_addr_ptr,
00314                                                                  const uint16_t port,
00315                                                                  const uint16_t msg_id);
00316 
00317 #endif /* SN_COAP_PROTOCOL_H_ */
00318 
00319 #ifdef __cplusplus
00320 }
00321 #endif