FTP Server Routines enable the transfer of files to a FTP Client. More...

Functions
void	ftp_server_fclose (void *file)
	Close a file previously open in FTP server.

bool	ftp_server_fdelete (const char *fname)
	Delete a file in FTP server.

uint32_t	ftp_server_ffind (uint8_t code, char buf, uint32_t buflen, const char mask)
	Search the file system directory for matching files.

void *	ftp_server_fopen (const char fname, const char mode)
	Open a file for reading or writing in FTP server.

uint32_t	ftp_server_fread (void file, uint8_t buf, uint32_t len)
	Read block of data from a file in FTP server.

bool	ftp_server_frename (const char fname, const char newname)
	Rename a file or directory in FTP server.

void	ftp_server_notify (ftpServerEvent event)
	Notify the user application about events in FTP server service.

uint32_t	ftp_server_fwrite (void file, const uint8_t buf, uint32_t len)
	Write block of data to a file in FTP server.

bool	ftp_accept_client (const uint8_t *ip_addr, uint16_t port)
	Accept or deny connection from remote FTP client.

bool	ftp_check_password (uint8_t user_id, const char *password)
	Check user account password in the user database.

uint8_t	ftp_check_username (const char *username)
	Check if an user account exist in the user database.

bool	ftp_file_access (uint8_t user_id, const char *fname, uint8_t mode)
	Check if remote user is allowed to access a file on FTP server.

uint8_t	ftp_get_user_id (void)
	Retrieve the user identification.

enum	ftpCommand { ftpPUT, ftpGET, ftpAPPEND, ftpDELETE, ftpLIST, ftpRENAME, ftpMKDIR, ftpRMDIR, ftpNLIST }
	FTP Commands. More...

enum	ftpServerEvent { ftpServerLogin, ftpServerLogout, ftpServerLoginFailed, ftpServerDownload, ftpServerUpload, ftpServerDelete, ftpServerRename, ftpServerMakeDirectory, ftpServerRemoveDirectory, ftpServerOperationDenied, ftpServerLocalFileError, ftpServerFileError, ftpServerError }
	FTP Server Events. More...

Description

FTP Server Routines enable the transfer of files to a FTP Client.

FTP routines are not reentrant.

Enumeration Type Documentation

enum ftpCommand

FTP Commands.

Parameter for:

ftp_client_connect

Enumerator:

ftpPUT	Puts a file on FTP server.
ftpGET	Retrieves a file from FTP server.
ftpAPPEND	Append file on FTP server (with create)
ftpDELETE	Deletes a file on FTP server.
ftpLIST	Lists files stored on FTP server.
ftpRENAME	Renames a file on FTP server.
ftpMKDIR	Makes a directory on FTP server.
ftpRMDIR	Removes an empty directory on FTP server.
ftpNLIST	Lists file names only (short format)

enum ftpServerEvent

FTP Server Events.

Parameter for:

ftp_server_notify

Enumerator:

ftpServerLogin	User logged in, session is busy.
ftpServerLogout	User logged out, session is idle.
ftpServerLoginFailed	User login failed (invalid credentials)
ftpServerDownload	File download ended.
ftpServerUpload	File upload ended.
ftpServerDelete	File deleted.
ftpServerRename	File or directory renamed.
ftpServerMakeDirectory	Directory created.
ftpServerRemoveDirectory	Directory removed.
ftpServerOperationDenied	Requested file operation denied.
ftpServerLocalFileError	Local file operation error.
ftpServerFileError	Generic file operation error.
ftpServerError	Generic FTP server error.

Function Documentation

bool ftp_accept_client	(	const uint8_t *	ip_addr,
		uint16_t	port
	)

Accept or deny connection from remote FTP client.

Parameters

[in]	ip_addr	IP address of the remote FTP client.
[in]	port	port number of the remote FTP client.

Returns

true = Connection from the remote client is allowed.
false = Connection is denied.

The function ftp_accept_client checks if a connection from the remote client is allowed or not. This enables remote client filtering. You can selectively decide which clients are allowed to connect to the FTP server and which are not.

The argument ip_addr points to a buffer containing the four octets that make up the IP address of the remote machine.

