FTP Client

Functions
int	FTP_InitializeSession (IPADDR4 server_address, uint16_t port, PCSTR UserName, PCSTR Password, uint32_t time_out)
	Initialize a FTP session with a FTP server.
int	FTP_CloseSession (int session)
	Close a FTP session.
int	FTPGetDir (int ftp_Session, char *dir_buf, int nbytes, uint16_t timeout)
	Get the current working directory.
int	FTPSetDir (int ftp_Session, const char *new_dir, uint16_t timeout)
	Set the current working directory.
int	FTPDeleteDir (int ftp_Session, const char *dir_to_delete, uint16_t timeout)
	Delete a directory.
int	FTPMakeDir (int ftp_Session, const char *dir_to_make, uint16_t timeout)
	Create a new directory.
int	FTPUpDir (int ftp_Session, uint16_t timeout)
	Move up one directory level.
int	FTPDeleteFile (int ftp_Session, const char *file_name, uint16_t timeout)
	Delete a file.
int	FTPRenameFile (int ftp_Session, const char *old_file_name, const char *new_file_name, uint16_t timeout)
	Rename a file.
int	FTPSendFile (int ftp_Session, const char *full_file_name, BOOL bBinaryMode, uint16_t timeout)
	Initialize the process to send a file to a FTP server.
int	FTPGetFile (int ftp_Session, const char *full_file_name, BOOL bBinaryMode, uint16_t timeout)
	Initialize the process to get a file from a FTP server.
int	FTPGetList (int ftp_Session, const char *full_dir_name, uint16_t timeout)
	Initialize the process to receive a directory listing from a FTP server.
int	FTPGetFileNames (int ftp_Session, const char *full_dir_name, uint16_t timeout)
	Initialize the process to receive just the file names in a directory from a FTP server.
int	FTPRawCommand (int ftp_Session, const char *cmd, char *cmd_buf, int nbytes, uint16_t timeout)
	Send a FTP command to the FTP server.
int	FTPGetCommandResult (int ftp_Session, char *cmd_buf, int nbytes, uint16_t timeout)
	Returns the result of the last FTP operation.
int	FTPRawStreamCommand (int ftp_Session, const char *cmd, int *pResult, char *cmd_buf, int nbytes, uint16_t timeout)
	Send a command and receive a response over a stream connection.
void	FTPActiveMode (int ftp_Session)
	Set the data connection mode to active (PORT).
void	FTPPassiveMode (int ftp_Session)
	Set the data connection mode to passive (PASV).

FTP Client Return Codes
#define	FTP_OK   (0)
	OK.
#define	FTP_TIMEOUT   (-1)
	Timeout.
#define	FTP_PASSWORDERROR   (-2)
	Password error.
#define	FTP_CONNECTFAIL   (-3)
	Connection failed.
#define	FTP_COMMANDFAIL   (-4)
	Command failed.
#define	FTP_COMMANDERROR   (-4)
	Command error.
#define	FTP_BADSESSION   (-5)
	Bad session.
#define	FTP_NETWORKERROR   (-6)
	Network error.

Detailed Description

#include< ftp.h>

Overview

The NetBurner FTP Client API provides a session-based interface for communicating with remote FTP servers. A session is established by calling FTP_InitializeSession(), which returns a session handle used by all subsequent operations. Multiple concurrent sessions to different servers are supported.

Key Features:

• Session Management: Connect/disconnect to remote FTP servers with username/password authentication
• File Transfer: Send and receive files in binary or ASCII mode via stream-based file descriptors
• Directory Operations: Create, delete, navigate, and list remote directories
• Active and Passive Modes: Support for both FTP data connection modes
• Raw Commands: Send arbitrary FTP commands for protocol-level control

Basic Usage Pattern

1. Call FTP_InitializeSession() to connect and authenticate with a remote FTP server
2. Perform file and directory operations using the returned session handle
3. Call FTP_CloseSession() to disconnect and free resources

Stream-Based File Transfers

The file transfer functions FTPSendFile(), FTPGetFile(), FTPGetList(), and FTPGetFileNames() return a TCP file descriptor rather than transferring data directly. After obtaining the file descriptor:

1. Use standard file I/O functions (read(), write(), writestring(), etc.) to transfer data
2. Close the file descriptor with close()
3. Call FTPGetCommandResult() to verify the operation completed successfully

Timeout Values

All timeout parameters are specified in system Time Ticks. Use the TICKS_PER_SECOND constant to specify timeouts in seconds. For example, 5 * TICKS_PER_SECOND for a 5-second timeout.

Return Values

Most functions return ftpClientReturnCodes on failure (negative values). Functions that return handles or file descriptors return a positive value on success. Always check the return value before proceeding.

---

