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/net/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

FTP client

Protocols

Limitations

API documentation

Protocols 

Limitations 

API documentation 