FTP Client Routines

FTP Client Routines provide access to a FTP Server. More...

Functions
netStatus	ftp_client_connect (const uint8_t *ip_addr, uint16_t port, ftpCommand command)
	Start FTP client file operation session.
void	ftp_client_fclose (void *file)
	Close local file previously open in FTP client.
void *	ftp_client_fopen (const char *fname, const char *mode)
	Open local file for reading or writing in FTP client.
uint32_t	ftp_client_fread (void *file, uint8_t *buf, uint32_t len)
	Read block of data from local file in FTP client.
uint32_t	ftp_client_fwrite (void *file, const uint8_t *buf, uint32_t len)
	Write block of data to local file in FTP client.
void	ftp_client_notify (ftpClientEvent event)
	Notify the user application when FTP client operation ends.
uint32_t	ftp_client_request (ftpClientRequest request, char *buf, uint32_t len)
	Request parameters for FTP client session.
enum	ftpClientRequest {   ftpClientUsername,   ftpClientPassword,   ftpClientPath,   ftpClientFilename,   ftpClientNewName,   ftpClientDirectory,   ftpClientFilterMask,   ftpClientList,   ftpClientLocalFile }
	FTP Client Requests. More...
enum	ftpClientEvent {   ftpClientSuccess = 0,   ftpClientTimeout,   ftpClientLoginFailed,   ftpClientAccessDenied,   ftpClientFileNotFound,   ftpClientInvalidPath,   ftpClientLocalFileError,   ftpClientError }
	FTP Client Events. More...

Description

FTP Client Routines provide access to a FTP Server.

FTP routines are not reentrant.

Enumeration Type Documentation

enum ftpClientEvent

FTP Client Events.

Parameter for:

• ftp_client_notify

Enumerator:

ftpClientSuccess	File operation successful.
ftpClientTimeout	Timeout on file operation.
ftpClientLoginFailed	Login error, username/password invalid.
ftpClientAccessDenied	File access not allowed.
ftpClientFileNotFound	File not found.
ftpClientInvalidPath	Working directory path not found.
ftpClientLocalFileError	Local file open/write error.
ftpClientError	Generic FTP client error.

enum ftpClientRequest

FTP Client Requests.

Parameter for:

• ftp_client_request

Enumerator:

ftpClientUsername	Username to login to FTP server.
ftpClientPassword	Password to login to FTP server.
ftpClientPath	Working directory path on server.
ftpClientFilename	Filename for PUT, GET, APPEND, DELETE or RENAME command.
ftpClientNewName	New name for a RENAME command.
ftpClientDirectory	Directory name for MKDIR or RMDIR command.
ftpClientFilterMask	File filter/mask for LIST command (wildcards allowed)
ftpClientList	Received data if LIST command is given.
ftpClientLocalFile	Local filename.

Function Documentation

netStatus ftp_client_connect	(	const uint8_t *	ip_addr,
		uint16_t	port,
		ftpCommand	command
	)

Start FTP client file operation session.

Parameters

[in]	ip_addr	IP address of remote FTP server.
[in]	port	port number of FTP server.
[in]	command	FTP command to perform.

Returns

status code that indicates the execution status of the function as defined with netStatus.

The function ftp_client_connect starts the FTP client. The FTP client then connects to a FTP server on the TCP port. If the port is not specified (argument port has a value of 0), then the system uses a standard FTP server port for connecting.

The argument ip_addr points to an array of 4 bytes containing the dotted-decimal notation of the IP address of the FTP server.

The argument port is the FTP server port to connect to.

The argument command specifies a command that is preformed when the FTP client connects to the FTP server. The following commands are supported:

Command	Description
ftpPUT	Puts a local file from local system to FTP server
ftpGET	Retrieves a file from FTP server to save as a local file
ftpAPPEND	Appends a local file to an existing file on FTP server
ftpDELETE	Deletes a file from FTP server
ftpLIST	Lists files located on FTP server (including detailed information)
ftpRENAME	Renames a file or directory on FTP server
ftpMKDIR	Creates a new directory on FTP server
ftpRMDIR	Deletes an empty directory on FTP server
ftpNLIST	Lists file names located on FTP server (names only)

Note

The default FTP server port is TCP port 21.

Code Example

void file_transfer (void) {
  const uint8_t srvip[4] = {192,168,2,253};
 
  if (ftp_client_connect (srvip, 21, ftpPUT) != netOK) {
    printf("Connect failed, the client is busy.\n");
  }
  else {
    printf("FTP client started.\n");
  }
}

void ftp_client_fclose

(

void *

file

)

Close local file previously open in FTP client.

Parameters

[in]

file

pointer to the file to close.

Returns

none.

The function ftp_client_fclose closes the file identified by the file stream pointer.

The function interfaces to the File System Component and will be called by the Network Component automatically. If another file system will be used, refer to the reference implementation in the FTP_Client_FS.c module.

