ftp_client.h
Go to the documentation of this file.
1 /**
2  * @file ftp_client.h
3  * @brief FTP client (File Transfer Protocol)
4  *
5  * @section License
6  *
7  * SPDX-License-Identifier: GPL-2.0-or-later
8  *
9  * Copyright (C) 2010-2024 Oryx Embedded SARL. All rights reserved.
10  *
11  * This file is part of CycloneTCP Open.
12  *
13  * This program is free software; you can redistribute it and/or
14  * modify it under the terms of the GNU General Public License
15  * as published by the Free Software Foundation; either version 2
16  * of the License, or (at your option) any later version.
17  *
18  * This program is distributed in the hope that it will be useful,
19  * but WITHOUT ANY WARRANTY; without even the implied warranty of
20  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
21  * GNU General Public License for more details.
22  *
23  * You should have received a copy of the GNU General Public License
24  * along with this program; if not, write to the Free Software Foundation,
25  * Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
26  *
27  * @author Oryx Embedded SARL (www.oryx-embedded.com)
28  * @version 2.4.0
29  **/
30 
31 #ifndef _FTP_CLIENT_H
32 #define _FTP_CLIENT_H
33 
34 //Dependencies
35 #include "core/net.h"
36 #include "date_time.h"
37 
38 //FTP client support
39 #ifndef FTP_CLIENT_SUPPORT
40  #define FTP_CLIENT_SUPPORT ENABLED
41 #elif (FTP_CLIENT_SUPPORT != ENABLED && FTP_CLIENT_SUPPORT != DISABLED)
42  #error FTP_CLIENT_SUPPORT parameter is not valid
43 #endif
44 
45 //FTP over TLS
46 #ifndef FTP_CLIENT_TLS_SUPPORT
47  #define FTP_CLIENT_TLS_SUPPORT DISABLED
48 #elif (FTP_CLIENT_TLS_SUPPORT != ENABLED && FTP_CLIENT_TLS_SUPPORT != DISABLED)
49  #error FTP_CLIENT_TLS_SUPPORT parameter is not valid
50 #endif
51 
52 //Default timeout
53 #ifndef FTP_CLIENT_DEFAULT_TIMEOUT
54  #define FTP_CLIENT_DEFAULT_TIMEOUT 20000
55 #elif (FTP_CLIENT_DEFAULT_TIMEOUT < 1000)
56  #error FTP_CLIENT_DEFAULT_TIMEOUT parameter is not valid
57 #endif
58 
59 //Size of the buffer for input/output operations
60 #ifndef FTP_CLIENT_BUFFER_SIZE
61  #define FTP_CLIENT_BUFFER_SIZE 512
62 #elif (FTP_CLIENT_BUFFER_SIZE < 64)
63  #error FTP_CLIENT_BUFFER_SIZE parameter is not valid
64 #endif
65 
66 //Minimum buffer size for TCP sockets
67 #ifndef FTP_CLIENT_MIN_TCP_BUFFER_SIZE
68  #define FTP_CLIENT_MIN_TCP_BUFFER_SIZE 1430
69 #elif (FTP_CLIENT_MIN_TCP_BUFFER_SIZE < 512)
70  #error FTP_CLIENT_MIN_TCP_BUFFER_SIZE parameter is not valid
71 #endif
72 
73 //Maximum buffer size for TCP sockets
74 #ifndef FTP_CLIENT_MAX_TCP_BUFFER_SIZE
75  #define FTP_CLIENT_MAX_TCP_BUFFER_SIZE 2860
76 #elif (FTP_CLIENT_MAX_TCP_BUFFER_SIZE < 512)
77  #error FTP_CLIENT_MAX_TCP_BUFFER_SIZE parameter is not valid
78 #endif
79 
80 //TX buffer size for TLS connections
81 #ifndef FTP_CLIENT_TLS_TX_BUFFER_SIZE
82  #define FTP_CLIENT_TLS_TX_BUFFER_SIZE 2048
83 #elif (FTP_CLIENT_TLS_TX_BUFFER_SIZE < 512)
84  #error FTP_CLIENT_TLS_TX_BUFFER_SIZE parameter is not valid
85 #endif
86 
87 //Minimum RX buffer size for TLS connections
88 #ifndef FTP_CLIENT_MIN_TLS_RX_BUFFER_SIZE
89  #define FTP_CLIENT_MIN_TLS_RX_BUFFER_SIZE 4096
90 #elif (FTP_CLIENT_MIN_TLS_RX_BUFFER_SIZE < 512)
91  #error FTP_CLIENT_MIN_TLS_RX_BUFFER_SIZE parameter is not valid
92 #endif
93 
94 //Maximum RX buffer size for TLS connections
95 #ifndef FTP_CLIENT_MAX_TLS_RX_BUFFER_SIZE
96  #define FTP_CLIENT_MAX_TLS_RX_BUFFER_SIZE 16384
97 #elif (FTP_CLIENT_MAX_TLS_RX_BUFFER_SIZE < 512)
98  #error FTP_CLIENT_MAX_TLS_RX_BUFFER_SIZE parameter is not valid
99 #endif
100 
101 //Maximum length of file names
102 #ifndef FTP_CLIENT_MAX_FILENAME_LEN
103  #define FTP_CLIENT_MAX_FILENAME_LEN 64
104 #elif (FTP_CLIENT_MAX_FILENAME_LEN < 16)
105  #error FTP_CLIENT_MAX_FILENAME_LEN parameter is not valid
106 #endif
107 
108 //Application specific context
109 #ifndef FTP_CLIENT_PRIVATE_CONTEXT
110  #define FTP_CLIENT_PRIVATE_CONTEXT
111 #endif
112 
113 //TLS supported?
114 #if (FTP_CLIENT_TLS_SUPPORT == ENABLED)
115  #include "core/crypto.h"
116  #include "tls.h"
117 #endif
118 
119 //Test macros for FTP response codes
120 #define FTP_REPLY_CODE_1YZ(code) ((code) >= 100 && (code) < 200)
121 #define FTP_REPLY_CODE_2YZ(code) ((code) >= 200 && (code) < 300)
122 #define FTP_REPLY_CODE_3YZ(code) ((code) >= 300 && (code) < 400)
123 #define FTP_REPLY_CODE_4YZ(code) ((code) >= 400 && (code) < 500)
124 #define FTP_REPLY_CODE_5YZ(code) ((code) >= 500 && (code) < 600)
125 
126 //Forward declaration of FtpClientContext structure
127 struct _FtpClientContext;
128 #define FtpClientContext struct _FtpClientContext
129 
130 //C++ guard
131 #ifdef __cplusplus
132 extern "C" {
133 #endif
134 
135 
136 /**
137  * @brief FTP connection modes
138  **/
139 
140 typedef enum
141 {
146  FTP_MODE_PASSIVE = 4
148 
149 
150 /**
151  * @brief File access modes
152  **/
153 
154 typedef enum
155 {
162 
163 
164 /**
165  * @brief Flags used by I/O functions
166  **/
167 
168 typedef enum
169 {
174  FTP_FLAG_DELAY = 0x8000
176 
177 
178 /**
179  * @brief File attributes
180  **/
181 
182 typedef enum
183 {
187 
188 
189 /**
190  * @brief FTP client states
191  */
192 
193 typedef enum
194 {
214 
215 
216 //TLS supported?
217 #if (FTP_CLIENT_TLS_SUPPORT == ENABLED)
218 
219 /**
220  * @brief TLS initialization callback function
221  **/
222 
224  TlsContext *tlsContext);
225 
226 #endif
227 
228 
229 /**
230  * @brief Control or data channel
231  **/
232 
233 typedef struct
234 {
235  Socket *socket; ///<Underlying TCP socket
236 #if (FTP_CLIENT_TLS_SUPPORT == ENABLED)
237  TlsContext *tlsContext; ///<TLS context
238 #endif
240 
241 
242 /**
243  * @brief FTP client context
244  **/
245 
247 {
248  FtpClientState state; ///<FTP client state
249  NetInterface *interface; ///<Underlying network interface
250  systime_t timeout; ///<Timeout value
251  systime_t timestamp; ///<Timestamp to manage timeout
252  IpAddr serverIpAddr; ///<IP address of the FTP server
253  uint16_t serverPort; ///<TCP port number
254  bool_t passiveMode; ///<Passive mode
255 #if (FTP_CLIENT_TLS_SUPPORT == ENABLED)
256  TlsSessionState tlsSession; ///<TLS session state
257  FtpClientTlsInitCallback tlsInitCallback; ///<TLS initialization callback function
258 #endif
259  FtpClientChannel controlChannel; ///<Control channel
260  FtpClientChannel dataChannel; ///<Data channel
261  char_t buffer[FTP_CLIENT_BUFFER_SIZE]; ///<Memory buffer for input/output operations
262  size_t bufferPos; ///<Current position in the buffer
263  size_t commandLen; ///<Length of the FTP command, in bytes
264  size_t replyLen; ///<Length of the FTP reply, in bytes
265  uint_t replyCode; ///<FTP reply code
266  FTP_CLIENT_PRIVATE_CONTEXT ///<Application specific context
267 };
268 
269 
270 /**
271  * @brief Directory entry
272  **/
273 
274 typedef struct
275 {
277  uint32_t attributes;
278  uint32_t size;
280 } FtpDirEntry;
281 
282 
283 //FTP client related functions
285 
286 #if (FTP_CLIENT_TLS_SUPPORT == ENABLED)
287 
289  FtpClientTlsInitCallback callback);
290 
291 #endif
292 
294 
296  NetInterface *interface);
297 
299  const IpAddr *serverIpAddr, uint16_t serverPort, uint_t mode);
300 
301 error_t ftpClientLogin(FtpClientContext *context, const char_t *username,
302  const char_t *password);
303 
304 error_t ftpClientLoginEx(FtpClientContext *context, const char_t *username,
305  const char_t *password, const char_t *account);
306 
308  size_t maxLen);
309 
311  const char_t *path);
312 
314 
315 error_t ftpClientOpenDir(FtpClientContext *context, const char_t *path);
318 
319 error_t ftpClientCreateDir(FtpClientContext *context, const char_t *path);
320 error_t ftpClientDeleteDir(FtpClientContext *context, const char_t *path);
321 
322 error_t ftpClientOpenFile(FtpClientContext *context, const char_t *path,
323  uint_t mode);
324 
325 error_t ftpClientWriteFile(FtpClientContext *context, const void *data,
326  size_t length, size_t *written, uint_t flags);
327 
328 error_t ftpClientReadFile(FtpClientContext *context, void *data, size_t size,
329  size_t *received, uint_t flags);
330 
332 
333 error_t ftpClientRenameFile(FtpClientContext *context, const char_t *oldPath,
334  const char_t *newPath);
335 
336 error_t ftpClientDeleteFile(FtpClientContext *context, const char_t *path);
337 
339 
342 
343 void ftpClientDeinit(FtpClientContext *context);
344 
345 //C++ guard
346 #ifdef __cplusplus
347 }
348 #endif
349 
350 #endif
unsigned int uint_t
Definition: compiler_port.h:50
char char_t
Definition: compiler_port.h:48
int bool_t
Definition: compiler_port.h:53
General definitions for cryptographic algorithms.
Date and time management.
error_t
Error codes.
Definition: error.h:43
uint8_t data[]
Definition: ethernet.h:222
error_t ftpClientCloseFile(FtpClientContext *context)
Close file.
Definition: ftp_client.c:1436
error_t ftpClientClose(FtpClientContext *context)
Close the connection with the FTP server.
Definition: ftp_client.c:1749
error_t ftpClientConnect(FtpClientContext *context, const IpAddr *serverIpAddr, uint16_t serverPort, uint_t mode)
Establish a connection with the specified FTP server.
Definition: ftp_client.c:170
error_t ftpClientLogin(FtpClientContext *context, const char_t *username, const char_t *password)
Login to the FTP server using the provided user name and password.
Definition: ftp_client.c:375
FtpClientState
FTP client states.
Definition: ftp_client.h:194
@ FTP_CLIENT_STATE_READING_DATA
Definition: ftp_client.h:210
@ FTP_CLIENT_STATE_WRITING_DATA
Definition: ftp_client.h:209
@ FTP_CLIENT_STATE_SUB_COMMAND_7
Definition: ftp_client.h:206
@ FTP_CLIENT_STATE_SUB_COMMAND_3
Definition: ftp_client.h:202
@ FTP_CLIENT_STATE_SUB_COMMAND_5
Definition: ftp_client.h:204
@ FTP_CLIENT_STATE_CONNECTING_TCP
Definition: ftp_client.h:197
@ FTP_CLIENT_STATE_SUB_COMMAND_2
Definition: ftp_client.h:201
@ FTP_CLIENT_STATE_CONNECTED
Definition: ftp_client.h:199
@ FTP_CLIENT_STATE_SUB_COMMAND_9
Definition: ftp_client.h:208
@ FTP_CLIENT_STATE_SUB_COMMAND_6
Definition: ftp_client.h:205
@ FTP_CLIENT_STATE_SUB_COMMAND_8
Definition: ftp_client.h:207
@ FTP_CLIENT_STATE_DISCONNECTING_1
Definition: ftp_client.h:211
@ FTP_CLIENT_STATE_SUB_COMMAND_4
Definition: ftp_client.h:203
@ FTP_CLIENT_STATE_DISCONNECTING_2
Definition: ftp_client.h:212
@ FTP_CLIENT_STATE_SUB_COMMAND_1
Definition: ftp_client.h:200
@ FTP_CLIENT_STATE_CONNECTING_TLS
Definition: ftp_client.h:198
@ FTP_CLIENT_STATE_ACCEPTING_TCP
Definition: ftp_client.h:196
@ FTP_CLIENT_STATE_DISCONNECTED
Definition: ftp_client.h:195
error_t ftpClientRegisterTlsInitCallback(FtpClientContext *context, FtpClientTlsInitCallback callback)
Register TLS initialization callback function.
Definition: ftp_client.c:101
error_t ftpClientGetWorkingDir(FtpClientContext *context, char_t *path, size_t maxLen)
Get current working directory.
Definition: ftp_client.c:542
error_t ftpClientReadFile(FtpClientContext *context, void *data, size_t size, size_t *received, uint_t flags)
Read from a remote file.
Definition: ftp_client.c:1387
#define FtpClientContext
Definition: ftp_client.h:128
#define FTP_CLIENT_MAX_FILENAME_LEN
Definition: ftp_client.h:103
error_t ftpClientLoginEx(FtpClientContext *context, const char_t *username, const char_t *password, const char_t *account)
Login to the FTP server using user name, password and account.
Definition: ftp_client.c:392
error_t ftpClientOpenFile(FtpClientContext *context, const char_t *path, uint_t mode)
Open a file for reading, writing, or appending.
Definition: ftp_client.c:1162
#define FTP_CLIENT_PRIVATE_CONTEXT
Definition: ftp_client.h:110
error_t ftpClientChangeToParentDir(FtpClientContext *context)
Change to parent directory.
Definition: ftp_client.c:696
error_t ftpClientDeleteDir(FtpClientContext *context, const char_t *path)
Remove a directory.
Definition: ftp_client.c:1087
error_t ftpClientReadDir(FtpClientContext *context, FtpDirEntry *dirEntry)
Read an entry from the directory.
Definition: ftp_client.c:900
#define FTP_CLIENT_BUFFER_SIZE
Definition: ftp_client.h:61
FtpFileAttributes
File attributes.
Definition: ftp_client.h:183
@ FTP_FILE_ATTR_READ_ONLY
Definition: ftp_client.h:185
@ FTP_FILE_ATTR_DIRECTORY
Definition: ftp_client.h:184
error_t ftpClientInit(FtpClientContext *context)
Initialize FTP client context.
Definition: ftp_client.c:61
error_t ftpClientCloseDir(FtpClientContext *context)
Close directory.
Definition: ftp_client.c:995
FtpFileFlags
Flags used by I/O functions.
Definition: ftp_client.h:169
@ FTP_FLAG_WAIT_ALL
Definition: ftp_client.h:170
@ FTP_FLAG_BREAK_CRLF
Definition: ftp_client.h:172
@ FTP_FLAG_DELAY
Definition: ftp_client.h:174
@ FTP_FLAG_BREAK_CHAR
Definition: ftp_client.h:171
@ FTP_FLAG_NO_DELAY
Definition: ftp_client.h:173
error_t ftpClientDeleteFile(FtpClientContext *context, const char_t *path)
Delete a file.
Definition: ftp_client.c:1560
error_t ftpClientCreateDir(FtpClientContext *context, const char_t *path)
Create a new directory.
Definition: ftp_client.c:1013
error_t ftpClientOpenDir(FtpClientContext *context, const char_t *path)
Open a directory.
Definition: ftp_client.c:770
error_t ftpClientChangeWorkingDir(FtpClientContext *context, const char_t *path)
Change working directory.
Definition: ftp_client.c:622
error_t ftpClientBindToInterface(FtpClientContext *context, NetInterface *interface)
Bind the FTP client to a particular network interface.
Definition: ftp_client.c:146
error_t(* FtpClientTlsInitCallback)(FtpClientContext *context, TlsContext *tlsContext)
TLS initialization callback function.
Definition: ftp_client.h:223
FtpConnectionModes
FTP connection modes.
Definition: ftp_client.h:141
@ FTP_MODE_ACTIVE
Definition: ftp_client.h:145
@ FTP_MODE_PLAINTEXT
Definition: ftp_client.h:142
@ FTP_MODE_IMPLICIT_TLS
Definition: ftp_client.h:143
@ FTP_MODE_EXPLICIT_TLS
Definition: ftp_client.h:144
@ FTP_MODE_PASSIVE
Definition: ftp_client.h:146
error_t ftpClientDisconnect(FtpClientContext *context)
Gracefully disconnect from the FTP server.
Definition: ftp_client.c:1660
void ftpClientDeinit(FtpClientContext *context)
Release FTP client context.
Definition: ftp_client.c:1772
error_t ftpClientWriteFile(FtpClientContext *context, const void *data, size_t length, size_t *written, uint_t flags)
Write to a remote file.
Definition: ftp_client.c:1320
FtpFileModes
File access modes.
Definition: ftp_client.h:155
@ FTP_FILE_MODE_TEXT
Definition: ftp_client.h:160
@ FTP_FILE_MODE_BINARY
Definition: ftp_client.h:159
@ FTP_FILE_MODE_READ
Definition: ftp_client.h:156
@ FTP_FILE_MODE_APPEND
Definition: ftp_client.h:158
@ FTP_FILE_MODE_WRITE
Definition: ftp_client.h:157
uint_t ftpClientGetReplyCode(FtpClientContext *context)
Retrieve server's reply code.
Definition: ftp_client.c:1633
error_t ftpClientRenameFile(FtpClientContext *context, const char_t *oldPath, const char_t *newPath)
Rename a file.
Definition: ftp_client.c:1455
error_t ftpClientSetTimeout(FtpClientContext *context, systime_t timeout)
Set communication timeout.
Definition: ftp_client.c:125
TCP/IP stack core.
#define NetInterface
Definition: net.h:36
uint32_t systime_t
System time.
char_t name[]
#define Socket
Definition: socket.h:36
FTP client context.
Definition: ftp_client.h:247
size_t commandLen
Length of the FTP command, in bytes.
Definition: ftp_client.h:263
FtpClientTlsInitCallback tlsInitCallback
TLS initialization callback function.
Definition: ftp_client.h:257
systime_t timestamp
Timestamp to manage timeout.
Definition: ftp_client.h:251
FtpClientState state
FTP client state.
Definition: ftp_client.h:248
char_t buffer[FTP_CLIENT_BUFFER_SIZE]
Memory buffer for input/output operations.
Definition: ftp_client.h:261
size_t bufferPos
Current position in the buffer.
Definition: ftp_client.h:262
FtpClientChannel controlChannel
Control channel.
Definition: ftp_client.h:259
FtpClientChannel dataChannel
Data channel.
Definition: ftp_client.h:260
IpAddr serverIpAddr
IP address of the FTP server.
Definition: ftp_client.h:252
uint16_t serverPort
TCP port number.
Definition: ftp_client.h:253
size_t replyLen
Length of the FTP reply, in bytes.
Definition: ftp_client.h:264
uint_t replyCode
FTP reply code.
Definition: ftp_client.h:265
systime_t timeout
Timeout value.
Definition: ftp_client.h:250
TlsSessionState tlsSession
TLS session state.
Definition: ftp_client.h:256
bool_t passiveMode
Passive mode.
Definition: ftp_client.h:254
NetInterface * interface
Underlying network interface.
Definition: ftp_client.h:249
Date and time representation.
Definition: date_time.h:47
Control or data channel.
Definition: ftp_client.h:234
TlsContext * tlsContext
TLS context.
Definition: ftp_client.h:237
Socket * socket
Underlying TCP socket.
Definition: ftp_client.h:235
Directory entry.
Definition: ftp_client.h:275
uint32_t attributes
Definition: ftp_client.h:277
uint32_t size
Definition: ftp_client.h:278
DateTime modified
Definition: ftp_client.h:279
IP network address.
Definition: ip.h:79
TLS session state.
Definition: tls.h:2021
uint8_t length
Definition: tcp.h:368
uint8_t flags
Definition: tcp.h:351
TLS (Transport Layer Security)
#define TlsContext
Definition: tls.h:36