The argument port specifies the port on the remote machine.

The function is in the FTP_Server_Access.c module.

Note: This function is optional. If it does not exist in the project, then the library default function is used. The library default function accepts all remote clients.

Code Example

#include "rl_net.h"
 
// Accept or deny connection from remote FTP client.
// If this function is missing, all remote clients are accepted.
bool ftp_accept_client (const uint8_t *ip_addr, uint16_t port) {
  /* Example
  if (ip_addr[0] == 192  &&
      ip_addr[1] == 168  &&
      ip_addr[2] == 0    &&
      ip_addr[3] == 1) {
    // Accept connection.
    return (true);
  }
  // Deny connection.
  return (false);
  */
  return (true);
}

bool ftp_check_password	(	uint8_t	user_id,
		const char *	password
	)

Check user account password in the user database.

Parameters

[in]	user_id	user identification number.
[in]	password	pointer to password.

Returns

true = password accepted.
false = invalid password.

The function ftp_check_password authenticates the password for a specified user ID.

The argument user_id is the identification number of a user.

The argument password points to the password that gets checked.

Note: The function can be adapted to the application's needs by adding the FTP_Server_Multiuser.c file to the project.

Code Example

#include <string.h>
#include "rl_net.h"
  
// Check user account password in the user database.
bool ftp_check_password (uint8_t user_id, const char *password) {
  if (user_id == 1) {
    if (strcmp (password, "guest") == 0) {
      // Password is correct
      return (true);
    }
  }
  return (false);
}

uint8_t ftp_check_username ( const char * username )

Check if an user account exist in the user database.

Parameters

[in] username pointer to username.

Returns

status information:

User identification number or
0 if the user is not existing.

The function ftp_check_username authenticates the username and returns the corresponding identification number.

The argument username points to the user name. A value of 0 is returned if the user does not exist.

Note: The function can be adapted to the application's needs by adding the FTP_Server_Multiuser.c file to the project.

Code Example

#include <string.h>
#include "rl_net.h"
 
// Check if an user account exist in the user database.
uint8_t ftp_check_username (const char *username) {
  if (strcmp (username, "guest") == 0) {
    // Username is correct
    return (1);
  }
  return (0);
}

bool ftp_file_access	(	uint8_t	user_id,
		const char *	fname,
		uint8_t	mode
	)

Check if remote user is allowed to access a file on FTP server.

Parameters

[in]	user_id	user identification number.
[in]	fname	name of a file to access.
[in]	mode	access mode: 0 = Read a file. 1 = Write a file. 2 = Create or remove a directory. 3 = List file directory.

Returns

true = File access is allowed.
false = File access is denied.

The function ftp_file_access checks if file access is allowed for a specific user. This allows access protection of sensitive files. The access to protected files will be blocked for unprivileged users. The error code "550 Access is denied" will be returned to the client if access is not allowed.

The argument user_id is the user identification number as returned by ftp_check_username. user_id identifies the user who is trying to access the specified file.

The argument fname points to a buffer containing the file name which should be accessed. The file name is a 0-terminated string.

The argument mode specifies the requested type of file access.

The function is in the FTP_Server_Multiuser.c module.

Note: This function is optional. If the FTP file access restriction is not used, this function is not required.

Code Example

#include <string.h>
#include "rl_net.h"
 
// Check if remote user is allowed to access a file on FTP server.
bool ftp_file_access (uint8_t user_id, const char *fname, uint8_t mode) {
  if (user_id == 1) {
    if ((strcmp (fname, "/log/test.txt") == 0) && (mode == 1)) {
      // User "guest" is not allowed to modify or delete "test.txt" in "log" folder
      return (false);
    }
  }
  return (true);
}

uint8_t ftp_get_user_id ( void )

Retrieve the user identification.

Returns: user identification number (0 = system administrator).

The function ftp_get_user_id retrieves the user identification number.

Note: This function returns a value of 0 for system administrator account.

Code Example

//coming soon

void ftp_server_fclose ( void * file )

Close a file previously open in FTP server.

Parameters

[in] file pointer to the file to close.

Returns: none.

The function ftp_server_fclose closes the file identified by the file stream pointer in the function argument.

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_Server_FS.c module.

