Line data Source code
1 1 : /* 2 : * Copyright (c) 2020 InnBlue 3 : * 4 : * SPDX-License-Identifier: Apache-2.0 5 : */ 6 : 7 : /** @file tftp.h 8 : * 9 : * @brief TFTP Client Implementation 10 : * 11 : * @defgroup tftp_client TFTP Client library 12 : * @since 2.3 13 : * @version 0.1.0 14 : * @ingroup networking 15 : * @{ 16 : */ 17 : 18 : #ifndef ZEPHYR_INCLUDE_NET_TFTP_H_ 19 : #define ZEPHYR_INCLUDE_NET_TFTP_H_ 20 : 21 : #include <zephyr/kernel.h> 22 : #include <zephyr/net/socket.h> 23 : 24 : #ifdef __cplusplus 25 : extern "C" { 26 : #endif 27 : 28 : /** 29 : * RFC1350: the file is sent in fixed length blocks of 512 bytes. 30 : * Each data packet contains one block of data, and must be acknowledged 31 : * by an acknowledgment packet before the next packet can be sent. 32 : * A data packet of less than 512 bytes signals termination of a transfer. 33 : */ 34 1 : #define TFTP_BLOCK_SIZE 512 35 : 36 : /** 37 : * RFC1350: For non-request TFTP message, the header contains 2-byte operation 38 : * code plus 2-byte block number or error code. 39 : */ 40 1 : #define TFTP_HEADER_SIZE 4 41 : 42 : /** Maximum amount of data that can be sent or received */ 43 1 : #define TFTPC_MAX_BUF_SIZE (TFTP_BLOCK_SIZE + TFTP_HEADER_SIZE) 44 : 45 : /** 46 : * @name TFTP client error codes. 47 : * @{ 48 : */ 49 1 : #define TFTPC_SUCCESS 0 /**< Success. */ 50 1 : #define TFTPC_DUPLICATE_DATA -1 /**< Duplicate data received. */ 51 1 : #define TFTPC_BUFFER_OVERFLOW -2 /**< User buffer is too small. */ 52 1 : #define TFTPC_UNKNOWN_FAILURE -3 /**< Unknown failure. */ 53 1 : #define TFTPC_REMOTE_ERROR -4 /**< Remote server error. */ 54 1 : #define TFTPC_RETRIES_EXHAUSTED -5 /**< Retries exhausted. */ 55 : /** 56 : * @} 57 : */ 58 : 59 : /** 60 : * @brief TFTP Asynchronous Events notified to the application from the module 61 : * through the callback registered by the application. 62 : */ 63 1 : enum tftp_evt_type { 64 : /** 65 : * DATA event when data is received from remote server. 66 : * 67 : * @note DATA event structure contains payload data and size. 68 : */ 69 : TFTP_EVT_DATA, 70 : 71 : /** 72 : * ERROR event when error is received from remote server. 73 : * 74 : * @note ERROR event structure contains error code and message. 75 : */ 76 : TFTP_EVT_ERROR 77 : }; 78 : 79 : /** @brief Parameters for data event. */ 80 1 : struct tftp_data_param { 81 1 : uint8_t *data_ptr; /**< Pointer to binary data. */ 82 1 : uint32_t len; /**< Length of binary data. */ 83 : }; 84 : 85 : /** @brief Parameters for error event. */ 86 1 : struct tftp_error_param { 87 1 : char *msg; /**< Error message. */ 88 1 : int code; /**< Error code. */ 89 : }; 90 : 91 : /** 92 : * @brief Defines event parameters notified along with asynchronous events 93 : * to the application. 94 : */ 95 1 : union tftp_evt_param { 96 : /** Parameters accompanying TFTP_EVT_DATA event. */ 97 1 : struct tftp_data_param data; 98 : 99 : /** Parameters accompanying TFTP_EVT_ERROR event. */ 100 1 : struct tftp_error_param error; 101 : }; 102 : 103 : /** @brief Defines TFTP asynchronous event notified to the application. */ 104 1 : struct tftp_evt { 105 : /** Identifies the event. */ 106 1 : enum tftp_evt_type type; 107 : 108 : /** Contains parameters (if any) accompanying the event. */ 109 1 : union tftp_evt_param param; 110 : }; 111 : 112 : /** 113 : * @typedef tftp_callback_t 114 : * 115 : * @brief TFTP event notification callback registered by the application. 116 : * 117 : * @param[in] evt Event description along with result and associated 118 : * parameters (if any). 119 : */ 120 1 : typedef void (*tftp_callback_t)(const struct tftp_evt *evt); 121 : 122 : /** 123 : * @brief TFTP client definition to maintain information relevant to the 124 : * client. 125 : * 126 : * @note Application must initialize `server` and `callback` before calling 127 : * GET or PUT API with the `tftpc` structure. 128 : */ 129 1 : struct tftpc { 130 : /** Socket address pointing to the remote TFTP server */ 131 1 : struct sockaddr server; 132 : 133 : /** Event notification callback. No notification if NULL */ 134 1 : tftp_callback_t callback; 135 : 136 : /** Buffer for internal usage */ 137 1 : uint8_t tftp_buf[TFTPC_MAX_BUF_SIZE]; 138 : }; 139 : 140 : /** 141 : * @brief This function gets data from a "file" on the remote server. 142 : * 143 : * @param client Client information of type @ref tftpc. 144 : * @param remote_file Name of the remote file to get. 145 : * @param mode TFTP Client "mode" setting. 146 : * 147 : * @retval The size of data being received if the operation completed successfully. 148 : * @retval TFTPC_BUFFER_OVERFLOW if the file is larger than the user buffer. 149 : * @retval TFTPC_REMOTE_ERROR if the server failed to process our request. 150 : * @retval TFTPC_RETRIES_EXHAUSTED if the client timed out waiting for server. 151 : * @retval -EINVAL if `client` is NULL. 152 : * 153 : * @note This function blocks until the transfer is completed or network error happens. The 154 : * integrity of the `client` structure must be ensured until the function returns. 155 : */ 156 1 : int tftp_get(struct tftpc *client, 157 : const char *remote_file, const char *mode); 158 : 159 : /** 160 : * @brief This function puts data to a "file" on the remote server. 161 : * 162 : * @param client Client information of type @ref tftpc. 163 : * @param remote_file Name of the remote file to put. 164 : * @param mode TFTP Client "mode" setting. 165 : * @param user_buf Data buffer containing the data to put. 166 : * @param user_buf_size Length of the data to put. 167 : * 168 : * @retval The size of data being sent if the operation completed successfully. 169 : * @retval TFTPC_REMOTE_ERROR if the server failed to process our request. 170 : * @retval TFTPC_RETRIES_EXHAUSTED if the client timed out waiting for server. 171 : * @retval -EINVAL if `client` or `user_buf` is NULL or if `user_buf_size` is zero. 172 : * 173 : * @note This function blocks until the transfer is completed or network error happens. The 174 : * integrity of the `client` structure must be ensured until the function returns. 175 : */ 176 1 : int tftp_put(struct tftpc *client, 177 : const char *remote_file, const char *mode, 178 : const uint8_t *user_buf, uint32_t user_buf_size); 179 : 180 : #ifdef __cplusplus 181 : } 182 : #endif 183 : 184 : #endif /* ZEPHYR_INCLUDE_NET_TFTP_H_ */ 185 : 186 : /** @} */
