Data Structures | Macros | Typedefs | Enumerations | Functions
ftp_client.h File Reference

FTP client (File Transfer Protocol) More...

#include "core/net.h"
#include "date_time.h"
#include "core/crypto.h"
#include "tls.h"

Go to the source code of this file.

Data Structures

struct  FtpClientChannel
 Control or data channel. More...
 
struct  _FtpClientContext
 FTP client context. More...
 
struct  FtpDirEntry
 Directory entry. More...
 

Macros

#define FTP_CLIENT_SUPPORT   ENABLED
 
#define FTP_CLIENT_TLS_SUPPORT   DISABLED
 
#define FTP_CLIENT_DEFAULT_TIMEOUT   20000
 
#define FTP_CLIENT_BUFFER_SIZE   512
 
#define FTP_CLIENT_MIN_TCP_BUFFER_SIZE   1430
 
#define FTP_CLIENT_MAX_TCP_BUFFER_SIZE   2860
 
#define FTP_CLIENT_TLS_TX_BUFFER_SIZE   2048
 
#define FTP_CLIENT_MIN_TLS_RX_BUFFER_SIZE   4096
 
#define FTP_CLIENT_MAX_TLS_RX_BUFFER_SIZE   16384
 
#define FTP_CLIENT_MAX_FILENAME_LEN   64
 
#define FTP_CLIENT_PRIVATE_CONTEXT
 
#define FTP_REPLY_CODE_1YZ(code)   ((code) >= 100 && (code) < 200)
 
#define FTP_REPLY_CODE_2YZ(code)   ((code) >= 200 && (code) < 300)
 
#define FTP_REPLY_CODE_3YZ(code)   ((code) >= 300 && (code) < 400)
 
#define FTP_REPLY_CODE_4YZ(code)   ((code) >= 400 && (code) < 500)
 
#define FTP_REPLY_CODE_5YZ(code)   ((code) >= 500 && (code) < 600)
 
#define FtpClientContext   struct _FtpClientContext
 

Typedefs

typedef error_t(* FtpClientTlsInitCallback) (FtpClientContext *context, TlsContext *tlsContext)
 TLS initialization callback function. More...
 

Enumerations

enum  FtpConnectionModes {
  FTP_MODE_PLAINTEXT = 0, FTP_MODE_IMPLICIT_TLS = 1, FTP_MODE_EXPLICIT_TLS = 2, FTP_MODE_ACTIVE = 0,
  FTP_MODE_PASSIVE = 4
}
 FTP connection modes. More...
 
enum  FtpFileModes {
  FTP_FILE_MODE_READ = 0, FTP_FILE_MODE_WRITE = 1, FTP_FILE_MODE_APPEND = 2, FTP_FILE_MODE_BINARY = 0,
  FTP_FILE_MODE_TEXT = 4
}
 File access modes. More...
 
enum  FtpFileFlags {
  FTP_FLAG_WAIT_ALL = 0x0800, FTP_FLAG_BREAK_CHAR = 0x1000, FTP_FLAG_BREAK_CRLF = 0x100A, FTP_FLAG_NO_DELAY = 0x4000,
  FTP_FLAG_DELAY = 0x8000
}
 Flags used by I/O functions. More...
 
enum  FtpFileAttributes { FTP_FILE_ATTR_DIRECTORY = 1, FTP_FILE_ATTR_READ_ONLY = 2 }
 File attributes. More...
 
enum  FtpClientState {
  FTP_CLIENT_STATE_DISCONNECTED = 0, FTP_CLIENT_STATE_ACCEPTING_TCP = 1, FTP_CLIENT_STATE_CONNECTING_TCP = 2, FTP_CLIENT_STATE_CONNECTING_TLS = 3,
  FTP_CLIENT_STATE_CONNECTED = 4, FTP_CLIENT_STATE_SUB_COMMAND_1 = 5, FTP_CLIENT_STATE_SUB_COMMAND_2 = 6, FTP_CLIENT_STATE_SUB_COMMAND_3 = 7,
  FTP_CLIENT_STATE_SUB_COMMAND_4 = 8, FTP_CLIENT_STATE_SUB_COMMAND_5 = 9, FTP_CLIENT_STATE_SUB_COMMAND_6 = 10, FTP_CLIENT_STATE_SUB_COMMAND_7 = 11,
  FTP_CLIENT_STATE_SUB_COMMAND_8 = 12, FTP_CLIENT_STATE_SUB_COMMAND_9 = 13, FTP_CLIENT_STATE_WRITING_DATA = 14, FTP_CLIENT_STATE_READING_DATA = 15,
  FTP_CLIENT_STATE_DISCONNECTING_1 = 16, FTP_CLIENT_STATE_DISCONNECTING_2 = 17
}
 FTP client states. More...
 

