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  * Copyright (C) 2010-2018 Oryx Embedded SARL. All rights reserved.
8  *
9  * This file is part of CycloneTCP Open.
10  *
11  * This program is free software; you can redistribute it and/or
12  * modify it under the terms of the GNU General Public License
13  * as published by the Free Software Foundation; either version 2
14  * of the License, or (at your option) any later version.
15  *
16  * This program is distributed in the hope that it will be useful,
17  * but WITHOUT ANY WARRANTY; without even the implied warranty of
18  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
19  * GNU General Public License for more details.
20  *
21  * You should have received a copy of the GNU General Public License
22  * along with this program; if not, write to the Free Software Foundation,
23  * Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
24  *
25  * @author Oryx Embedded SARL (www.oryx-embedded.com)
26  * @version 1.9.0
27  **/
28 
29 #ifndef _FTP_CLIENT_H
30 #define _FTP_CLIENT_H
31 
32 //Dependencies
33 #include "core/net.h"
34 #include "date_time.h"
35 
36 //FTP client support
37 #ifndef FTP_CLIENT_SUPPORT
38  #define FTP_CLIENT_SUPPORT ENABLED
39 #elif (FTP_CLIENT_SUPPORT != ENABLED && FTP_CLIENT_SUPPORT != DISABLED)
40  #error FTP_CLIENT_SUPPORT parameter is not valid
41 #endif
42 
43 //FTP over TLS
44 #ifndef FTP_CLIENT_TLS_SUPPORT
45  #define FTP_CLIENT_TLS_SUPPORT DISABLED
46 #elif (FTP_CLIENT_TLS_SUPPORT != ENABLED && FTP_CLIENT_TLS_SUPPORT != DISABLED)
47  #error FTP_CLIENT_TLS_SUPPORT parameter is not valid
48 #endif
49 
50 //Default timeout
51 #ifndef FTP_CLIENT_DEFAULT_TIMEOUT
52  #define FTP_CLIENT_DEFAULT_TIMEOUT 20000
53 #elif (FTP_CLIENT_DEFAULT_TIMEOUT < 1000)
54  #error FTP_CLIENT_DEFAULT_TIMEOUT parameter is not valid
55 #endif
56 
57 //Size of the buffer for input/output operations
58 #ifndef FTP_CLIENT_BUFFER_SIZE
59  #define FTP_CLIENT_BUFFER_SIZE 512
60 #elif (FTP_CLIENT_BUFFER_SIZE < 64)
61  #error FTP_CLIENT_BUFFER_SIZE parameter is not valid
62 #endif
63 
64 //Minimum buffer size for TCP sockets
65 #ifndef FTP_CLIENT_MIN_TCP_BUFFER_SIZE
66  #define FTP_CLIENT_MIN_TCP_BUFFER_SIZE 1430
67 #elif (FTP_CLIENT_MIN_TCP_BUFFER_SIZE < 512)
68  #error FTP_CLIENT_MIN_TCP_BUFFER_SIZE parameter is not valid
69 #endif
70 
71 //Maximum buffer size for TCP sockets
72 #ifndef FTP_CLIENT_MAX_TCP_BUFFER_SIZE
73  #define FTP_CLIENT_MAX_TCP_BUFFER_SIZE 2860
74 #elif (FTP_CLIENT_MAX_TCP_BUFFER_SIZE < 512)
75  #error FTP_CLIENT_MAX_TCP_BUFFER_SIZE parameter is not valid
76 #endif
77 
78 //TX buffer size for TLS connections
79 #ifndef FTP_CLIENT_TLS_TX_BUFFER_SIZE
80  #define FTP_CLIENT_TLS_TX_BUFFER_SIZE 2048
81 #elif (FTP_CLIENT_TLS_TX_BUFFER_SIZE < 512)
82  #error FTP_CLIENT_TLS_TX_BUFFER_SIZE parameter is not valid
83 #endif
84 
85 //Minimum RX buffer size for TLS connections
86 #ifndef FTP_CLIENT_MIN_TLS_RX_BUFFER_SIZE
87  #define FTP_CLIENT_MIN_TLS_RX_BUFFER_SIZE 4096
88 #elif (FTP_CLIENT_MIN_TLS_RX_BUFFER_SIZE < 512)
89  #error FTP_CLIENT_MIN_TLS_RX_BUFFER_SIZE parameter is not valid
90 #endif
91 
92 //Maximum RX buffer size for TLS connections
93 #ifndef FTP_CLIENT_MAX_TLS_RX_BUFFER_SIZE
94  #define FTP_CLIENT_MAX_TLS_RX_BUFFER_SIZE 16384
95 #elif (FTP_CLIENT_MAX_TLS_RX_BUFFER_SIZE < 512)
96  #error FTP_CLIENT_MAX_TLS_RX_BUFFER_SIZE parameter is not valid
97 #endif
98 
99 //Maximum length of file names
100 #ifndef FTP_CLIENT_MAX_FILENAME_LEN
101  #define FTP_CLIENT_MAX_FILENAME_LEN 64
102 #elif (FTP_CLIENT_MAX_FILENAME_LEN < 16)
103  #error FTP_CLIENT_MAX_FILENAME_LEN parameter is not valid
104 #endif
105 
106 //TLS supported?
107 #if (FTP_CLIENT_TLS_SUPPORT == ENABLED)
108  #include "core/crypto.h"
109  #include "tls.h"
110 #endif
111 
112 //Test macros for FTP response codes
113 #define FTP_REPLY_CODE_1YZ(code) ((code) >= 100 && (code) < 200)
114 #define FTP_REPLY_CODE_2YZ(code) ((code) >= 200 && (code) < 300)
115 #define FTP_REPLY_CODE_3YZ(code) ((code) >= 300 && (code) < 400)
116 #define FTP_REPLY_CODE_4YZ(code) ((code) >= 400 && (code) < 500)
117 #define FTP_REPLY_CODE_5YZ(code) ((code) >= 500 && (code) < 600)
118 
119 //Forward declaration of FtpClientContext structure
120 struct _FtpClientContext;
121 #define FtpClientContext struct _FtpClientContext
122 
123 //C++ guard
124 #ifdef __cplusplus
125  extern "C" {
126 #endif
127 
128 
129 /**
130  * @brief FTP connection modes
131  **/
132 
133 typedef enum
134 {
141 
142 
143 /**
144  * @brief File access modes
145  **/
146 
147 typedef enum
148 {
154 } FtpFileModes;
155 
156 
157 /**
158  * @brief Flags used by I/O functions
159  **/
160 
161 typedef enum
162 {
163  FTP_FLAG_PEEK = 0x0200,
168 } FtpFileFlags;
169 
170 
171 /**
172  * @brief File attributes
173  **/
174 
175 typedef enum
176 {
180 
181 
182 /**
183  * @brief FTP client states
184  */
185 
186 typedef enum
187 {
207 
208 
209 //TLS supported?
210 #if (FTP_CLIENT_TLS_SUPPORT == ENABLED)
211 
212 /**
213  * @brief TLS initialization callback function
214  **/
215 
217  TlsContext *tlsContext);
218 
219 #endif
220 
221 
222 /**
223  * @brief Control or data connection
224  **/
225 
226 typedef struct
227 {
228  Socket *socket; ///<Underlying TCP socket
229 #if (FTP_CLIENT_TLS_SUPPORT == ENABLED)
230  TlsContext *tlsContext; ///<TLS context
231 #endif
233 
234 
235 /**
236  * @brief FTP client context
237  **/
238 
240 {
241  FtpClientState state; ///<FTP client state
242  NetInterface *interface; ///<Underlying network interface
243  systime_t timeout; ///<Timeout value
244  systime_t timestamp; ///<Timestamp to manage timeout
245  IpAddr serverIpAddr; ///<IP address of the FTP server
246  uint16_t serverPort; ///<TCP port number
247  bool_t passiveMode; ///<Passive mode
248 #if (FTP_CLIENT_TLS_SUPPORT == ENABLED)
249  TlsSessionState tlsSession; ///<TLS session state
250  FtpClientTlsInitCallback tlsInitCallback; ///<TLS initialization callback function
251 #endif
252  FtpClientSocket controlConnection; ///<Control connection
253  FtpClientSocket dataConnection; ///<Data connection
254  char_t buffer[FTP_CLIENT_BUFFER_SIZE]; ///<Memory buffer for input/output operations
255  size_t bufferPos; ///<Current position in the buffer
256  size_t commandLen; ///<Length of the FTP command, in bytes
257  size_t replyLen; ///<Length of the FTP reply, in bytes
258  uint_t replyCode; ///<FTP reply code
259 };
260 
261 
262 /**
263  * @brief Directory entry
264  **/
265 
266 typedef struct
267 {
269  uint32_t attributes;
270  uint32_t size;
272 } FtpDirEntry;
273 
274 
275 //FTP client related functions
277 
278 #if (FTP_CLIENT_TLS_SUPPORT == ENABLED)
279 
281  FtpClientTlsInitCallback callback);
282 
283 #endif
284 
286 
288  NetInterface *interface);
289 
291  const IpAddr *serverIpAddr, uint16_t serverPort, uint_t mode);
292 
293 error_t ftpClientLogin(FtpClientContext *context, const char_t *username,
294  const char_t *password);
295 
296 error_t ftpClientLoginEx(FtpClientContext *context, const char_t *username,
297  const char_t *password, const char_t *account);
298 
300  size_t maxLen);
301 
303  const char_t *path);
304 
306 
307 error_t ftpClientOpenDir(FtpClientContext *context, const char_t *path);
310 
311 error_t ftpClientMakeDir(FtpClientContext *context, const char_t *path);
312 error_t ftpClientRemoveDir(FtpClientContext *context, const char_t *path);
313 
314 error_t ftpClientOpenFile(FtpClientContext *context, const char_t *path,
315  uint_t mode);
316 
317 error_t ftpClientWriteFile(FtpClientContext *context, const void *data,
318  size_t length, size_t *written, uint_t flags);
319 
320 error_t ftpClientReadFile(FtpClientContext *context, void *data, size_t size,
321  size_t *length, uint_t flags);
322 
324 
325 error_t ftpClientRenameFile(FtpClientContext *context, const char_t *oldName,
326  const char_t *newName);
327 
328 error_t ftpClientDeleteFile(FtpClientContext *context, const char_t *path);
329 
331 
334 
335 void ftpClientDeinit(FtpClientContext *context);
336 
337 //Deprecated function
338 error_t ftpConnect(FtpClientContext *context, NetInterface *interface,
339  const IpAddr *serverIpAddr, uint16_t serverPort, uint_t flags);
340 
341 //C++ guard
342 #ifdef __cplusplus
343  }
344 #endif
345 
346 #endif
TLS (Transport Layer Security)
systime_t timestamp
Timestamp to manage timeout.
Definition: ftp_client.h:244
systime_t timeout
Timeout value.
Definition: ftp_client.h:243
uint32_t systime_t
Definition: compiler_port.h:44
char char_t
Definition: compiler_port.h:41
uint8_t flags
Definition: tcp.h:312
TCP/IP stack core.
uint32_t attributes
Definition: ftp_client.h:269
error_t ftpClientRenameFile(FtpClientContext *context, const char_t *oldName, const char_t *newName)
Rename a remote file.
Definition: ftp_client.c:1425
FtpFileAttributes
File attributes.
Definition: ftp_client.h:175
#define FTP_CLIENT_MAX_FILENAME_LEN
Definition: ftp_client.h:101
error_t ftpClientOpenFile(FtpClientContext *context, const char_t *path, uint_t mode)
Open a file for reading, writing, or appending.
Definition: ftp_client.c:1158
void ftpClientDeinit(FtpClientContext *context)
Release FTP client context.
Definition: ftp_client.c:1742
General definitions for cryptographic algorithms.
error_t ftpClientRemoveDir(FtpClientContext *context, const char_t *path)
Remove a directory on the FTP server.
Definition: ftp_client.c:1083
#define FtpClientContext
Definition: ftp_client.h:121
IP network address.
Definition: ip.h:57
bool_t passiveMode
Passive mode.
Definition: ftp_client.h:247
error_t ftpClientReadFile(FtpClientContext *context, void *data, size_t size, size_t *length, uint_t flags)
Read from a remote file.
Definition: ftp_client.c:1357
#define FTP_CLIENT_BUFFER_SIZE
Definition: ftp_client.h:59
TlsContext * tlsContext
TLS context.
Definition: ftp_client.h:230
FtpClientSocket dataConnection
Data connection.
Definition: ftp_client.h:253
error_t(* FtpClientTlsInitCallback)(FtpClientContext *context, TlsContext *tlsContext)
TLS initialization callback function.
Definition: ftp_client.h:216
TLS session state.
Definition: tls.h:1820
NetInterface * interface
Underlying network interface.
Definition: ftp_client.h:242
FtpClientState
FTP client states.
Definition: ftp_client.h:186
error_t ftpClientReadDir(FtpClientContext *context, FtpDirEntry *dirEntry)
Read an entry from the directory.
Definition: ftp_client.c:896
error_t ftpClientCloseFile(FtpClientContext *context)
Close file.
Definition: ftp_client.c:1406
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:1304
char_t buffer[FTP_CLIENT_BUFFER_SIZE]
Memory buffer for input/output operations.
Definition: ftp_client.h:254
#define Socket
Definition: socket.h:34
uint_t ftpClientGetReplyCode(FtpClientContext *context)
Retrieve server&#39;s reply code.
Definition: ftp_client.c:1603
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
char_t name[]
error_t ftpClientBindToInterface(FtpClientContext *context, NetInterface *interface)
Bind the FTP client to a particular network interface.
Definition: ftp_client.c:146
Date and time management.
error_t ftpClientClose(FtpClientContext *context)
Close the connection with the FTP server.
Definition: ftp_client.c:1719
size_t bufferPos
Current position in the buffer.
Definition: ftp_client.h:255
error_t ftpClientMakeDir(FtpClientContext *context, const char_t *path)
Create a new directory.
Definition: ftp_client.c:1009
FTP client context.
Definition: ftp_client.h:239
uint32_t size
Definition: ftp_client.h:270
FtpConnectionModes
FTP connection modes.
Definition: ftp_client.h:133
FtpFileFlags
Flags used by I/O functions.
Definition: ftp_client.h:161
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
size_t replyLen
Length of the FTP reply, in bytes.
Definition: ftp_client.h:257
TlsSessionState tlsSession
TLS session state.
Definition: ftp_client.h:249
Date and time representation.
Definition: date_time.h:44
error_t ftpClientOpenDir(FtpClientContext *context, const char_t *path)
Open a directory.
Definition: ftp_client.c:770
uint_t replyCode
FTP reply code.
Definition: ftp_client.h:258
error_t ftpClientSetTimeout(FtpClientContext *context, systime_t timeout)
Set communication timeout.
Definition: ftp_client.c:125
error_t ftpClientDisconnect(FtpClientContext *context)
Gracefully disconnect from the FTP server.
Definition: ftp_client.c:1630
error_t ftpClientDeleteFile(FtpClientContext *context, const char_t *path)
Delete a file.
Definition: ftp_client.c:1530
error_t ftpClientInit(FtpClientContext *context)
Initialize FTP client context.
Definition: ftp_client.c:60
error_t
Error codes.
Definition: error.h:40
FtpClientState state
FTP client state.
Definition: ftp_client.h:241
Control or data connection.
Definition: ftp_client.h:226
unsigned int uint_t
Definition: compiler_port.h:43
FtpFileModes
File access modes.
Definition: ftp_client.h:147
Directory entry.
Definition: ftp_client.h:266
uint8_t data[]
Definition: dtls_misc.h:167
error_t ftpClientCloseDir(FtpClientContext *context)
Close directory.
Definition: ftp_client.c:991
#define NetInterface
Definition: net.h:34
uint8_t mode
Definition: sntp_client.h:143
error_t ftpClientChangeWorkingDir(FtpClientContext *context, const char_t *path)
Change working directory.
Definition: ftp_client.c:622
uint16_t serverPort
TCP port number.
Definition: ftp_client.h:246
error_t ftpClientChangeToParentDir(FtpClientContext *context)
Change to parent directory.
Definition: ftp_client.c:696
IpAddr serverIpAddr
IP address of the FTP server.
Definition: ftp_client.h:245
error_t ftpConnect(FtpClientContext *context, NetInterface *interface, const IpAddr *serverIpAddr, uint16_t serverPort, uint_t flags)
Definition: ftp_client.c:1763
DateTime modified
Definition: ftp_client.h:271
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
size_t commandLen
Length of the FTP command, in bytes.
Definition: ftp_client.h:256
uint8_t length
Definition: dtls_misc.h:140
Socket * socket
Underlying TCP socket.
Definition: ftp_client.h:228
#define TlsContext
Definition: tls.h:34
int bool_t
Definition: compiler_port.h:47
FtpClientTlsInitCallback tlsInitCallback
TLS initialization callback function.
Definition: ftp_client.h:250
FtpClientSocket controlConnection
Control connection.
Definition: ftp_client.h:252
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