FTP Client

The FTP client allows you to connect to a remote FTP server and perform various file operations. Using the FTP client you can:

• transfer files from local system to remote FTP server,
• transfer files from remote FTP server to a local system,
• append a local file to remote file on FTP server,
• delete a file from the FTP server,
• list the files stored on FTP server,
• rename a file or directory on FTP server,
• create a directory on FTP server,
• remove a directory from FTP server.

The FTP client session starts with a connect request. The FTP client then opens a FTP connection to the server. The file operation to perform is specified in the connect request parameter. Once the file operation has completed, the FTP session ends and the connection closes. FTP session performs only one file operation. If you want to transfer more files, you need to start FTP session again.

File System Interface

All File System interface functions are located in FTP_Client_FS.c, which will be automatically added to your project's Network folder. The file is preconfigured for the File System Component, so no modifications are required. If you want to use another type of file system or to use a different storage media such as a hard disk, you need to add a similar file to your project.

The following functions are implemented in this module:

• ftp_client_fopen - open a file for reading or writing.
• ftp_client_fclose - close a file that was previously opened.
• ftp_client_fread - read a block of data from a file to the FTP data buffer.
• ftp_client_fwrite - write a block of data from the FTP data buffer to a file.

FTP Client Session Operation

All required session parameters are given in the ftp_client_request callback function. This function is in the FTP_Client_UIF.c module. From the callback function, you can specify the username/password to access the FTP server, a working directory on the FTP server, a filename for the file operation, etc.

The FTP Client's operation mode is working with a relative path. This means the filename can not contain a path information. Instead of this, a working directory must be specified in the FTP_Client_UIF.c user interface module. After login, the FTP Client first changes the working directory to the path specified in user interface module, and then performs a file command. To add the module to your project, simply right-click on the Source group, select Add Net Item to Group, then click on User Code Template and scroll in the template files list until you find the FTP Client User Interface template. The FTP Client also supports directory manipulation and rename commands. This allows you to create or remove directories, and to rename files or directories on the server.

The following function is included in the Network Component library rl_net.h:

• ftp_client_request - request parameters for FTP client session.

User Application Notification

The end of a FTP Client operation can be notified to the user utilizing the ftp_client_notify function. It is part of the file FTP_Client_UIF.c module as well. You need to adapt the function to the application's needs.

Code Example FTP_Client_UIF.c

#include <stdio.h>
#include "rl_net.h"
 
// Request parameters for FTP client session.
uint32_t ftp_client_request (ftpClientRequest request, char *buf, uint32_t len) {
  uint32_t rlen = 0;
//int32_t i;
 
  switch (request) {
    case ftpClientUsername:
      // Username to login to FTP server
      /* Example
      rlen = sprintf (buf, "anonymous");
      */
      break;

    case ftpClientPassword:
      // Password to login to FTP server
      /* Example
      rlen = sprintf (buf, "test@keil.com");
      */
      break;

    case ftpClientPath:
      // Working directory path on server
      /* Example
      rlen = sprintf (buf, "/Logs");
      */
      break;

    case ftpClientFilename:
      // Filename for PUT, GET, APPEND, DELETE or RENAME command
      /* Example
      rlen = sprintf (buf, "test.log");
      */
      break;

    case ftpClientNewName:
      // New name for a RENAME command
      /* Example
      rlen = sprintf (buf, "renamed.log");
      */
      break;

    case ftpClientDirectory:
      // Directory name for MKDIR or RMDIR command
      /* Example
      rlen = sprintf (buf, "New_Folder");
      */
      break;

    case ftpClientFilterMask:
      // File filter/mask for LIST command (wildcards allowed)
      /* Example
      rlen = sprintf (buf, "");
      */
      break;

    case ftpClientList:
      // Received data if LIST command is given
      /* Example
      for (i = 0; i < len; i++) {
        putchar (buf[i]);
      }
      */
      break;

    case ftpClientLocalFile:
      // Local filename
      /* Example
      rlen = sprintf (buf, "test_log.txt");
      */
      break;
  }
  return (rlen);
}
 
// Notify the user application when FTP client operation ends.
void ftp_client_notify (ftpClientEvent event) {
  switch (event) {
    case ftpClientSuccess:
      // File operation successful
      break;
    case ftpClientTimeout:
      // Timeout on file operation
      break;
    case ftpClientLoginFailed:
      // Login error, username/password invalid
      break;
    case ftpClientAccessDenied:
      // File access not allowed
      break;
    case ftpClientFileNotFound:
      // File not found
      break;
    case ftpClientInvalidPath:
      // Working directory path not found
      break;
    case ftpClientLocalFileError:
      // Local file open/write error
      break;
    case ftpClientError:
      // Generic FTP client error
      break;
  }
}

FTP Client Configuration

FTP Client Configuration File

The FTP client configuration file Net_Config_FTP_Client.h contains the following settings:

• Response Timeout in seconds is an inactivity timeout. When the FTP client does not receive a response from a FTP server within this timeout, the operation is aborted.
• In Passive mode (PASV), the FTP client initiates both connections (control and data) to the server. This solves the problem of firewalls filtering the incoming data port connection to the client from the server.

Note

One FTP session uses two TCP sockets, one control and one data socket. Have this in mind when you are configuring the number of TCP sockets.