Core Functions for running a FTP Server on a NetBurner device. More...

Topics
	FTP Server Core Return Codes

	FTP Server File Return Codes

Initialization functions
typedef void	FTPDCallBackReportFunct(int handle, const char *name_to_report)
	FTP Session callback typedef Typedef for all directory reporting callbacks This callback type definition is used by the directory reporting functions.

int	FTPDStartSSL (uint16_t port, uint8_t server_priority, bool enableFTPS=false, bool encryptData=false)
	Starts the FTP Server task (SSL) Listens for incoming connections. Only one instance of the FTPD is allowed.

int	FTPDStart (uint16_t port, uint8_t server_priority)
	Starts the FTP Server task (non-SSL/TLS) Listens for incoming connections. Only one instance of the FTPD is allowed. If FTPD SSL support exists, FTPDStartSSL() may be used instead.

int	FTPDStopReq ()
	Stops the FTP Server task Sends a stop request to the currently running FTPD.

FTP Session callback functions that must be implemented by the programmer
void *	FTPDSessionStart (const char user, const char passwd, const IPADDR4 hi_ip)
	Start an FTP user session (User) This function is called following the creation of a new FTP session. The function needs to determine the validity of the user/password pair. The returned void pointer will be passed to all access functions, which will be asked to determine the validity of the operation based on the permissions associated with the return value.

void	FTPDSessionEnd (void *pSession)
	Indicate an FTP user session will be terminated. This callback function gives the user program the opportunity to clean up any storage associated with the void pointer returned from the FTPBSessionStart( ) call.

FTP Directory callback functions that must be implemented by the programmer
int	FTPD_DirectoryExists (const char full_directory, void pSession)
	Called by the FTP Server to test for the existence of a directory Called by the FTP Server as the result of an attempt to change to a new directory. This function can also be used to validate the permissions of the session. This function must be implemented by the programmer.

int	FTPD_CreateSubDirectory (const char current_directory, const char new_dir, void *pSession)
	Called by the FTP Server to create a directory Called by the FTP Server as the result of an attempt to create a new directory. This function can also be used to validate the permissions of the session. This function must be implemented by the programmer.

int	FTPD_DeleteSubDirectory (const char current_directory, const char sub_dir, void *pSession)
	Called by the FTP Server to delete a directory Called by the FTP Server as the result of an attempt to delete a subdirectory. This function call can be used to validate the permissions of this session. This function must be implemented by the programmer.

int	FTPD_ListSubDirectories (const char current_directory, void pSession, FTPDCallBackReportFunct *pFunc, int handle)
	Called by the FTP Server to list all subdirectories under the current directory Called by the FTP Server as the result of a client's attempt to list the contents of a directory. This function must be implemented by the programmer.

FTP file callback functions that must be implemented by the programmer
int	FTPD_FileExists (const char full_directory, const char file_name, void *pSession)
	Report on the whether or not a file exists Check for the existence of a file, usually just before an attempt is made to download the file. This function must be implemented by the programmer.

int	FTPD_GetFileSize (const char full_directory, const char file_name)
	Returns the size of a specific file.

int	FTPD_SendFileToClient (const char full_directory, const char file_name, void *pSession, int fd)
	Send the contents of a file to a file descriptor Send a file to a FTP client. This function must be implemented by the programmer.

int	FTPD_AbleToCreateFile (const char full_directory, const char file_name, void *pSession)
	Report on the ability to create/receive a file Determine if a file can be created. This function must be implemented by the programmer.

int	FTPD_GetFileFromClient (const char full_directory, const char file_name, void *pSession, int fd)
	Create/get a file Receive a file from the FTP client. This function must be implemented by the programmer.

int	FTPD_DeleteFile (const char current_directory, const char file_name, void *pSession)
	Delete a file Delete a file. This function must be implemented by the programmer.

int	FTPD_Rename (const char current_directory, const char cur_file_name, const char new_file_name, void pSession)
	Rename a file Rename a file. This function must be implemented by the programmer.

int	FTPD_ListFile (const char current_directory, void pSession, FTPDCallBackReportFunct *pFunc, int handle)
	Lists all files in the current directory List all files in the current directory. This function must be implemented by the programmer.