Functions

error_t ftpClientInit (FtpClientContext *context)
 Initialize FTP client context. More...
 
error_t ftpClientRegisterTlsInitCallback (FtpClientContext *context, FtpClientTlsInitCallback callback)
 Register TLS initialization callback function. More...
 
error_t ftpClientSetTimeout (FtpClientContext *context, systime_t timeout)
 Set communication timeout. More...
 
error_t ftpClientBindToInterface (FtpClientContext *context, NetInterface *interface)
 Bind the FTP client to a particular network interface. More...
 
error_t ftpClientConnect (FtpClientContext *context, const IpAddr *serverIpAddr, uint16_t serverPort, uint_t mode)
 Establish a connection with the specified FTP server. More...
 
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. More...
 
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. More...
 
error_t ftpClientGetWorkingDir (FtpClientContext *context, char_t *path, size_t maxLen)
 Get current working directory. More...
 
error_t ftpClientChangeWorkingDir (FtpClientContext *context, const char_t *path)
 Change working directory. More...
 
error_t ftpClientChangeToParentDir (FtpClientContext *context)
 Change to parent directory. More...
 
error_t ftpClientOpenDir (FtpClientContext *context, const char_t *path)
 Open a directory. More...
 
error_t ftpClientReadDir (FtpClientContext *context, FtpDirEntry *dirEntry)
 Read an entry from the directory. More...
 
error_t ftpClientCloseDir (FtpClientContext *context)
 Close directory. More...
 
error_t ftpClientCreateDir (FtpClientContext *context, const char_t *path)
 Create a new directory. More...
 
error_t ftpClientDeleteDir (FtpClientContext *context, const char_t *path)
 Remove a directory. More...
 
error_t ftpClientOpenFile (FtpClientContext *context, const char_t *path, uint_t mode)
 Open a file for reading, writing, or appending. More...
 
error_t ftpClientWriteFile (FtpClientContext *context, const void *data, size_t length, size_t *written, uint_t flags)
 Write to a remote file. More...
 
error_t ftpClientReadFile (FtpClientContext *context, void *data, size_t size, size_t *received, uint_t flags)
 Read from a remote file. More...
 
error_t ftpClientCloseFile (FtpClientContext *context)
 Close file. More...
 
error_t ftpClientRenameFile (FtpClientContext *context, const char_t *oldPath, const char_t *newPath)
 Rename a file. More...
 
error_t ftpClientDeleteFile (FtpClientContext *context, const char_t *path)
 Delete a file. More...
 
uint_t ftpClientGetReplyCode (FtpClientContext *context)
 Retrieve server's reply code. More...
 
error_t ftpClientDisconnect (FtpClientContext *context)
 Gracefully disconnect from the FTP server. More...
 
error_t ftpClientClose (FtpClientContext *context)
 Close the connection with the FTP server. More...
 
void ftpClientDeinit (FtpClientContext *context)
 Release FTP client context. More...
 

Detailed Description

FTP client (File Transfer Protocol)

License

SPDX-License-Identifier: GPL-2.0-or-later

Copyright (C) 2010-2025 Oryx Embedded SARL. All rights reserved.

This file is part of CycloneTCP Open.

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.

Author
Oryx Embedded SARL (www.oryx-embedded.com)
Version
2.5.4

Definition in file ftp_client.h.

Macro Definition Documentation

◆ FTP_CLIENT_BUFFER_SIZE

#define FTP_CLIENT_BUFFER_SIZE   512

Definition at line 61 of file ftp_client.h.

◆ FTP_CLIENT_DEFAULT_TIMEOUT

#define FTP_CLIENT_DEFAULT_TIMEOUT   20000

Definition at line 54 of file ftp_client.h.

◆ FTP_CLIENT_MAX_FILENAME_LEN

#define FTP_CLIENT_MAX_FILENAME_LEN   64

Definition at line 103 of file ftp_client.h.

◆ FTP_CLIENT_MAX_TCP_BUFFER_SIZE

#define FTP_CLIENT_MAX_TCP_BUFFER_SIZE   2860

Definition at line 75 of file ftp_client.h.

◆ FTP_CLIENT_MAX_TLS_RX_BUFFER_SIZE

#define FTP_CLIENT_MAX_TLS_RX_BUFFER_SIZE   16384

Definition at line 96 of file ftp_client.h.

