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 : /** @} */
|