Detailed Description

Core Functions for running a FTP Server on a NetBurner device.

#include< ftpd.h >

The FTP Server Core Functions described in this section consist of function to start and stop the FTP server, and callback functions to handle FTP processing such as: session handling, directory and file creation, deletion and listings, etc. These core callback functions enable applications to create a FTP server in many different ways, with or without a file system.

Without a file system. Real time processing of files sent or received. For example, application data can be sent in response to a FTP client request as a text file by specifying the file type as .txt and sending the data. There are examples of this method in the "\nburn\examples\FTP" folder.

With a file system. There are 3 choices on your NetBurner platform: external flash cards (EFFS-FAT), on-chip flash memory (EFFS-STD), and ram drives. Examples of these methods are located in the "\nburn\examples\EFFS" folder. When using a file system these core functions do not need to be used directly. Since the choice has been made to use a file system rather than the callback functions, applications should use the functions described in the examples since the work of linking the callbacks to the file system has already been done for you.

Deprecated: For NetBurner customers porting from the 2.x tools to 3.x: FTP_FAIL and FTP_OK were deprecated on Jan 16, 2008. These defines were removed and all server functions (denoted as FTPD) were modified to use FTPD_OK and FTPD_FAIL. This was necessary so that the FTP client and server header files could be used at the same time. If you have any errors in your application code, you can safely change all server functions from FTP_OK/FAIL to FTPD_OK/FAIL.

Typedef Documentation

◆ FTPDCallBackReportFunct

typedef void FTPDCallBackReportFunct(int handle, const char *name_to_report)

#include <ftpd.h>

FTP Session callback typedef Typedef for all directory reporting callbacks This callback type definition is used by the directory reporting functions.

Parameters

handle	The handle passed into the listing function
name_to_report	The file name to report for use in a directory listing

Return values

FTPD_RUNNING	- The FTPD is already running
FTPD_LISTEN_ERR	- The listen socket was not able to be opened
FTPD_OK	- The FTPD was succesfully started
FTPD_FAIL	- The FTPD task could not be created

See also: FTPD_ListSubDirectories, FTPD_ListFile

Function Documentation

◆ FTPD_AbleToCreateFile()

int FTPD_AbleToCreateFile	(	const char *	full_directory,
		const char *	file_name,
		void *	pSession )

#include <ftpd.h>

Report on the ability to create/receive a file Determine if a file can be created. This function must be implemented by the programmer.

Parameters

full_directory	The current value of the session directory
file_name	The name of the file to create
pSession	The void * object returned from the FTPBSessionStart( ) function call

Return values

FTPD_OK	The requested file can be written/created
FTPD_FAIL	The requested file could not be created

See also: FTPD_FileExists, FTPD_SendFileToClient, FTPD_GetFileFromClient, FTPD_DeleteFile, FTPD_ListFile

◆ FTPD_CreateSubDirectory()

int FTPD_CreateSubDirectory	(	const char *	current_directory,
		const char *	new_dir,
		void *	pSession )

#include <ftpd.h>

Called by the FTP Server to create a directory Called by the FTP Server as the result of an attempt to create a new directory. This function can also be used to validate the permissions of the session. This function must be implemented by the programmer.

Parameters

current_directory	The current value of the session directory
new_dir	The directory to create under the current_directory
pSession	The void * object returned from the FTPBSessionStart( ) function call

Return values

FTPD_OK	The requested directory was created
FTPD_FAIL	The requested directory could not be created

See also: FTPD_DirectoryExists, FTPD_DeleteSubDirectory

◆ FTPD_DeleteFile()

int FTPD_DeleteFile	(	const char *	current_directory,
		const char *	file_name,
		void *	pSession )

#include <ftpd.h>

Delete a file Delete a file. This function must be implemented by the programmer.

Parameters

current_directory	The current value of the session directory
file_name	The name of the file to delete
pSession	The void * object returned from the FTPBSessionStart( ) function call

Return values

FTPD_OK	The requested file was deleted
FTPD_FAIL	The requested file could not be deleted

See also: FTPD_FileExists, FTPD_SendFileToClient, FTPD_AbleToCreateFile, FTPD_GetFileFromClient, FTPD_ListFile