◆ FTP_CLIENT_MIN_TCP_BUFFER_SIZE

#define FTP_CLIENT_MIN_TCP_BUFFER_SIZE   1430

Definition at line 68 of file ftp_client.h.

◆ FTP_CLIENT_MIN_TLS_RX_BUFFER_SIZE

#define FTP_CLIENT_MIN_TLS_RX_BUFFER_SIZE   4096

Definition at line 89 of file ftp_client.h.

◆ FTP_CLIENT_PRIVATE_CONTEXT

#define FTP_CLIENT_PRIVATE_CONTEXT

Definition at line 110 of file ftp_client.h.

◆ FTP_CLIENT_SUPPORT

#define FTP_CLIENT_SUPPORT   ENABLED

Definition at line 40 of file ftp_client.h.

◆ FTP_CLIENT_TLS_SUPPORT

#define FTP_CLIENT_TLS_SUPPORT   DISABLED

Definition at line 47 of file ftp_client.h.

◆ FTP_CLIENT_TLS_TX_BUFFER_SIZE

#define FTP_CLIENT_TLS_TX_BUFFER_SIZE   2048

Definition at line 82 of file ftp_client.h.

◆ FTP_REPLY_CODE_1YZ

#define FTP_REPLY_CODE_1YZ (   code)    ((code) >= 100 && (code) < 200)

Definition at line 120 of file ftp_client.h.

◆ FTP_REPLY_CODE_2YZ

#define FTP_REPLY_CODE_2YZ (   code)    ((code) >= 200 && (code) < 300)

Definition at line 121 of file ftp_client.h.

◆ FTP_REPLY_CODE_3YZ

#define FTP_REPLY_CODE_3YZ (   code)    ((code) >= 300 && (code) < 400)

Definition at line 122 of file ftp_client.h.

◆ FTP_REPLY_CODE_4YZ

#define FTP_REPLY_CODE_4YZ (   code)    ((code) >= 400 && (code) < 500)

Definition at line 123 of file ftp_client.h.

◆ FTP_REPLY_CODE_5YZ

#define FTP_REPLY_CODE_5YZ (   code)    ((code) >= 500 && (code) < 600)

Definition at line 124 of file ftp_client.h.

◆ FtpClientContext

#define FtpClientContext   struct _FtpClientContext

Definition at line 128 of file ftp_client.h.

Typedef Documentation

◆ FtpClientTlsInitCallback

typedef error_t(* FtpClientTlsInitCallback) (FtpClientContext *context, TlsContext *tlsContext)

TLS initialization callback function.

Definition at line 223 of file ftp_client.h.

Enumeration Type Documentation

◆ FtpClientState

enum FtpClientState

FTP client states.

Enumerator
FTP_CLIENT_STATE_DISCONNECTED 
FTP_CLIENT_STATE_ACCEPTING_TCP 
FTP_CLIENT_STATE_CONNECTING_TCP 
FTP_CLIENT_STATE_CONNECTING_TLS 
FTP_CLIENT_STATE_CONNECTED 
FTP_CLIENT_STATE_SUB_COMMAND_1 
FTP_CLIENT_STATE_SUB_COMMAND_2 
FTP_CLIENT_STATE_SUB_COMMAND_3 
FTP_CLIENT_STATE_SUB_COMMAND_4 
FTP_CLIENT_STATE_SUB_COMMAND_5 
FTP_CLIENT_STATE_SUB_COMMAND_6 
FTP_CLIENT_STATE_SUB_COMMAND_7 
FTP_CLIENT_STATE_SUB_COMMAND_8 
FTP_CLIENT_STATE_SUB_COMMAND_9 
FTP_CLIENT_STATE_WRITING_DATA 
FTP_CLIENT_STATE_READING_DATA 
FTP_CLIENT_STATE_DISCONNECTING_1 
FTP_CLIENT_STATE_DISCONNECTING_2 

Definition at line 193 of file ftp_client.h.

◆ FtpConnectionModes

enum FtpConnectionModes

FTP connection modes.

Enumerator
FTP_MODE_PLAINTEXT 
FTP_MODE_IMPLICIT_TLS 
FTP_MODE_EXPLICIT_TLS 
FTP_MODE_ACTIVE 
FTP_MODE_PASSIVE 

Definition at line 140 of file ftp_client.h.

◆ FtpFileAttributes

enum FtpFileAttributes

File attributes.

Enumerator
FTP_FILE_ATTR_DIRECTORY 
FTP_FILE_ATTR_READ_ONLY 

Definition at line 182 of file ftp_client.h.