Expand for Example Usage

Examples

Example: Complete FTP session lifecycle

#include <ftp.h>
 
// Connect to FTP server
int ftpSession = FTP_InitializeSession(serverIp, 21, "username", "password", 10 * TICKS_PER_SECOND);
if (ftpSession > 0)
{
    // Navigate to a directory
    FTPSetDir(ftpSession, "/uploads", 5 * TICKS_PER_SECOND);
 
    // Send a file
    int fd = FTPSendFile(ftpSession, "data.txt", FALSE, 5 * TICKS_PER_SECOND);
    if (fd > 0)
    {
        writestring(fd, "Hello from NetBurner\r\n");
        close(fd);
 
        char resultBuf[80];
        int rv = FTPGetCommandResult(ftpSession, resultBuf, 80, 5 * TICKS_PER_SECOND);
        if (rv != 226) { iprintf("Send error: %d %s\r\n", rv, resultBuf); }
    }
 
    // Disconnect
    FTP_CloseSession(ftpSession);
}

---

Function Documentation

FTP_CloseSession()

int FTP_CloseSession

(

int

session

)

#include <ftp.h>

Close a FTP session.

Sends the FTP QUIT command and closes the TCP connection to the FTP server. This function should always be called when done with a session to free resources.

Parameters

session

FTP session number to close

Returns

ftpClientReturnCodes

See also

FTP_InitializeSession()

FTP_InitializeSession()

int FTP_InitializeSession	(	IPADDR4	server_address,
		uint16_t	port,
		PCSTR	UserName,
		PCSTR	Password,
		uint32_t	time_out )

#include <ftp.h>

Initialize a FTP session with a FTP server.

Open a connection to a FTP server and log in with the specified username and password. The session handle returned from this call is required by all other FTP client functions to identify the server connection.

Parameters

server_address	The IP address of the FTP server
port	The listen port number of the FTP server. Typically 21.
UserName	Log-in username
Password	Log-in password
time_out	Timeout in system Time Ticks

Return values

>0	A FTP session handle for use with subsequent FTP operations
FTP_TIMEOUT	The connection attempt timed out
FTP_PASSWORDERROR	Authentication failed with the provided credentials
FTP_CONNECTFAIL	Unable to establish a TCP connection to the server

See also

FTP_CloseSession()

FTPActiveMode()

void FTPActiveMode

(

int

ftp_Session

)

#include <ftp.h>

Set the data connection mode to active (PORT).

In active mode, the client sends a PORT command telling the server which address and port to connect back to for data transfers. This is the traditional FTP behavior, but may not work when the client is behind a firewall or NAT device.

Parameters

ftp_Session

FTP session number

See also

FTPPassiveMode()

FTPDeleteDir()

int FTPDeleteDir	(	int	ftp_Session,
		const char *	dir_to_delete,
		uint16_t	timeout )

#include <ftp.h>

Delete a directory.

Removes a directory on the remote FTP server. The directory must typically be empty before it can be deleted.

Parameters

ftp_Session	FTP session number
dir_to_delete	Directory to delete
timeout	Timeout in system Time Ticks

Returns

ftpClientReturnCodes

See also

FTPMakeDir(), FTPSetDir()

FTPDeleteFile()

int FTPDeleteFile	(	int	ftp_Session,
		const char *	file_name,
		uint16_t	timeout )

#include <ftp.h>

Delete a file.

Deletes a file on the remote FTP server.

Parameters

ftp_Session	FTP session number
file_name	Name of file to delete
timeout	Timeout in system Time Ticks

Returns

ftpClientReturnCodes

See also

FTPRenameFile()

FTPGetCommandResult()

int FTPGetCommandResult	(	int	ftp_Session,
		char *	cmd_buf,
		int	nbytes,
		uint16_t	timeout )

#include <ftp.h>

Returns the result of the last FTP operation.

Queries the FTP server for the last FTP operation status.

Must be called after the following functions are used:

• FTPGetList()
• FTPGetFileNames()
• FTPGetFile()
• FTPSendFile()

Parameters

ftp_Session	FTP session number
cmd_buf	The buffer to hold the ASCII FTP server response. See FTP Server return codes for details.
nbytes	The maximum number of bytes cmd_buf can hold
timeout	Timeout in system Time Ticks

Returns

The FTP server response number on success, otherwise ftpClientReturnCodes

See also

FTPSendFile(), FTPGetFile(), FTPGetList(), FTPGetFileNames()

FTPGetDir()

int FTPGetDir	(	int	ftp_Session,
		char *	dir_buf,
		int	nbytes,
		uint16_t	timeout )

#include <ftp.h>

Get the current working directory.

Retrieves the current working directory path on the remote FTP server and copies it into the provided buffer.

Parameters

