diff options
Diffstat (limited to 'thirdparty/nRF5_SDK_15.0.0_a53641a/components/iot/ipv6_stack/tftp/iot_tftp.h')
| -rw-r--r-- | thirdparty/nRF5_SDK_15.0.0_a53641a/components/iot/ipv6_stack/tftp/iot_tftp.h | 245 |
1 files changed, 245 insertions, 0 deletions
diff --git a/thirdparty/nRF5_SDK_15.0.0_a53641a/components/iot/ipv6_stack/tftp/iot_tftp.h b/thirdparty/nRF5_SDK_15.0.0_a53641a/components/iot/ipv6_stack/tftp/iot_tftp.h new file mode 100644 index 0000000..0405af2 --- /dev/null +++ b/thirdparty/nRF5_SDK_15.0.0_a53641a/components/iot/ipv6_stack/tftp/iot_tftp.h @@ -0,0 +1,245 @@ +/** + * Copyright (c) 2015 - 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 iot_tftp.h + * + * @defgroup iot_tftp TFTP Application Interface for Nordic's IPv6 stack + * @ingroup iot_sdk_stack + * @{ + * @brief Trivial File Transfer Protocol module provides implementation of TFTP Client. + * + */ + +#ifndef IOT_TFTP_H__ +#define IOT_TFTP_H__ + +#include "sdk_common.h" +#include "iot_common.h" +#include "iot_timer.h" +#include "iot_file.h" +#include "iot_defines.h" + +#ifdef __cplusplus +extern "C" { +#endif + +/**@brief TFTP global instance number. */ +typedef uint32_t iot_tftp_t; + +/**@brief TFTP module Events. */ +typedef enum +{ + IOT_TFTP_EVT_ERROR, /**< Event code indicating that an error occurred. */ + IOT_TFTP_EVT_TRANSFER_DATA_RECEIVED, /**< Event code indicating that a data packet was received during read transfer. */ + IOT_TFTP_EVT_TRANSFER_GET_COMPLETE, /**< Event code indicating that transfer read was completed. */ + IOT_TFTP_EVT_TRANSFER_PUT_COMPLETE, /**< Event code indicating that transfer write was completed. */ +} iot_tftp_evt_id_t; + +/**@brief TFTP error event structure. */ +typedef struct +{ + uint32_t code; /**< Error code. */ + char * p_msg; /**< Message describing the reason or NULL if no description is available. */ + uint32_t size_transfered; /**< In case of an error, variable indicates a number of successfully read or write bytes. */ +} iot_tftp_evt_err_t; + +/**@brief TFTP data received event structure. */ +typedef struct +{ + uint8_t * p_data; /**< Pointer to received data chunk. */ + uint16_t size; /**< Size of received data chunk. */ +} iot_tftp_evt_data_received_t; + +/**@brief TFTP event structure. */ +typedef union +{ + iot_tftp_evt_err_t err; /**< Error event structure. Used only in case of IOT_TFTP_EVT_ERROR error. */ + iot_tftp_evt_data_received_t data_received; /**< Data received event structure. Used only in case of IOT_TFTP_EVT_TRANSFER_DATA_RECEIVED event. */ +} iot_tftp_evt_param_t; + +/**@brief Asynchronous event type. */ +typedef struct +{ + iot_tftp_evt_id_t id; /**< Event code. */ + iot_tftp_evt_param_t param; /**< Union to structures describing event. */ + iot_file_t * p_file; /**< File associated with TFTP transfer. */ +} iot_tftp_evt_t; + +/**@brief TFTP Transmission initialization structure (both GET and PUT). */ +typedef struct +{ + uint32_t next_retr; /**< Number of seconds between retransmissions. */ + uint16_t block_size; /**< Maximum or negotiated size of data block. */ +} iot_tftp_trans_params_t; + +/**@brief User callback from TFTP module. + * + * @note TFTP module user callback will be invoked even if user asks TFTP to abort (TFTP error event). + * + * @param[in] p_tftp Pointer to the TFTP instance. + * @param[in] p_evt Pointer to the TFTP event structure, describing reason. + * + * @retval None. + */ +typedef void (*iot_tftp_callback_t)(iot_tftp_t * p_tftp, iot_tftp_evt_t * p_evt); + + +/**@brief TFTP initialization structure. */ +typedef struct +{ + ipv6_addr_t * p_ipv6_addr; /**< IPv6 address of the server. */ + uint16_t src_port; /**< Source port (local UDP port) from which all request and data will be sent. Should be choosen randomly. */ + uint16_t dst_port; /**< Destination port - UDP port on which server listens for new connections. */ + iot_tftp_callback_t callback; /**< Reference to the user callback. */ + const char * p_password; /**< Server password for all requests. Shall be NULL if no password is required. */ +} iot_tftp_init_t; + + +/**@brief Initializes TFTP client. + * + * @param[in] p_tftp Pointer to the TFTP instance. Should not be NULL. + * @param[in] p_init_params Initialization structure for TFTP client. Should not be NULL. + * + * @retval NRF_SUCCESS on successful execution of procedure, else an error code indicating reason + * for failure. + */ +uint32_t iot_tftp_init(iot_tftp_t * p_tftp, iot_tftp_init_t * p_init_params); + + +/**@brief Function used in order to change initial connection parameters. + * + * @param[in] p_tftp Reference to the TFTP instance. + * @param[in] p_params Pointer to transmission parameters structure. Should not be NULL. + * + * @retval NRF_SUCCESS if parameters successfully set, else an error code indicating reason + * for failure. + */ +uint32_t iot_tftp_set_params(iot_tftp_t * p_tftp, iot_tftp_trans_params_t * p_params); + + +/**@brief Retrieves file from remote server into p_file. + * + * If @p p_file is a NULL pointer, the content of received file can be retrieved by handling + * @ref IOT_TFTP_EVT_TRANSFER_DATA_RECEIVED event. This event is generated each time a data + * packet (containing a chunk of requested file) is received. + * IOT_TFTP_EVT_TRANSFER_GET_COMPLETE event is generated after download is complete. + * + * @note This function should not be called until previous download operation is completed. + * + * @param[in] p_tftp Pointer to the TFTP instance. + * @param[in] p_file Reference to the file from which data should be read. + * @param[in] p_path Path of the requested file on the remote server. Shall not be NULL. + * + * @retval NRF_SUCCESS on successful execution of procedure, else an error code indicating reason + * for failure. + */ +uint32_t iot_tftp_get(iot_tftp_t * p_tftp, iot_file_t * p_file, const char * p_path); + + +/**@brief Sends local file p_file to a remote server. + * + * @param[in] p_tftp Pointer to the TFTP instance. + * @param[in] p_file Reference to the file to which data should be stored. Should not be NULL. + * @param[in] p_path Path of the file on the remote server. Shall not be NULL. + * + * @retval NRF_SUCCESS on successful execution of procedure, else an error code indicating reason + * for failure. + */ +uint32_t iot_tftp_put(iot_tftp_t * p_tftp, iot_file_t * p_file, const char * p_path); + + +/**@brief Holds transmission of ACK (use in order to slow transmission). + * + * @param[in] p_tftp Pointer to the TFTP instance. + * + * @retval NRF_SUCCESS on successful execution of procedure, else an error code indicating reason + * for failure. + */ +uint32_t iot_tftp_hold(iot_tftp_t * p_tftp); + + +/**@brief Resumes transmission. + * + * @param[in] p_tftp Pointer to the TFTP instance. + * + * @retval NRF_SUCCESS on successful execution of procedure, else an error code indicating reason + * for failure. + */ +uint32_t iot_tftp_resume(iot_tftp_t * p_tftp); + + +/**@brief Resets TFTP client instance, so it is possible to make another request after error. + * + * @param[in] p_tftp Pointer to the TFTP instance. + * + * @retval NRF_SUCCESS on successful execution of procedure, else an error code indicating reason + * for failure. + */ +uint32_t iot_tftp_abort(iot_tftp_t * p_tftp); + + +/**@brief Frees assigned sockets. + * + * @param[in] p_tftp Pointer to the TFTP instance. + * + * @retval NRF_SUCCESS on successful execution of procedure, else an error code indicating reason + * for failure. + */ +uint32_t iot_tftp_uninit(iot_tftp_t * p_tftp); + + +/**@brief Function for performing retransmissions of TFTP acknowledgments. + * + * @note TFTP module implements the retransmission mechanism by invoking this function periodically. + * So that method has to be added to IoT Timer client list and has to be called with minimum of + * TFTP_RETRANSMISSION_INTERVAL resolution. + * + * @param[in] wall_clock_value The value of the wall clock that triggered the callback. + * + * @retval None. + */ +void iot_tftp_timeout_process(iot_timer_time_in_ms_t wall_clock_value); + +#ifdef __cplusplus +} +#endif + +#endif // IOT_TFTP_H__ + +/** @} */ |