◆ FtpFileFlags

enum FtpFileFlags

Flags used by I/O functions.

Enumerator
FTP_FLAG_WAIT_ALL 
FTP_FLAG_BREAK_CHAR 
FTP_FLAG_BREAK_CRLF 
FTP_FLAG_NO_DELAY 
FTP_FLAG_DELAY 

Definition at line 168 of file ftp_client.h.

◆ FtpFileModes

enum FtpFileModes

File access modes.

Enumerator
FTP_FILE_MODE_READ 
FTP_FILE_MODE_WRITE 
FTP_FILE_MODE_APPEND 
FTP_FILE_MODE_BINARY 
FTP_FILE_MODE_TEXT 

Definition at line 154 of file ftp_client.h.

Function Documentation

◆ ftpClientBindToInterface()

error_t ftpClientBindToInterface ( FtpClientContext *  context,
NetInterface *  interface 
)

Bind the FTP client to a particular network interface.

Parameters
[in]contextPointer to the FTP client context
[in]interfaceNetwork interface to be used
Returns
Error code

Definition at line 145 of file ftp_client.c.

◆ ftpClientChangeToParentDir()

error_t ftpClientChangeToParentDir ( FtpClientContext *  context)

Change to parent directory.

Parameters
[in]contextPointer to the FTP client context
Returns
Error code

Definition at line 695 of file ftp_client.c.

◆ ftpClientChangeWorkingDir()

error_t ftpClientChangeWorkingDir ( FtpClientContext *  context,
const char_t *  path 
)

Change working directory.

Parameters
[in]contextPointer to the FTP client context
[in]pathNew current working directory
Returns
Error code

Definition at line 621 of file ftp_client.c.

◆ ftpClientClose()

error_t ftpClientClose ( FtpClientContext *  context)

Close the connection with the FTP server.

Parameters
[in]contextPointer to the FTP client context
Returns
Error code

Definition at line 1750 of file ftp_client.c.

◆ ftpClientCloseDir()

error_t ftpClientCloseDir ( FtpClientContext *  context)

Close directory.

Parameters
[in]contextPointer to the FTP client context
Returns
Error code

Definition at line 994 of file ftp_client.c.

◆ ftpClientCloseFile()

error_t ftpClientCloseFile ( FtpClientContext *  context)

Close file.

Parameters
[in]contextPointer to the FTP client context
Returns
Error code

Definition at line 1437 of file ftp_client.c.

◆ ftpClientConnect()

error_t ftpClientConnect ( FtpClientContext *  context,
const IpAddr *  serverIpAddr,
uint16_t  serverPort,
uint_t  mode 
)

Establish a connection with the specified FTP server.

Parameters
[in]contextPointer to the FTP client context
[in]serverIpAddrIP address of the FTP server to connect to
[in]serverPortPort number
[in]modeFTP connection mode
Returns
Error code

Definition at line 169 of file ftp_client.c.

◆ ftpClientCreateDir()

error_t ftpClientCreateDir ( FtpClientContext *  context,
const char_t *  path 
)

Create a new directory.

Parameters
[in]contextPointer to the FTP client context
[in]pathName of the new directory
Returns
Error code

Definition at line 1012 of file ftp_client.c.

◆ ftpClientDeinit()

void ftpClientDeinit ( FtpClientContext *  context)

Release FTP client context.

Parameters
[in]contextPointer to the FTP client context

Definition at line 1773 of file ftp_client.c.

◆ ftpClientDeleteDir()

error_t ftpClientDeleteDir ( FtpClientContext *  context,
const char_t *  path 
)

Remove a directory.

Parameters
[in]contextPointer to the FTP client context
[in]pathPath to the directory to be removed
Returns
Error code

Definition at line 1086 of file ftp_client.c.

◆ ftpClientDeleteFile()

error_t ftpClientDeleteFile ( FtpClientContext *  context,
const char_t *  path 
)

Delete a file.

Parameters
[in]contextPointer to the FTP client context
[in]pathPath to the file to be be deleted
Returns
Error code

Definition at line 1561 of file ftp_client.c.

◆ ftpClientDisconnect()

error_t ftpClientDisconnect ( FtpClientContext *  context)

Gracefully disconnect from the FTP server.

Parameters
[in]contextPointer to the FTP client context
Returns
Error code

Definition at line 1661 of file ftp_client.c.

◆ ftpClientGetReplyCode()

uint_t ftpClientGetReplyCode ( FtpClientContext *  context)

Retrieve server's reply code.

Parameters
[in]contextPointer to the FTP client context
Returns
FTP reply code

