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

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.

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.

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:

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.

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.

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.

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.

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:

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.

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.

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.

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.