FTP Server Callback

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.
int	FTPDStartSSL (uint16_t port, uint8_t server_priority, bool enableFTPS=false, bool encryptData=false)
	Starts the FTP Server task with SSL/TLS support.
int	FTPDStart (uint16_t port, uint8_t server_priority)
	Starts the FTP Server task (non-SSL/TLS).
int	FTPDStopReq ()
	Stops the FTP Server task.

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.
void	FTPDSessionEnd (void *pSession)
	Indicate an FTP user session will be terminated.

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.
int	FTPD_CreateSubDirectory (const char *current_directory, const char *new_dir, void *pSession)
	Called by the FTP Server to create a directory.
int	FTPD_DeleteSubDirectory (const char *current_directory, const char *sub_dir, void *pSession)
	Called by the FTP Server to delete a directory.
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.

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 whether or not a file exists.
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.
int	FTPD_AbleToCreateFile (const char *full_directory, const char *file_name, void *pSession)
	Report on the ability to create/receive a file.
int	FTPD_GetFileFromClient (const char *full_directory, const char *file_name, void *pSession, int fd)
	Receive a file from the FTP client.
int	FTPD_DeleteFile (const char *current_directory, const char *file_name, void *pSession)
	Delete a file.
int	FTPD_Rename (const char *current_directory, const char *cur_file_name, const char *new_file_name, void *pSession)
	Rename a file.
int	FTPD_ListFile (const char *current_directory, void *pSession, FTPDCallBackReportFunct *pFunc, int handle)
	Lists all files in the current directory.

Detailed Description

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

#include< ftpd.h>

Overview

The FTP Server Callback API provides a framework for implementing an FTP server by supplying a set of callback functions. The server handles the FTP protocol (command parsing, data connections, etc.), while your application controls authentication, directory structure, and file content through the callbacks.

This design allows FTP servers to operate with or without a traditional file system:

Without a file system: Application data can be served directly in response to FTP client requests. For example, real-time sensor data can be presented as a downloadable text file, or uploaded data can be processed on the fly. See the examples in \nburn\examples\FTP for this approach.

With a file system: When using EFFS-FAT (external flash cards), EFFS-STD (on-chip flash), or RAM drives, the callback-to-filesystem linkage is already provided. See the examples in \nburn\examples\EFFS for these implementations. In this case, applications do not need to implement the callbacks directly.

Callback Functions

The following callback functions must be implemented by the application programmer when using the Callback API directly:

Session callbacks:

• FTPDSessionStart() — Authenticate users and create session context
• FTPDSessionEnd() — Clean up session resources

Directory callbacks:

• FTPD_DirectoryExists() — Validate directory paths
• FTPD_CreateSubDirectory() — Handle mkdir requests
• FTPD_DeleteSubDirectory() — Handle rmdir requests
• FTPD_ListSubDirectories() — Report subdirectory names for listings

File callbacks:

• FTPD_FileExists() — Check if a file exists
• FTPD_GetFileSize() — Report file sizes
• FTPD_SendFileToClient() — Send file data to FTP clients (download)
• FTPD_AbleToCreateFile() — Check if a file can be created
• FTPD_GetFileFromClient() — Receive file data from FTP clients (upload)
• FTPD_DeleteFile() — Delete files
• FTPD_Rename() — Rename files
• FTPD_ListFile() — Report file names for directory listings

Basic Usage Pattern

1. Implement all required callback functions
2. Call FTPDStart() to start the FTP server task
3. The server handles incoming FTP connections and invokes your callbacks as needed
4. Optionally call FTPDStopReq() to shut down the server

---

Expand for Example Usage

Examples

Example: Starting the FTP server

#include <ftpd.h>
#include <init.h>
#include <nbrtos.h>
 
void UserMain(void *pd)
{
    init();
    WaitForActiveNetwork(TICKS_PER_SECOND * 5);
 
    // Start FTP server on port 21 at one priority below main
    int result = FTPDStart(21, MAIN_PRIO - 1);
    if (result == FTPD_OK) { iprintf("FTP Server started\r\n"); }
 
    while (1) { OSTimeDly(TICKS_PER_SECOND); }
}

Example: Minimal session authentication callback

void *FTPDSessionStart(const char *user, const char *passwd, const IPADDR4 hi_ip)
{
    // Accept any user/password combination
    return (void *)1;   // Non-null = session accepted
}
 
void FTPDSessionEnd(void *pSession)
{
    // No session resources to clean up
}

---

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 and file listing report callbacks. This callback type definition is used by the directory and file reporting functions. The FTP server calls the provided function pointer once for each item (subdirectory or file) to report.

Parameters

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

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. Called before FTPD_GetFileFromClient() to verify permissions and storage availability. 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 FTPDSessionStart() 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 FTPDSessionStart() 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 on the FTP server. This function can also be used to validate session permissions. 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 FTPDSessionStart() 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 FTPDSessionStart() function call

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 FTPDSessionStart() 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_ListSubDirectories()

FTPD_FileExists()

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

#include <ftpd.h>

Report on 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 can also be used to validate session permissions. 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 FTPDSessionStart() function call

Return values

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

See also

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>

Receive a file from the FTP client.

Receive file data uploaded by the FTP client. Use standard file I/O read functions such as read() or ReadWithTimeout() to read data from the provided file descriptor. 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 FTPDSessionStart() 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.

Called by the FTP server in response to a SIZE command from the 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 query

Returns

The file size in bytes if the file exists

Return values

FTPD_FILE_SIZE_NOSUCH_FILE	The file does not exist
FTPD_FILE_SIZE_UNKNOWN	The file exists but its size is unknown

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. The application must call pFunc() once for each file to report. The string passed to pFunc() should be a formatted directory listing string that includes permissions, size, date, and file name. This function must be implemented by the programmer.

Parameters

current_directory	The current value of the session directory
pSession	The void * object returned from the FTPDSessionStart() 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 files could not be listed

See also

FTPD_FileExists(), FTPD_SendFileToClient(), FTPD_AbleToCreateFile(), FTPD_GetFileFromClient(), FTPD_DeleteFile()

---

Expand for Example Usage

Examples

Example: Reporting file names

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 numberof_files 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_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. The application must call pFunc() once for each subdirectory name to report. This function must be implemented by the programmer.

Parameters

current_directory	The current value of the session current directory
pSession	The void * object returned from the FTPDSessionStart() 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_ListFile()

---

Expand for Example Usage

Examples

Example: Reporting subdirectory names

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_dir 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_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 on the FTP server. This function must be implemented by the programmer.

Parameters

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

Return values

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

See also

FTPD_FileExists(), FTPD_DeleteFile()

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. Use standard file I/O write functions such as write(), writeall(), or writestring() to send data to the provided file descriptor. 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 FTPDSessionStart() function call
fd	The file descriptor to send data 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 FTPDSessionStart() call.

Parameters

pSession

The void * object returned from the FTPDSessionStart() function call

See also

FTPDSessionStart()

FTPDSessionStart()

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

#include <ftpd.h>

Start an FTP user session.

This callback 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 client 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 successfully 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 with SSL/TLS support.

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	Enable explicit FTPS (AUTH TLS) support (default: false)
encryptData	Encrypt data channel in addition to control channel (default: false)

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 successfully 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()