FTP client

The FTP client library can be used to download or upload FTP server files.

The file is downloaded in fragments of NET_IPV4_MTU. The size of a file can be fetched by LIST command.

The FTP client library reports FTP control message and download data with two separate callback functions (ftp_client_callback_t and ftp_client_callback_t). The library automatically sends KEEPALIVE message to the server through a timer if CONFIG_FTP_CLIENT_KEEPALIVE_TIME is not zero. The KEEPALIVE message is sent periodically at the completion of the time interval indicated by the value of CONFIG_FTP_CLIENT_KEEPALIVE_TIME.

If there is no username or password provided, the library performs a login as an anonymous user.

Protocols

The library is implemented in accordance with the RFC959 File Transfer Protocol (FTP) specification.

Limitations

The library implements only a minimal set of commands as of now. However, new command support can be easily added.

The library supports IPv4 protocol only.

Due to the differences in the implementation of FTP servers, the library might need customization to work with a specific server.

API documentation

Header file: include/ftp_client.h
Source files: subsys/net/lib/ftp_client/src/
group ftp_client

Library for FTP client.

Provide selected FTP client functionality

Defines

FTP_PRELIMINARY_POS(code)
FTP_COMPLETION_POS(code)
FTP_INTERMEDIATE_POS(code)
FTP_TRANSIENT_NEG(code)
FTP_COMPLETION_NEG(code)
FTP_PROTECTED(code)
FTP_PROPRIETARY(code)
FTP_WINSOCK_ERR(code)

Typedefs

typedef void (*ftp_client_callback_t)(const uint8_t *msg, uint16_t len)

FTP asynchronous callback function.

Param msg

FTP client data received, or local message

Param len

length of message

Enums

enum ftp_reply_code

List of FTP server reply codes Reference RFC959 FTP Transfer Protocol.

Values:

enumerator FTP_CODE_110

Restart marker replay. In this case, the text is exact and not left to the particular implementation; it must read: MARK yyyy = mmmm where yyyy is User-process data stream marker, and mmmm server’s equivalent marker (note the spaces between markers and “=”)

enumerator FTP_CODE_120

Service ready in nnn minutes

enumerator FTP_CODE_125

Data connection already open; transfer starting

enumerator FTP_CODE_150

File status okay; about to open data connection

enumerator FTP_CODE_200

Command OK

enumerator FTP_CODE_202

Command not implemented, superfluous at this site

enumerator FTP_CODE_211

System status, or system help reply

enumerator FTP_CODE_212

Directory status

enumerator FTP_CODE_213

File status

enumerator FTP_CODE_214

Help message. Explains how to use the server or the meaning of a particular non-standard command. This reply is useful only to the human user

enumerator FTP_CODE_215

NAME system type. Where NAME is an official system name from the registry kept by IANA.

enumerator FTP_CODE_220

Service ready for new user

enumerator FTP_CODE_221

Service closing control connection

enumerator FTP_CODE_225

Data connection open; no transfer in progress

enumerator FTP_CODE_226

Closing data connection. Requested file action successful (for example, file transfer or file abort)

enumerator FTP_CODE_227

Entering Passive Mode (h1,h2,h3,h4,p1,p2)

enumerator FTP_CODE_228

Entering Long Passive Mode (long address, port)

enumerator FTP_CODE_229

Entering Extended Passive Mode (|||port|)

enumerator FTP_CODE_230

User logged in, proceed. Logged out if appropriate

enumerator FTP_CODE_231

User logged out; service terminated

enumerator FTP_CODE_233

Logout command noted, will complete when transfer done

enumerator FTP_CODE_234

Specifies that the server accepts the authentication mechanism specified by the client, and the exchange of security data is complete. A higher level nonstandard code created by Microsoft

enumerator FTP_CODE_250

Requested file action okay, completed

enumerator FTP_CODE_257

“PATHNAME” created

enumerator FTP_CODE_331

User name okay, need password

enumerator FTP_CODE_332

Need account for login

enumerator FTP_CODE_350

Requested file action pending further information

enumerator FTP_CODE_421

Service not available, closing control connection. This may be a reply to any command if the service knows it must shut down

enumerator FTP_CODE_425

Cannot open data connection

enumerator FTP_CODE_426

Connection closed; transfer aborted

enumerator FTP_CODE_430

Invalid username or password

enumerator FTP_CODE_434

Requested host unavailable

enumerator FTP_CODE_450

Requested file action not taken

enumerator FTP_CODE_451

Requested action aborted. Local error in processing

enumerator FTP_CODE_452

Requested action not taken. Insufficient storage space in system. File unavailable (for example, file busy)

enumerator FTP_CODE_500

General error

enumerator FTP_CODE_501

Syntax error in parameters or arguments

enumerator FTP_CODE_502

Command not implemented

enumerator FTP_CODE_503