ftp_Session	FTP session number
dir_buf	The buffer to copy the directory information into
nbytes	Maximum number of bytes in the dir_buf
timeout	Timeout in system Time Ticks

Returns

ftpClientReturnCodes

See also

FTPSetDir(), FTPUpDir()

FTPGetFile()

int FTPGetFile	(	int	ftp_Session,
		const char *	full_file_name,
		BOOL	bBinaryMode,
		uint16_t	timeout )

#include <ftp.h>

Initialize the process to get a file from a FTP server.

This function opens a TCP connection to a FTP server so that a file may be read. It will return a file descriptor that can then be used to read the file data using file I/O functions such as: read() and ReadWithTimeout().

IMPORTANT: After reading the file data you must do 2 things:

• The TCP connection must be closed with the close() function.
• FTPGetCommandResult() must be called to check the result of the operation.

Parameters

ftp_Session	FTP session number
full_file_name	Full file name being read, including the path
bBinaryMode	True = read file as binary data, False = read file as ASCII data
timeout	Timeout in system Time Ticks

Returns

TCP file descriptor if greater than 0, otherwise ftpClientReturnCodes

See also

FTPSendFile(), FTPGetCommandResult()

---

Expand for Example Usage

Examples

Example: Read a text file in ASCII mode

int fd = FTPGetFile(ftp, "testfile.txt", FALSE, 5 * TICKS_PER_SECOND);
 
if (fd > 0)
{
    // Code to read all data from the file descriptor goes here
    close(fd);
 
    int rv = FTPGetCommandResult(ftpSession, resultBuffer, 80, 5 * TICKS_PER_SECOND);
 
    if (rv != 226)   // Return code 226 = Closing data connection. Requested file action successful.
        iprintf("Read error result = %d %s\r\n", rv, resultBuffer);
}
else
{
    iprintf("Failed to read file\r\n");
}

---

FTPGetFileNames()

int FTPGetFileNames	(	int	ftp_Session,
		const char *	full_dir_name,
		uint16_t	timeout )

#include <ftp.h>

Initialize the process to receive just the file names in a directory from a FTP server.

This function opens a TCP connection to a FTP server so that a list of file names may be read. It will return a file descriptor that can then be used to read the name list using file I/O functions such as: read() and ReadWithTimeout(). Unlike FTPGetList(), this returns only file names without additional details such as size or date.

IMPORTANT: After reading the name list you must do 2 things:

• The TCP connection must be closed with the close() function.
• FTPGetCommandResult() must be called to check the result of the operation.

Parameters

ftp_Session	FTP session number
full_dir_name	Full directory name to read, including the path
timeout	Timeout in system Time Ticks

Returns

TCP file descriptor if greater than 0, otherwise ftpClientReturnCodes

See also

FTPGetList(), FTPGetCommandResult()

FTPGetList()

int FTPGetList	(	int	ftp_Session,
		const char *	full_dir_name,
		uint16_t	timeout )

#include <ftp.h>

Initialize the process to receive a directory listing from a FTP server.

This function opens a TCP connection to a FTP server so that a directory list may be read. It will return a file descriptor that can then be used to read the listing data using file I/O functions such as: read() and ReadWithTimeout(). The listing includes file names, sizes, dates, and permissions in the standard FTP LIST format.

IMPORTANT: After reading the listing data you must do 2 things:

• The TCP connection must be closed with the close() function.
• FTPGetCommandResult() must be called to check the result of the operation.

Parameters

ftp_Session	FTP session number
full_dir_name	Full directory name to read, including the path
timeout	Timeout in system Time Ticks

Returns

TCP file descriptor if greater than 0, otherwise ftpClientReturnCodes

See also

FTPGetFileNames(), FTPGetCommandResult()

FTPMakeDir()

int FTPMakeDir	(	int	ftp_Session,
		const char *	dir_to_make,
		uint16_t	timeout )

#include <ftp.h>

Create a new directory.

Creates a new directory on the remote FTP server at the specified path.

Parameters

ftp_Session	FTP session number
dir_to_make	Directory to create
timeout	Timeout in system Time Ticks

Returns

ftpClientReturnCodes

See also

FTPDeleteDir(), FTPSetDir()

FTPPassiveMode()

void FTPPassiveMode

(

int

ftp_Session

)

#include <ftp.h>

Set the data connection mode to passive (PASV).

In passive mode, the server provides an address and port for the client to connect to for data transfers. This mode is generally preferred when the client is behind a firewall or NAT device, since the client initiates all connections.

Parameters

ftp_Session

FTP session number

See also

FTPActiveMode()

FTPRawCommand()

int FTPRawCommand	(	int	ftp_Session,
		const char *	cmd,
		char *	cmd_buf,
		int	nbytes,
		uint16_t	timeout )

