Chapter 184. FTP Client API and Configuration

184.1. FTP Client API

The FTP Client API is provided by the include file install/include/ftpclient.h and it can be used thus:

#include <network.h>
#include <ftpclient.h>
[Note]Note

The reason for the following variety of API operations performing the get and put operations is for backwards compatibility with earlier releases of the FTP Client package. Existing API parameter requirements have not been changed, with new features adding new API calls as required.

184.1.1. Support API

Support functions are available irrespective of the type of data transfer operations used.

184.1.2. ftp_delete

int ftp_delete(char * hostname,
               char * username,
               char * passwd,
               char * filename,
               ftp_printf_t ftp_printf);

Delete a file from the FTP server. The filename should be the full pathname of the file to be deleted.

184.1.3. ftpclient_printf

void ftpclient_printf(unsigned error, const char *fmt, …);

The get and put API operations take a pointer to a function to use for printing out diagnostic and error messages. This is a sample implementation which can be used if you don't want to implement the function yourself. error will be true when the message to print is an error message. Otherwise the message is diagnostic, eg. the commands sent and received from the server.

184.1.4. Basic FTP Client API

The basic API only supports active connections, and is provided for backwards compatability with earlier releases. It is superceded by the extended API described below, which provides greater control and extra features not available with the original basic API. The basic API consists of the following exported functions:

184.1.5. ftp_get

int ftp_get(char * hostname,
            char * username,
            char * passwd,
            char * filename,
            char * buf,
            unsigned buf_size,
            ftp_printf_t ftp_printf);

Use the FTP protocol to retrieve a file from a server. Only binary mode is supported. The filename can include a directory name. Only use unix style ’/‚ file separators, not ’\‚. The file is placed into buf. buf has maximum size buf_size. If the file is bigger than this, the transfer fails and FTP_TOOBIG is returned. Other error codes listed in the header can also be returned. If the transfer is successful the number of bytes received is returned.

184.1.6. ftp_put

int ftp_put(char * hostname,
            char * username,
            char * passwd,
            char * filename,
            char * buf,
            unsigned buf_size,
            ftp_printf_t ftp_printf);

Use the FTP protocol to send a file to a server. Only binary mode is supported. The filename can include a directory name. Only use unix style ’/‚ file separators, not ’\‚. The contents of buf are placed into the file on the server. If an error occurs one of the codes listed will be returned. If the transfer is successful zero is returned.

184.1.7. ftp_get_var

int ftp_get(char * hostname,
            char * username,
            char * passwd,
            char * filename,
            ftp_write_t ftp_write,
            void * ftp_write_priv,
            ftp_printf_t ftp_printf);

Use the FTP protocol to retrieve a file from a server. Only binary mode is supported. The filename can include a directory name. Only use unix style ’/‚ file separators, not ’\‚. The ftp_write function is called as data arrives, using the supplied ftp_write_priv private context. If the transfer is successful the total number of bytes received is returned.

184.1.8. ftp_put_var

int ftp_put(char * hostname,
            char * username,
            char * passwd,
            char * filename,
            ftp_read_t ftp_read,
            void * ftp_read_priv,
            ftp_printf_t ftp_printf);

Use the FTP protocol to send a file to a server. Only binary mode is supported. The filename can include a directory name. Only use unix style ’/‚ file separators, not ’\‚. The ftp_read function is called to fetch data to be written, using the supplied ftp_read_priv private context. The call returns the total amount of data written, or a negative error indication.

184.1.9. Extended FTP Client API

The extended FTP Client API provides for more control of the FTP connection, including passive mode selection and timeout configuration. The extended API uses the ftp_extended_info structure to pass information into the handler functions. The use of a structure allows the data to be re-used, or individual fields modified, between calls using the API. The extended API also provides a boolean passive that if true causes the relevant API call to use a passive FTP connection, with false indicating an active FTP connection (as per the original API).