bool ftp_server_fdelete ( const char * fname )

Delete a file in FTP server.

Parameters

[in] fname name of the file to delete.

Returns

true = File successfully deleted.
false = Failed to delete a file.

The function ftp_server_fdelete deletes the file specified by fname from the server.

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_Server_FS.c module.

uint32_t ftp_server_ffind	(	uint8_t	code,
		char *	buf,
		uint32_t	buflen,
		const char *	mask
	)

Search the file system directory for matching files.

Parameters

[in]	code	request type code: 0 = Retrieve file size. 1 = Retrieve last-modified time of a file. 2 = List files by name, first call. 3 = List files in extended format, first call. 4 = List files by name, subsequent call. 5 = List files in extended format, subsequent call.
[out]	buf	output buffer to write the listing to.
[in]	buflen	length of the output buffer in bytes.
[in]	mask	file mask filter.

Returns: number of bytes written to output buffer.

The function ftp_server_ffind searches the File System directory for files matching the specified mask filter mask. Matching file information is stored to the output buffer buf. The output data must be formatted in the FTP folder listing format.

The argument code specifies the request type:

Code	Request Type
0	Read file size.
1	Read last-modified time of a file.
2	List file names only (first call).
3	List file directory in extended format (first call).
4	List file names only (subsequent call).
5	List file directory in extended format (subsequent call).

The argument buflen specifies the size of output buffer buf.

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_Server_FS.c module.

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

Open a file for reading or writing in FTP server.

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_server_fopen opens a file for reading or writing.

The argument fname specifies the name of the file to open.

The argument mode defines the type of access permitted for the file. The argument 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 does not exist. 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_Server_FS.c module.

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

Read block of data from a file in FTP server.

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_server_fread reads len bytes from the file file stream pointer specified in the function argument.

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

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_Server_FS.c module.

Note: The function must read len bytes. The FTP Server stops reading and closes the file if the return value is less than len bytes.

bool ftp_server_frename	(	const char *	fname,
		const char *	newname
	)

Rename a file or directory in FTP server.

Parameters

[in]	fname	old name to rename from.
[in]	newname	new name to rename to.

Returns

true = File or directory successfully renamed.
false = Failed to rename a file or directory.

The function ftp_server_frename renames the file name fname to newname on the server.

The argument fname must be the name of an existing file.

The argument newname must be a valid file name that does not exist in the scope.

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_Server_FS.c module.

Note: A name with a trailing '\' character denotes a directory.

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

Write block of data to a file in FTP server.

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.

The function ftp_server_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_Server_FS.c module.

void ftp_server_notify ( ftpServerEvent event )

Notify the user application about events in FTP server service.

Parameters

[in] event FTP Server notification event

Returns: none.

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

The function ftp_server_notify notifies the user application about events in FTP server. This function is useful to synchronize various actions, such as firmware upgrade, to FTP server events. The firmware upgrade might start after the ftpServerLogout event is signalled and a new firmware image file has been uploaded to the server.

Code Example

void ftp_server_notify (ftpServerEvent event) {
  // Notify the user application about events in FTP server.
  switch (event) {
    case ftpServerLogin:
      // User logged in, FTP session is busy. 
      break;
    case ftpServerLogout;
      // User logged out, session is idle. 
      break;
    case ftpServerLoginFailed:
      // User login failed (invalid credentials). 
      break;
    case ftpServerDownload:
      // File download ended. 
      break;
    case ftpServerUpload:
      // File upload ended. 
      break;
    case ftpServerDelete:
      // File deleted. 
      break;
    case ftpServerRename:
      // File or directory renamed. 
      break;
    case ftpServerMakeDirectory:
      // Directory created. 
      break;
    case ftpServerRemoveDirectory:
      // Directory removed. 
      break;
    case ftpServerOperationDenied:
      // Requested file operation denied. 
      break;
    case ftpServerLocalFileError:
      // Local file operation error. 
      break;
    case ftpServerFileError:
      // Generic file operation error. 
      break;
    case ftpServerError:
      // Generic FTP server error. 
      break;
  }
}

Functions

Description

Enumeration Type Documentation

Function Documentation