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
enumerator FTP_CODE_120
enumerator FTP_CODE_125
enumerator FTP_CODE_150
enumerator FTP_CODE_200
enumerator FTP_CODE_202
enumerator FTP_CODE_211
enumerator FTP_CODE_212
enumerator FTP_CODE_213
enumerator FTP_CODE_214
enumerator FTP_CODE_215
enumerator FTP_CODE_220
enumerator FTP_CODE_221
enumerator FTP_CODE_225
enumerator FTP_CODE_226
enumerator FTP_CODE_227
enumerator FTP_CODE_228
enumerator FTP_CODE_229
enumerator FTP_CODE_230
enumerator FTP_CODE_231
enumerator FTP_CODE_233
enumerator FTP_CODE_234
enumerator FTP_CODE_250
enumerator FTP_CODE_257
enumerator FTP_CODE_331
enumerator FTP_CODE_332
enumerator FTP_CODE_350
enumerator FTP_CODE_421
enumerator FTP_CODE_425
enumerator FTP_CODE_426
enumerator FTP_CODE_430
enumerator FTP_CODE_434
enumerator FTP_CODE_450
enumerator FTP_CODE_451
enumerator FTP_CODE_452
enumerator FTP_CODE_500
enumerator FTP_CODE_501
enumerator FTP_CODE_502
enumerator FTP_CODE_503
enumerator FTP_CODE_504
enumerator FTP_CODE_530
enumerator FTP_CODE_532
enumerator FTP_CODE_534
enumerator FTP_CODE_550
enumerator FTP_CODE_551
enumerator FTP_CODE_552
enumerator FTP_CODE_553
enumerator FTP_CODE_631
enumerator FTP_CODE_632
enumerator FTP_CODE_633
enumerator FTP_CODE_900
enumerator FTP_CODE_901

Fatal errors

enumerator FTP_CODE_902
enumerator FTP_CODE_903
enumerator FTP_CODE_904
enumerator FTP_CODE_905
enumerator FTP_CODE_909
enumerator FTP_CODE_910

Non-fatal errors

enumerator FTP_CODE_10054
enumerator FTP_CODE_10060
enumerator FTP_CODE_10061
enumerator FTP_CODE_10066
enumerator FTP_CODE_10068
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