The extended API also allows for RX and TX timeouts (specified as a number of seconds) to be used for connection and data transfers. If either of the timeout fields is set to 0 then the respective CDL configuration option CYGNUM_NET_FTPCLIENT_TIMEOUT_RX and CYGNUM_NET_FTPCLIENT_TIMEOUT_TX will be used by the API operation instead.

The structure contains the following fields, which mostly mirror the individual parameter functions as used by the older (active-only) API:

struct ftp_extended_info {
  cyg_bool passive;
  char *hostname;
  char *username;
  char *passwd;
  char *filename;
  ftp_printf_t ftp_printf;
  unsigned int rx_timeout;
  unsigned int tx_timeout;
};

The extended API consists of the following functions:

184.1.10. ftp_get_extended

int ftp_get_extended(struct ftp_extended_info * info,
                     char * buf,
                     unsigned buf_size);

Use the FTP protocol to retrieve a file from a server. Only binary mode is supported. The filename can include a directory name. Only use unix style ’/‚ file separators, not ’\‚. The info parameter provides the server connection and credentials information, as well as indicating the type of connection to establish, the diagnostic and error output routine and the RX and TX timeouts. The file is placed into buf. buf has maximum size buf_size. If the file is bigger than this, the transfer fails and FTP_TOOBIG is returned. Other error codes listed in the header can also be returned. If the transfer is successful the number of bytes received is returned.

184.1.11. ftp_put_extended

int ftp_put_extended(struct ftp_extended_info * info,
                     char * buf,
                     unsigned buf_size);

Use the FTP protocol to send a file to a server. Only binary mode is supported. The filename can include a directory name. Only use unix style ’/‚ file separators, not ’\‚. The info parameter provides the server connection and credentials information, as well as indicating the type of connection to establish, the diagnostic and error output routine and the RX and TX timeouts. The contents of buf are placed into the file on the server. If an error occurs one of the codes listed will be returned. If the transfer is successful zero is returned.

184.1.12. ftp_get_extended_var

int ftp_get_extended_var(struct ftp_extended_info * info,
                         ftp_write_t ftp_write,
                         void * ftp_wrote_priv);

Use the FTP protocol to retrieve a file from a server. Only binary mode is supported. The filename can include a directory name. Only use unix style ’/‚ file separators, not ’\‚. The info parameter provides the server connection and credentials information, as well as indicating the type of connection to establish, the diagnostic and error output routine and the RX and TX timeouts. The ftp_write function is called as data arrives, using the supplied ftp_write_priv private context. If the transfer is successful the total number of bytes received is returned.

184.1.13. ftp_put_extended_var

int ftp_put_extended_var(struct ftp_extended_info * info,
                         ftp_read_t ftp_read,
                         void * ftp_read_priv);

Use the FTP protocol to send a file to a server. Only binary mode is supported. The filename can include a directory name. Only use unix style ’/‚ file separators, not ’\‚. The info parameter provides the server connection and credentials information, as well as indicating the type of connection to establish, the diagnostic and error output routine and the RX and TX timeouts. The ftp_read function is called to fetch data to be written, using the supplied ftp_read_priv private context. The call returns the total amount of data written, or a negative error indication.

184.2. FTP Client Configuration

The FTP Client provides some CDL configuration items that can be used to tune the performance and behaviour of the client.

CYGNUM_NET_FTPCLIENT_BUFSIZE
The FTP data transfer functions buffer the data as it passes between systems and this option controls the size of the dynamically allocated buffer. The buffers are allocated using the standard malloc() interface.
CYGNUM_NET_FTPCLIENT_TIMEOUT_RX
This option controls the default timeout in seconds used when waiting for connection or data reception. It is used to set the SO_RCVTIMEO for the overall control and data socket connections, as well as the individual read() operations. The CDL value can be over-ridden by a run-time supplied value when using the extended API.
CYGNUM_NET_FTPCLIENT_TIMEOUT_TX
This option controls the default timeout in seconds used when waiting for data transmissions to complete. It is used to set the SO_SNDTIMEO for the overall control and data socket connections, as well as the individual write() operations. The CDL value can be over-ridden by a run-time supplied value when using the extended API.