#include <ftp.h>

Send a FTP command to the FTP server.

Sends an arbitrary FTP protocol command and returns the server's response. Use this function for FTP commands not covered by the other API functions.

Parameters

ftp_Session	FTP session number.
cmd	The command to send. Do not include termination such as \r\n.
cmd_buf	The buffer to hold the FTP server response, in ASCII.
nbytes	The maximum number of bytes the cmd_buf can hold.
timeout	Timeout in system Time Ticks.

Returns

The FTP server response code if greater than 0, otherwise ftpClientReturnCodes

See also

FTPRawStreamCommand()

FTPRawStreamCommand()

int FTPRawStreamCommand	(	int	ftp_Session,
		const char *	cmd,
		int *	pResult,
		char *	cmd_buf,
		int	nbytes,
		uint16_t	timeout )

#include <ftp.h>

Send a command and receive a response over a stream connection.

The FTP server will close the connection after all the data has been read. This function is the basis for such functions as FTPGetList() and FTPGetFileNames().

IMPORTANT: After reading the data you must call FTPGetCommandResult() to check the result of the operation.

Parameters

ftp_Session	FTP session number
cmd	Command to send
pResult	The server response code integer value
cmd_buf	The server response code ASCII value (including \r\n)
nbytes	Maximum number of bytes cmd_buf can hold
timeout	Timeout in system Time Ticks

Returns

TCP file descriptor if greater than 0, otherwise ftpClientReturnCodes

See also

FTPRawCommand(), FTPGetCommandResult()

FTPRenameFile()

int FTPRenameFile	(	int	ftp_Session,
		const char *	old_file_name,
		const char *	new_file_name,
		uint16_t	timeout )

#include <ftp.h>

Rename a file.

Renames a file on the remote FTP server. Can also be used to move a file by specifying a different directory path in the new name.

Parameters

ftp_Session	FTP session number
old_file_name	Name of file to rename
new_file_name	New name of file
timeout	Timeout in system Time Ticks

Returns

ftpClientReturnCodes

See also

FTPDeleteFile()

FTPSendFile()

int FTPSendFile	(	int	ftp_Session,
		const char *	full_file_name,
		BOOL	bBinaryMode,
		uint16_t	timeout )

#include <ftp.h>

Initialize the process to send a file to a FTP server.

This function opens a TCP connection to a FTP server so that a file may be sent. It will return a file descriptor that can then be used to send the file data using file I/O write functions such as: write(), writeall(), writestring(), etc.

IMPORTANT: After sending the file data you must do 2 things:

• The TCP connection must be closed with the close() function.
• FTPGetCommandResult() must be called to check the result of the operation.

Parameters

ftp_Session	FTP session number
full_file_name	Name of the file being sent
bBinaryMode	True = send file as binary data, False = send file as ASCII data
timeout	Timeout in system Time Ticks

Returns

TCP file descriptor if greater than 0, otherwise ftpClientReturnCodes

See also

FTPGetFile(), FTPGetCommandResult()

---

Expand for Example Usage

Examples

Example: Send a text file in ASCII mode

int fd = FTPSendFile(ftp, "testfile.txt", FALSE, 5 * TICKS_PER_SECOND);
 
if (fd > 0)
{
    writestring(fd, "This is a test file\r\n");
    writestring(fd, "This is line 2 of the test file\r\n");
    writestring(fd, "Last Line\r\n");
    close(fd);
 
    int rv = FTPGetCommandResult(ftpSession, resultBuffer, 80, 5 * TICKS_PER_SECOND);
 
    if (rv != 226)   // Return code 226 = Closing data connection. Requested file action successful.
        iprintf("Write error result = %d %s\r\n", rv, resultBuffer);
}
else
{
    iprintf("Failed to send file\r\n");
}

---

FTPSetDir()

int FTPSetDir	(	int	ftp_Session,
		const char *	new_dir,
		uint16_t	timeout )

#include <ftp.h>

Set the current working directory.

Changes the current working directory on the remote FTP server to the specified path.

Parameters

ftp_Session	FTP session number
new_dir	Directory path to set
timeout	Timeout in system Time Ticks

Returns

ftpClientReturnCodes

See also

FTPGetDir(), FTPUpDir(), FTPMakeDir()

FTPUpDir()

int FTPUpDir	(	int	ftp_Session,
		uint16_t	timeout )

#include <ftp.h>

Move up one directory level.

Changes the current working directory on the remote FTP server to the parent directory. Equivalent to cd .. on the remote server.

Parameters

ftp_Session	FTP session number
timeout	Timeout in system Time Ticks

Returns

ftpClientReturnCodes

See also

FTPSetDir(), FTPGetDir()