void * ftp_client_fopen	(	const char *	fname,
		const char *	mode
	)

Open local file for reading or writing in FTP client.

Parameters

[in]	fname	name of the file to open.
[in]	mode	type of access: "rb" = opens a file for reading. "wb" = opens a file for writing.

Returns

status information:

• Pointer to an open file or
• NULL in case of an error.

The function ftp_client_fopen opens a local file for reading or writing.

The argument mode defines the type of access permitted for the file fname. mode can have one of the following values:

Mode	Description
"rb"	Opens the file for reading. If the file does not exist, fopen fails.
"wb"	Opens an empty file for writing. If the file already exists, its contents are cleared.

The function interfaces to the File System Component and will be called by the Network Component automatically. If another file system will be used, refer to the reference implementation in the FTP_Client_FS.c module.

uint32_t ftp_client_fread	(	void *	file,
		uint8_t *	buf,
		uint32_t	len
	)

Read block of data from local file in FTP client.

Parameters

[in]	file	pointer to the file to read from.
[out]	buf	block of memory to write data to.
[in]	len	length of data to read in bytes.

Returns

number of bytes successfully read.

The function ftp_client_fread reads len bytes from the file identified by the file stream pointer in the function argument.

The argument buf is a pointer to the buffer where the function stores the data read.

The function interfaces to the File System Component and will be called by the Network Component automatically. If another file system will be used, refer to the reference implementation in the FTP_Client_FS.c module.

uint32_t ftp_client_fwrite	(	void *	file,
		const uint8_t *	buf,
		uint32_t	len
	)

Write block of data to local file in FTP client.

Parameters

[in]	file	pointer to the file to write to.
[in]	buf	block of memory to be written.
[in]	len	length of data to write in bytes.

Returns

number of bytes successfully written.

Note

FTP client stops writing and closes the file, if the return value is less than len bytes.

The function ftp_client_fwrite writes a block of data to the file identified by the file stream pointer.

The argument buf points to the buffer containing the data that is to be written to the file.

The argument len specifies the number of bytes to write to the file.

The function interfaces to the File System Component and will be called by the Network Component automatically. If another file system will be used, refer to the reference implementation in the FTP_Client_FS.c module.

Note

The function must write len bytes. The FTP Client stops writing, aborts data transfer and closes the FTP session if the return value is less than len bytes.

void ftp_client_notify

(

ftpClientEvent

event

)

Notify the user application when FTP client operation ends.

Parameters

[in]

event

FTP client notification event

Returns

none.

Note

This function is called by the system to inform about events.

The function ftp_client_notify is called automatically when an FTP event occurred and notifies the user application when the FTP client operation ends.

The argument event is a ftpClientEvent signal:

Event	Description
ftpClientSuccess	The file operation completed successfully
ftpClientTimeout	FTP Server response has timed out, and hence the FTP client has aborted the operation
ftpClientLoginFailed	The FTP client failed to login to FTP server
ftpClientAccessDenied	The file access to a specified file is not allowed
ftpClientFileNotFound	The requested file was not found on FTP server
ftpClientInvalidPath	Working directory path not found on FTP server
ftpClientLocalFileError	File open or file write error on local system
ftpClientError	An error encountered during the file operation

You can customize the function in FTP_Client_UIF.c module.

Code Example

#include <stdio.h>
#include "rl_net.h"
 
// 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;
  }
}

uint32_t ftp_client_request	(	ftpClientRequest	request,
		char *	buf,
		uint32_t	len
	)

Request parameters for FTP client session.

Parameters

[in]	request	request code.
[out]	buf	output buffer to write the data to.
[in]	len	length of the output buffer in bytes.

Returns

number of bytes written to output buffer.

The function ftp_client_request provides additional parameters for the FTP client session such as the credentials to login to the FTP server, local and remote file name for the file operation, etc. The FTP client calls this function several times to complete the file operation requested.

The argument request specifies the type of additional information (user, password, file name, etc.) that the FTP Client requires:

Type	Description
ftpClientUsername	Username for FTP authentication
ftpClientPassword	Password for FTP authentication
ftpClientDirectory	Working directory path for all commands
ftpClientFilename	Filename for PUT, GET, APPEND, DELETE or RENAME commands
ftpClientNewName	New filename for RENAME command
ftpClientPath	A directory name for MKDIR or RMDIR command
ftpClientFilterMask	A file filter/mask for the LIST command
ftpClientList	Received directory listing when the LIST command was given

The argument buf is a pointer to the output buffer where the function writes the requested data.

The argument buflen specifies the length of the output buffer in bytes.

The function is in the FTP_Client_UIF.c module.

Note

• The length of the output buffer, buflen, might vary because it is determined by the TCP socket Maximum Segment Size (MSS) negotiation. It is normally 1460 bytes for local LAN.
• If the function writes more bytes than buflen into the output buffer, then a system crash resulting from corruption of memory link pointers is highly likely.

Code Example

#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;
  }
}