Bad sequence of commands

enumerator FTP_CODE_504

Command not implemented for that parameter

enumerator FTP_CODE_530

Not logged in

enumerator FTP_CODE_532

Need account for storing files

enumerator FTP_CODE_534

Could Not Connect to Server - Policy Requires SSL

enumerator FTP_CODE_550

Requested action not taken. File unavailable (for example, file not found, no access)

enumerator FTP_CODE_551

Requested action aborted. Page type unknown

enumerator FTP_CODE_552

Requested file action aborted. Exceeded storage allocation (for current directory or dataset)

enumerator FTP_CODE_553

Requested action not taken. File name not allowed

enumerator FTP_CODE_631

Integrity protected reply

enumerator FTP_CODE_632

Confidentiality and integrity protected reply

enumerator FTP_CODE_633

Confidentiality protected reply

enumerator FTP_CODE_900

DUMMY

enumerator FTP_CODE_901

Fatal errors Disconnected by remote server

enumerator FTP_CODE_902

Connection aborted

enumerator FTP_CODE_903

Socket poll error

enumerator FTP_CODE_904

Unexpected poll event

enumerator FTP_CODE_905

Network down

enumerator FTP_CODE_909

Unexpected error

enumerator FTP_CODE_910

Data transfer timeout

enumerator FTP_CODE_10054

Connection reset by peer. The connection was forcibly closed by the remote host

enumerator FTP_CODE_10060

Cannot connect to remote server

enumerator FTP_CODE_10061

Cannot connect to remote server. The connection is actively refused by the server

enumerator FTP_CODE_10066

Directory not empty

enumerator FTP_CODE_10068

Too many users, server is full

enum ftp_trasfer_type

Values:

enumerator FTP_TYPE_ASCII
enumerator FTP_TYPE_BINARY
enum ftp_put_type

Values:

enumerator FTP_PUT_NORMAL
enumerator FTP_PUT_UNIQUE
enumerator FTP_PUT_APPEND

Functions

int ftp_init(ftp_client_callback_t ctrl_callback, ftp_client_callback_t data_callback)

Initialize the FTP client library.

Parameters
  • ctrl_callback – Callback for FTP command result.

  • data_callback – Callback for FTP received data.

Return values

0 – If successfully initialized. Otherwise, a negative value is returned.

int ftp_uninit(void)

Uninitialize the FTP client library.

Return values

0 – If successfully initialized. Otherwise, a negative value is returned.

int ftp_open(const char *hostname, uint16_t port, int sec_tag)

Open FTP connection.

Parameters
  • hostname – FTP server name or IP address

  • port – FTP service port on server

  • sec_tag – If FTP over TLS is required (-1 means no TLS)

Return values

ftp_reply_code – or negative if error

int ftp_login(const char *username, const char *password)

FTP server login.

Parameters
  • username – user name

  • password – The password

Return values

ftp_reply_code – or negative if error

int ftp_close(void)

Close FTP connection.

Return values

ftp_reply_code – or negative if error

int ftp_status(void)

Get FTP server and connection status Also returns server system type.

Return values

ftp_reply_code – or negative if error

int ftp_type(enum ftp_trasfer_type type)

Set FTP transfer type.

Parameters
  • type – transfer type

Return values

ftp_reply_code – or negative if error

int ftp_pwd(void)

Print working directory.

Return values

ftp_reply_code – or negative if error

int ftp_list(const char *options, const char *target)

List information of folder or file.

Parameters
  • options – List options, refer to Linux “man ls”

  • target – file or directory to list. If not specified, list current folder

Return values

ftp_reply_code – or negative if error

int ftp_cwd(const char *folder)

Change working directory.

Parameters
  • folder – Target folder

Return values

ftp_reply_code – or negative if error

int ftp_mkd(const char *folder)

Make directory.

Parameters
  • folder – New folder name

Return values

ftp_reply_code – or negative if error

int ftp_rmd(const char *folder)

Remove directory.

Parameters
  • folder – Target folder name

Return values

ftp_reply_code – or negative if error

int ftp_rename(const char *old_name, const char *new_name)

Rename a file.

Parameters
  • old_name – Old file name

  • new_name – New file name

Return values

ftp_reply_code – or negative if error

int ftp_delete(const char *file)

Delete a file.

Parameters
  • file – Target file name

Return values

ftp_reply_code – or negative if error

int ftp_get(const char *file)

Get a file.

Parameters
  • file – Target file name

Return values

ftp_reply_code – or negative if error

int ftp_put(const char *file, const uint8_t *data, uint16_t length, int type)

Put data to a file If file does not exist, create the file.

Parameters
  • file – Target file name

  • data – Data to be stored

  • length – Length of data to be stored

  • type – specify FTP put types, see enum ftp_reply_code

Return values

ftp_reply_code – or negative if error