◆ FTPD_DeleteSubDirectory()

int FTPD_DeleteSubDirectory	(	const char *	current_directory,
		const char *	sub_dir,
		void *	pSession )

#include <ftpd.h>

Called by the FTP Server to delete a directory Called by the FTP Server as the result of an attempt to delete a subdirectory. This function call can be used to validate the permissions of this session. This function must be implemented by the programmer.

Parameters

current_directory	The current value of the session current directory
sub_dir	The directory to delete under the current_directory
pSession	The void * object returned from the FTPBSessionStart( ) function call at the beginning of the session

Return values

FTPD_OK	The requested directory was deleted
FTPD_FAIL	The requested directory could not be deleted

See also: FTPD_DirectoryExists, FTPD_CreateSubDirectory

◆ FTPD_DirectoryExists()

int FTPD_DirectoryExists	(	const char *	full_directory,
		void *	pSession )

#include <ftpd.h>

Called by the FTP Server to test for the existence of a directory Called by the FTP Server as the result of an attempt to change to a new directory. This function can also be used to validate the permissions of the session. This function must be implemented by the programmer.

Parameters

full_directory	Name of the new directory to test
pSession	The void * object returned from the FTPBSessionStart( ) function call

Return values

FTPD_OK	The requested directory exists
FTPD_FAIL	The requested directory does not exist, or access is not permitted for the user

See also: FTPD_CreateSubDirectory, FTPD_DeleteSubDirectory

◆ FTPD_FileExists()

int FTPD_FileExists	(	const char *	full_directory,
		const char *	file_name,
		void *	pSession )

#include <ftpd.h>

Report on the whether or not a file exists Check for the existence of a file, usually just before an attempt is made to download the file. This function must be implemented by the programmer.

Parameters

full_directory	The current value of the session directory
file_name	The name of the file to check
pSession	The void * object returned from the FTPBSessionStart( ) function call

Return values

FTPD_OK	The requested file exists
FTPD_FAIL	The requested file does not exist

See also: FTPD_FileExists, FTPD_SendFileToClient, FTPD_AbleToCreateFile, FTPD_GetFileFromClient, FTPD_DeleteFile, FTPD_ListFile

◆ FTPD_GetFileFromClient()

int FTPD_GetFileFromClient	(	const char *	full_directory,
		const char *	file_name,
		void *	pSession,
		int	fd )

#include <ftpd.h>

Create/get a file Receive a file from the FTP client. This function must be implemented by the programmer.

Parameters

full_directory	The current value of the session directory
file_name	The name of the file to create
pSession	The void * object returned from the FTPBSessionStart( ) function call
fd	The file descriptor that will be used to receive the file

Return values

FTPD_OK	The requested file was written/created
FTPD_FAIL	The requested file was not created

See also: FTPD_FileExists, FTPD_SendFileToClient, FTPD_AbleToCreateFile, FTPD_DeleteFile, FTPD_ListFile

◆ FTPD_GetFileSize()

int FTPD_GetFileSize	(	const char *	full_directory,
		const char *	file_name )

#include <ftpd.h>

Returns the size of a specific file.

Returns: file size

Return values

FTPD_FILE_SIZE_UNKNOWN
FTPD_FILE_SIZE_NOSUCH_FILE

◆ FTPD_ListFile()

int FTPD_ListFile	(	const char *	current_directory,
		void *	pSession,
		FTPDCallBackReportFunct *	pFunc,
		int	handle )

#include <ftpd.h>

Lists all files in the current directory List all files in the current directory. This function must be implemented by the programmer.

Example: Everything inside the callback function stub must be supplied by the programmer.: The FTP server will automatically call this function and provide values for the function variables. It is the programmer's responsibility to execute pFunc( ) with the provided handle and a pointer to the string representing the file name. pFunc( ) must be executed once for each file name. In this example, the variables number_of_directories and FileNames[] must be declared and initialized elsewhere in the application program.
int FTPD_ListFile(const char * current_directory, void * pSession, FTPDCallBackReportFunct * pFunc, int handle)

{

for (int n = 0; n < numberof_files; n++)

pFunc(handle, FileNames[n]);

return FTPD_OK;

}