Definition at line 1634 of file ftp_client.c.

◆ ftpClientGetWorkingDir()

error_t ftpClientGetWorkingDir ( FtpClientContext *  context,
char_t *  path,
size_t  maxLen 
)

Get current working directory.

Parameters
[in]contextPointer to the FTP client context
[out]pathOutput buffer where to store the current directory
[in]maxLenMaximum number of characters the buffer can hold
Returns
Error code

Definition at line 541 of file ftp_client.c.

◆ ftpClientInit()

error_t ftpClientInit ( FtpClientContext *  context)

Initialize FTP client context.

Parameters
[in]contextPointer to the FTP client context
Returns
Error code

Definition at line 60 of file ftp_client.c.

◆ ftpClientLogin()

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.

Parameters
[in]contextPointer to the FTP client context
[in]usernameNULL-terminated string containing the user name
[in]passwordNULL-terminated string containing the user's password
Returns
Error code

Definition at line 374 of file ftp_client.c.

◆ ftpClientLoginEx()

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.

Parameters
[in]contextPointer to the FTP client context
[in]usernameNULL-terminated string containing the user name
[in]passwordNULL-terminated string containing the user's password
[in]accountNULL-terminated string containing the user's account
Returns
Error code

Definition at line 391 of file ftp_client.c.

◆ ftpClientOpenDir()

error_t ftpClientOpenDir ( FtpClientContext *  context,
const char_t *  path 
)

Open a directory.

Parameters
[in]contextPointer to the FTP client context
[in]pathPath to the directory to be be opened
Returns
Directory handle

Definition at line 769 of file ftp_client.c.

◆ ftpClientOpenFile()

error_t ftpClientOpenFile ( FtpClientContext *  context,
const char_t *  path,
uint_t  mode 
)

Open a file for reading, writing, or appending.

Parameters
[in]contextPointer to the FTP client context
[in]pathPath to the file to be be opened
[in]modeFile access mode
Returns
Error code

Definition at line 1161 of file ftp_client.c.

◆ ftpClientReadDir()

error_t ftpClientReadDir ( FtpClientContext *  context,
FtpDirEntry *  dirEntry 
)

Read an entry from the directory.

Parameters
[in]contextPointer to the FTP client context
[out]dirEntryPointer to a directory entry
Returns
Error code

Definition at line 899 of file ftp_client.c.

◆ ftpClientReadFile()

error_t ftpClientReadFile ( FtpClientContext *  context,
void *  data,
size_t  size,
size_t *  received,
uint_t  flags 
)

Read from a remote file.

Parameters
[in]contextPointer to the FTP client context
[out]dataBuffer where to store the incoming data
[in]sizeMaximum number of bytes that can be read
[out]receivedActual number of bytes that have been read
[in]flagsSet of flags that influences the behavior of this function
Returns
Error code

Definition at line 1388 of file ftp_client.c.

◆ ftpClientRegisterTlsInitCallback()

error_t ftpClientRegisterTlsInitCallback ( FtpClientContext *  context,
FtpClientTlsInitCallback  callback 
)

Register TLS initialization callback function.

Parameters
[in]contextPointer to the FTP client context
[in]callbackTLS initialization callback function
Returns
Error code

Definition at line 100 of file ftp_client.c.

◆ ftpClientRenameFile()

error_t ftpClientRenameFile ( FtpClientContext *  context,
const char_t *  oldPath,
const char_t *  newPath 
)

Rename a file.

Parameters
[in]contextPointer to the FTP client context
[in]oldPathName of an existing file or directory
[in]newPathNew name for the file or directory
Returns
Error code

Definition at line 1456 of file ftp_client.c.

◆ ftpClientSetTimeout()

error_t ftpClientSetTimeout ( FtpClientContext *  context,
systime_t  timeout 
)

Set communication timeout.

Parameters
[in]contextPointer to the FTP client context
[in]timeoutTimeout value, in milliseconds
Returns
Error code

Definition at line 124 of file ftp_client.c.

◆ ftpClientWriteFile()

error_t ftpClientWriteFile ( FtpClientContext *  context,
const void *  data,
size_t  length,
size_t *  written,
uint_t  flags 
)

Write to a remote file.

Parameters
[in]contextPointer to the FTP client context
[in]dataPointer to a buffer containing the data to be written
[in]lengthNumber of data bytes to write
[in]writtenNumber of bytes that have been written (optional parameter)
[in]flagsSet of flags that influences the behavior of this function
Returns
Error code

Definition at line 1319 of file ftp_client.c.