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-2019 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 1.9.6
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 //TLS supported?
109 #if (FTP_CLIENT_TLS_SUPPORT == ENABLED)
110  #include "core/crypto.h"
111  #include "tls.h"
112 #endif
113 
114 //Test macros for FTP response codes
115 #define FTP_REPLY_CODE_1YZ(code) ((code) >= 100 && (code) < 200)
116 #define FTP_REPLY_CODE_2YZ(code) ((code) >= 200 && (code) < 300)
117 #define FTP_REPLY_CODE_3YZ(code) ((code) >= 300 && (code) < 400)
118 #define FTP_REPLY_CODE_4YZ(code) ((code) >= 400 && (code) < 500)
119 #define FTP_REPLY_CODE_5YZ(code) ((code) >= 500 && (code) < 600)
120 
121 //Forward declaration of FtpClientContext structure
122 struct _FtpClientContext;
123 #define FtpClientContext struct _FtpClientContext
124 
125 //C++ guard
126 #ifdef __cplusplus
127 extern "C" {
128 #endif
129 
130 
131 /**
132  * @brief FTP connection modes
133  **/
134 
135 typedef enum
136 {
143 
144 
145 /**
146  * @brief File access modes
147  **/
148 
149 typedef enum
150 {
156 } FtpFileModes;
157 
158 
159 /**
160  * @brief Flags used by I/O functions
161  **/
162 
163 typedef enum
164 {
169  FTP_FLAG_DELAY = 0x8000
170 } FtpFileFlags;
171 
172 
173 /**
174  * @brief File attributes
175  **/
176 
177 typedef enum
178 {
182 
183 
184 /**
185  * @brief FTP client states
186  */
187 
188 typedef enum
189 {
209 
210 
211 //TLS supported?
212 #if (FTP_CLIENT_TLS_SUPPORT == ENABLED)
213 
214 /**
215  * @brief TLS initialization callback function
216  **/
217 
219  TlsContext *tlsContext);
220 
221 #endif
222 
223 
224 /**
225  * @brief Control or data channel
226  **/
227 
228 typedef struct
229 {
230  Socket *socket; ///<Underlying TCP socket
231 #if (FTP_CLIENT_TLS_SUPPORT == ENABLED)
232  TlsContext *tlsContext; ///<TLS context
233 #endif
235 
236 
237 /**
238  * @brief FTP client context
239  **/
240 
242 {
243  FtpClientState state; ///<FTP client state
244  NetInterface *interface; ///<Underlying network interface
245  systime_t timeout; ///<Timeout value
246  systime_t timestamp; ///<Timestamp to manage timeout
247  IpAddr serverIpAddr; ///<IP address of the FTP server
248  uint16_t serverPort; ///<TCP port number
249  bool_t passiveMode; ///<Passive mode
250 #if (FTP_CLIENT_TLS_SUPPORT == ENABLED)
251  TlsSessionState tlsSession; ///<TLS session state
252  FtpClientTlsInitCallback tlsInitCallback; ///<TLS initialization callback function
253 #endif
254  FtpClientChannel controlChannel; ///<Control channel
255  FtpClientChannel dataChannel; ///<Data channel
256  char_t buffer[FTP_CLIENT_BUFFER_SIZE]; ///<Memory buffer for input/output operations
257  size_t bufferPos; ///<Current position in the buffer
258  size_t commandLen; ///<Length of the FTP command, in bytes
259  size_t replyLen; ///<Length of the FTP reply, in bytes
260  uint_t replyCode; ///<FTP reply code
261 };
262 
263 
264 /**
265  * @brief Directory entry
266  **/
267 
268 typedef struct
269 {
271  uint32_t attributes;
272  uint32_t size;
274 } FtpDirEntry;
275 
276 
277 //FTP client related functions
279 
280 #if (FTP_CLIENT_TLS_SUPPORT == ENABLED)
281 
283  FtpClientTlsInitCallback callback);
284 
285 #endif
286 
288 
290  NetInterface *interface);
291 
293  const IpAddr *serverIpAddr, uint16_t serverPort, uint_t mode);
294 
295 error_t ftpClientLogin(FtpClientContext *context, const char_t *username,
296  const char_t *password);
297 
298 error_t ftpClientLoginEx(FtpClientContext *context, const char_t *username,
299  const char_t *password, const char_t *account);
300 
302  size_t maxLen);
303 
305  const char_t *path);
306 
308 
309 error_t ftpClientOpenDir(FtpClientContext *context, const char_t *path);
312 
313 error_t ftpClientCreateDir(FtpClientContext *context, const char_t *path);
314 error_t ftpClientDeleteDir(FtpClientContext *context, const char_t *path);
315 
316 error_t ftpClientOpenFile(FtpClientContext *context, const char_t *path,
317  uint_t mode);
318 
319 error_t ftpClientWriteFile(FtpClientContext *context, const void *data,
320  size_t length, size_t *written, uint_t flags);
321 
322 error_t ftpClientReadFile(FtpClientContext *context, void *data, size_t size,
323  size_t *received, uint_t flags);
324 
326 
327 error_t ftpClientRenameFile(FtpClientContext *context, const char_t *oldPath,
328  const char_t *newPath);
329 
330 error_t ftpClientDeleteFile(FtpClientContext *context, const char_t *path);
331 
333 
336 
337 void ftpClientDeinit(FtpClientContext *context);
338 
339 //C++ guard
340 #ifdef __cplusplus
341 }
342 #endif
343 
344 #endif
TlsContext * tlsContext
TLS context.
Definition: ftp_client.h:232
error_t ftpClientDeleteDir(FtpClientContext *context, const char_t *path)
Remove a directory.
Definition: ftp_client.c:1084
Control or data channel.
Definition: ftp_client.h:228
uint8_t length
Definition: dtls_misc.h:149
Date and time management.
error_t ftpClientChangeWorkingDir(FtpClientContext *context, const char_t *path)
Change working directory.
Definition: ftp_client.c:623
@ FTP_CLIENT_STATE_SUB_COMMAND_2
Definition: ftp_client.h:196
int bool_t
Definition: compiler_port.h:49
@ FTP_FLAG_NO_DELAY
Definition: ftp_client.h:168
bool_t passiveMode
Passive mode.
Definition: ftp_client.h:249
@ FTP_FILE_MODE_APPEND
Definition: ftp_client.h:153
error_t ftpClientRenameFile(FtpClientContext *context, const char_t *oldPath, const char_t *newPath)
Rename a file.
Definition: ftp_client.c:1440
IP network address.
Definition: ip.h:71
#define FTP_CLIENT_BUFFER_SIZE
Definition: ftp_client.h:61
error_t ftpClientCreateDir(FtpClientContext *context, const char_t *path)
Create a new directory.
Definition: ftp_client.c:1010
@ FTP_FLAG_BREAK_CRLF
Definition: ftp_client.h:167
@ FTP_CLIENT_STATE_DISCONNECTING_2
Definition: ftp_client.h:207
@ FTP_FLAG_BREAK_CHAR
Definition: ftp_client.h:166
FtpFileAttributes
File attributes.
Definition: ftp_client.h:177
@ FTP_CLIENT_STATE_DISCONNECTED
Definition: ftp_client.h:190
@ FTP_FILE_MODE_TEXT
Definition: ftp_client.h:155
@ FTP_MODE_IMPLICIT_TLS
Definition: ftp_client.h:138
systime_t timeout
Timeout value.
Definition: ftp_client.h:245
error_t ftpClientGetWorkingDir(FtpClientContext *context, char_t *path, size_t maxLen)
Get current working directory.
Definition: ftp_client.c:543
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:393
char_t name[]
FtpClientState
FTP client states.
Definition: ftp_client.h:188
size_t replyLen
Length of the FTP reply, in bytes.
Definition: ftp_client.h:259
@ FTP_CLIENT_STATE_SUB_COMMAND_4
Definition: ftp_client.h:198
@ FTP_FILE_MODE_READ
Definition: ftp_client.h:151
@ FTP_CLIENT_STATE_WRITING_DATA
Definition: ftp_client.h:204
@ FTP_CLIENT_STATE_CONNECTED
Definition: ftp_client.h:194
FtpConnectionModes
FTP connection modes.
Definition: ftp_client.h:135
@ FTP_CLIENT_STATE_DISCONNECTING_1
Definition: ftp_client.h:206
FtpClientTlsInitCallback tlsInitCallback
TLS initialization callback function.
Definition: ftp_client.h:252
error_t ftpClientSetTimeout(FtpClientContext *context, systime_t timeout)
Set communication timeout.
Definition: ftp_client.c:126
@ FTP_FILE_MODE_BINARY
Definition: ftp_client.h:154
error_t ftpClientRegisterTlsInitCallback(FtpClientContext *context, FtpClientTlsInitCallback callback)
Register TLS initialization callback function.
Definition: ftp_client.c:102
@ FTP_CLIENT_STATE_CONNECTING_TLS
Definition: ftp_client.h:193
@ FTP_MODE_PLAINTEXT
Definition: ftp_client.h:137
#define TlsContext
Definition: tls.h:36
error_t
Error codes.
Definition: error.h:42
error_t ftpClientDeleteFile(FtpClientContext *context, const char_t *path)
Delete a file.
Definition: ftp_client.c:1545
@ FTP_CLIENT_STATE_SUB_COMMAND_8
Definition: ftp_client.h:202
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:376
TlsSessionState tlsSession
TLS session state.
Definition: ftp_client.h:251
error_t ftpClientOpenFile(FtpClientContext *context, const char_t *path, uint_t mode)
Open a file for reading, writing, or appending.
Definition: ftp_client.c:1159
NetInterface * interface
Underlying network interface.
Definition: ftp_client.h:244
#define NetInterface
Definition: net.h:36
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:171
uint_t replyCode
FTP reply code.
Definition: ftp_client.h:260
General definitions for cryptographic algorithms.
void ftpClientDeinit(FtpClientContext *context)
Release FTP client context.
Definition: ftp_client.c:1757
@ FTP_FLAG_WAIT_ALL
Definition: ftp_client.h:165
Date and time representation.
Definition: date_time.h:46
size_t commandLen
Length of the FTP command, in bytes.
Definition: ftp_client.h:258
char_t buffer[FTP_CLIENT_BUFFER_SIZE]
Memory buffer for input/output operations.
Definition: ftp_client.h:256
@ FTP_FLAG_DELAY
Definition: ftp_client.h:169
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:1305
@ FTP_CLIENT_STATE_CONNECTING_TCP
Definition: ftp_client.h:192
@ FTP_MODE_EXPLICIT_TLS
Definition: ftp_client.h:139
@ FTP_CLIENT_STATE_SUB_COMMAND_3
Definition: ftp_client.h:197
@ FTP_CLIENT_STATE_SUB_COMMAND_9
Definition: ftp_client.h:203
DateTime modified
Definition: ftp_client.h:273
#define FTP_CLIENT_MAX_FILENAME_LEN
Definition: ftp_client.h:103
error_t ftpClientReadDir(FtpClientContext *context, FtpDirEntry *dirEntry)
Read an entry from the directory.
Definition: ftp_client.c:897
IpAddr serverIpAddr
IP address of the FTP server.
Definition: ftp_client.h:247
uint8_t flags
Definition: tcp.h:314
char char_t
Definition: compiler_port.h:43
error_t ftpClientDisconnect(FtpClientContext *context)
Gracefully disconnect from the FTP server.
Definition: ftp_client.c:1645
TLS session state.
Definition: tls.h:1834
uint_t ftpClientGetReplyCode(FtpClientContext *context)
Retrieve server's reply code.
Definition: ftp_client.c:1618
@ FTP_FILE_ATTR_DIRECTORY
Definition: ftp_client.h:179
#define FtpClientContext
Definition: ftp_client.h:123
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:1372
#define Socket
Definition: socket.h:36
error_t ftpClientClose(FtpClientContext *context)
Close the connection with the FTP server.
Definition: ftp_client.c:1734
size_t bufferPos
Current position in the buffer.
Definition: ftp_client.h:257
error_t ftpClientChangeToParentDir(FtpClientContext *context)
Change to parent directory.
Definition: ftp_client.c:697
TLS (Transport Layer Security)
@ FTP_MODE_ACTIVE
Definition: ftp_client.h:140
@ FTP_FILE_MODE_WRITE
Definition: ftp_client.h:152
error_t ftpClientInit(FtpClientContext *context)
Initialize FTP client context.
Definition: ftp_client.c:62
@ FTP_FILE_ATTR_READ_ONLY
Definition: ftp_client.h:180
@ FTP_CLIENT_STATE_SUB_COMMAND_1
Definition: ftp_client.h:195
uint8_t mode
Definition: ntp_common.h:149
error_t(* FtpClientTlsInitCallback)(FtpClientContext *context, TlsContext *tlsContext)
TLS initialization callback function.
Definition: ftp_client.h:218
error_t ftpClientCloseFile(FtpClientContext *context)
Close file.
Definition: ftp_client.c:1421
FtpFileFlags
Flags used by I/O functions.
Definition: ftp_client.h:163
uint32_t attributes
Definition: ftp_client.h:271
FtpClientState state
FTP client state.
Definition: ftp_client.h:243
systime_t timestamp
Timestamp to manage timeout.
Definition: ftp_client.h:246
Directory entry.
Definition: ftp_client.h:268
@ FTP_MODE_PASSIVE
Definition: ftp_client.h:141
@ FTP_CLIENT_STATE_READING_DATA
Definition: ftp_client.h:205
error_t ftpClientCloseDir(FtpClientContext *context)
Close directory.
Definition: ftp_client.c:992
@ FTP_CLIENT_STATE_SUB_COMMAND_6
Definition: ftp_client.h:200
unsigned int uint_t
Definition: compiler_port.h:45
TCP/IP stack core.
uint8_t data[]
Definition: dtls_misc.h:176
error_t ftpClientOpenDir(FtpClientContext *context, const char_t *path)
Open a directory.
Definition: ftp_client.c:771
FtpClientChannel controlChannel
Control channel.
Definition: ftp_client.h:254
FTP client context.
Definition: ftp_client.h:241
@ FTP_CLIENT_STATE_SUB_COMMAND_5
Definition: ftp_client.h:199
FtpFileModes
File access modes.
Definition: ftp_client.h:149
error_t ftpClientBindToInterface(FtpClientContext *context, NetInterface *interface)
Bind the FTP client to a particular network interface.
Definition: ftp_client.c:147
uint16_t serverPort
TCP port number.
Definition: ftp_client.h:248
uint32_t systime_t
Definition: compiler_port.h:46
Socket * socket
Underlying TCP socket.
Definition: ftp_client.h:230
uint32_t size
Definition: ftp_client.h:272
@ FTP_CLIENT_STATE_SUB_COMMAND_7
Definition: ftp_client.h:201
@ FTP_CLIENT_STATE_ACCEPTING_TCP
Definition: ftp_client.h:191
FtpClientChannel dataChannel
Data channel.
Definition: ftp_client.h:255