FTPD_ListFile
int FTPD_ListFile(const char *current_directory, void *pSession, FTPDCallBackReportFunct *pFunc, int handle)
Lists all files in the current directory List all files in the current directory. This function must ...
Definition _common/EFFS/FAT/src/ftp_f.cpp:651

FTPDCallBackReportFunct
void FTPDCallBackReportFunct(int handle, const char *name_to_report)
FTP Session callback typedef Typedef for all directory reporting callbacks This callback type definit...
Definition ftpd.h:145

FTPD_OK
#define FTPD_OK
Operation succeeded.
Definition ftpd.h:66

Parameters

current_directory	The current value of the session directory
pSession	The void * object returned from the FTPBSessionStart( ) function call
pFunc	The pointer to the callback function to be called for each file name. This is a callback function provided and used by the NetBurner internal FTP code.
handle	The handle value to be passed back into the pFunc. This is a handle provided and used by the NetBurner internal FTP code.

Return values

FTPD_OK	The requested files were listed
FTPD_FAIL	The requested file was not listed

See also: FTPD_FileExists, FTPD_SendFileToClient, FTPD_AbleToCreateFile, FTPD_GetFileFromClient, FTPD_DeleteFile

◆ FTPD_ListSubDirectories()

int FTPD_ListSubDirectories	(	const char *	current_directory,
		void *	pSession,
		FTPDCallBackReportFunct *	pFunc,
		int	handle )

#include <ftpd.h>

Called by the FTP Server to list all subdirectories under the current directory Called by the FTP Server as the result of a client's attempt to list the contents of a directory. This function must be implemented by the programmer.

Example:: Everything inside the callback function stub must be supplied by the programmer. The FTP server will automatically call this function and provide values for the function variables. It is the programmer's responsibility to execute pFunc( ) with the provided handle and a pointer to the string representing the subdirectory name. pFunc( ) must be executed once for each subdirectory name. In this example, the variables number_of_directories and DirectoryName[] must be declared and initialized elsewhere in the application program.
int FTPD_ListSubDirectories(const char * current_directory, void * pSession, FTPDCallBackReportFunct * pFunc, int handle);

{

for (int n = 0; n < number_of_dir; n++)

pFunc(handle, DirectoryName[n]);

return FTPD_OK;

}

FTPD_ListSubDirectories
int FTPD_ListSubDirectories(const char *current_directory, void *pSession, FTPDCallBackReportFunct *pFunc, int handle)
Called by the FTP Server to list all subdirectories under the current directory Called by the FTP Ser...
Definition _common/EFFS/FAT/src/ftp_f.cpp:261

Parameters

current_directory	The current value of the session current directory
pSession	The void * object returned from the FTPBSessionStart( ) function call
pFunc	The pointer to the callback function to be called for each subdirectory
handle	The handle value to be passed back into the pFunc

Return values

FTPD_OK	The requested listing was successfully delivered
FTPD_FAIL	The requested directory could not be listed

See also: FTPD_DirectoryExists, FTPD_DeleteSubDirectory, FTPD_CreateSubDirectory

◆ FTPD_Rename()

int FTPD_Rename	(	const char *	current_directory,
		const char *	cur_file_name,
		const char *	new_file_name,
		void *	pSession )

#include <ftpd.h>

Rename a file Rename a file. This function must be implemented by the programmer.

Parameters

current_directory	The current value of the session directory
cur_file_name	The name of the file to rename
new_file_name
pSession	The void * object returned from the FTPBSessionStart( ) function call

Return values

FTPD_OK	The requested file was deleted
FTPD_FAIL	The requested file could not be renamed

See also: FTPD_FileExists, FTPD_SendFileToClient, FTPD_AbleToCreateFile, FTPD_GetFileFromClient, FTPD_ListFile

◆ FTPD_SendFileToClient()

int FTPD_SendFileToClient	(	const char *	full_directory,
		const char *	file_name,
		void *	pSession,
		int	fd )

#include <ftpd.h>

Send the contents of a file to a file descriptor Send a file to a FTP client. This function must be implemented by the programmer.

Parameters

full_directory	The current value of the session directory
file_name	The name of the file to send
pSession	The void * object returned from the FTPBSessionStart( ) function call
fd	The file descriptor to send to

Return values

FTPD_OK	The requested file was sent.
FTPD_FAIL	The requested file was not sent.

See also: FTPD_FileExists, FTPD_AbleToCreateFile, FTPD_GetFileFromClient, FTPD_DeleteFile, FTPD_ListFile

◆ FTPDSessionEnd()

void FTPDSessionEnd ( void * pSession )

#include <ftpd.h>

Indicate an FTP user session will be terminated. This callback function gives the user program the opportunity to clean up any storage associated with the void pointer returned from the FTPBSessionStart( ) call.

Parameters

pSession The void * object returned from the FTPBSessionStart( ) function call

See also: FTPBSessionStart

◆ FTPDSessionStart()

void * FTPDSessionStart	(	const char *	user,
		const char *	passwd,
		const IPADDR4	hi_ip )

#include <ftpd.h>

Start an FTP user session (User) This function is called following the creation of a new FTP session. The function needs to determine the validity of the user/password pair. The returned void pointer will be passed to all access functions, which will be asked to determine the validity of the operation based on the permissions associated with the return value.

Parameters

user	The name of the user attempting to establish an FTP session
passwd	The password of the user attempting to establish an FTP session
hi_ip	The IP address of the server trying to establish this connection

Return values

NULL	The user name/password set is invalid
(obj)	A non-null void pointer to an object that will be associated with this login session

See also: FTPDSessionEnd

◆ FTPDStart()

int FTPDStart	(	uint16_t	port,
		uint8_t	server_priority )

#include <ftpd.h>

Starts the FTP Server task (non-SSL/TLS) Listens for incoming connections. Only one instance of the FTPD is allowed. If FTPD SSL support exists, FTPDStartSSL() may be used instead.

Parameters

port	The TCP port to listen to for incoming FTP requests
server_priority	The RTOS task priority for the FTP Server

Return values

FTPD_RUNNING	- The FTPD is already running
FTPD_LISTEN_ERR	- The listen socket was not able to be opened
FTPD_OK	- The FTPD was succesfully started
FTPD_FAIL	- The FTPD task could not be created

See also: FTPDStartSSL, FTPDStopReq

◆ FTPDStartSSL()

int FTPDStartSSL	(	uint16_t	port,
		uint8_t	server_priority,
		bool	enableFTPS = false,
		bool	encryptData = false )

#include <ftpd.h>

Starts the FTP Server task (SSL) Listens for incoming connections. Only one instance of the FTPD is allowed.

Parameters

port	The TCP port to listen to for incoming FTP requests
server_priority	The RTOS task priority for the FTP Server
enableFTPS
encryptData

Return values

FTPD_RUNNING	- The FTPD is already running
FTPD_LISTEN_ERR	- The listen socket was not able to be opened
FTPD_OK	- The FTPD was succesfully started
FTPD_FAIL	- The FTPD task could not be created

See also: FTPDStart, FTPDStopReq

◆ FTPDStopReq()

int FTPDStopReq ( )

#include <ftpd.h>

Stops the FTP Server task Sends a stop request to the currently running FTPD.

Return values

FTPD_RUNNING	- The FTPD is still running
FTPD_NOT_RUNNING	- The FTPD is no longer running

See also: FTPDStart, FTPDStartSSL

Topics

Initialization functions

FTP Session callback functions that must be implemented by the programmer

FTP Directory callback functions that must be implemented by the programmer

FTP file callback functions that must be implemented by the programmer

Detailed Description

Typedef Documentation

◆ FTPDCallBackReportFunct

Function Documentation

◆ FTPD_AbleToCreateFile()

◆ FTPD_CreateSubDirectory()

◆ FTPD_DeleteFile()

◆ FTPD_DeleteSubDirectory()

◆ FTPD_DirectoryExists()

◆ FTPD_FileExists()

◆ FTPD_GetFileFromClient()

◆ FTPD_GetFileSize()

◆ FTPD_ListFile()

◆ FTPD_ListSubDirectories()

◆ FTPD_Rename()

◆ FTPD_SendFileToClient()

◆ FTPDSessionEnd()

◆ FTPDSessionStart()

◆ FTPDStart()

◆ FTPDStartSSL()

◆ FTPDStopReq()