NetBurner 3.1
FTP Client

Modules

 FTP Client Return Codes
 

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. More...
 
int FTP_CloseSession (int session)
 Close a FTP session. More...
 
int FTPGetDir (int ftp_Session, char *dir_buf, int nbytes, uint16_t timeout)
 Get the current working directory. More...
 
int FTPSetDir (int ftp_Session, const char *new_dir, uint16_t timeout)
 Set the current working directory. More...
 
int FTPDeleteDir (int ftp_Session, const char *dir_to_delete, uint16_t timeout)
 Delete a directory. More...
 
int FTPMakeDir (int ftp_Session, const char *dir_to_make, uint16_t timeout)
 Create a new directory. More...
 
int FTPUpDir (int ftp_Session, uint16_t timeout)
 Move up one directory level. More...
 
int FTPDeleteFile (int ftp_Session, const char *file_name, uint16_t timeout)
 Delete a file. More...
 
int FTPRenameFile (int ftp_Session, const char *old_file_name, const char *new_file_name, uint16_t timeout)
 Rename a file. More...
 
int FTPSendFile (int ftp_Session, const char *full_file_name, BOOL bBinaryMode, uint16_t timeout)
 Initialize the process to send a file to s FTP server. More...
 
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. More...
 
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. More...
 
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. More...
 
int FTPRawCommand (int ftp_Session, const char *cmd, char *cmd_buf, int nbytes, uint16_t timeout)
 Send a FTP command to the FTP server. More...
 
int FTPGetCommandResult (int ftp_Session, char *cmd_buf, int nbytes, uint16_t timeout)
 Returns the result of the last FTP operation. More...
 
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. More...
 
void FTPActiveMode (int ftp_Session)
 Set mode to active. More...
 
void FTPPassiveMode (int ftp_Session)
 Set mode to passive. More...
 

Detailed Description

The NetBurner FTP Client Group

Function Documentation

◆ FTP_CloseSession()

int FTP_CloseSession ( int  session)

Close a FTP session.

Parameters
sessionFTP session number to close
Returns
FTP Client Return Codes
See also
FTP_InitializeSession()

◆ FTP_InitializeSession()

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.

Open a connection to a FTP server and log in with the specified username and password. The session number returned from this call can be used with the file and directory functions.

Parameters
server_addressThe IP address of the FTP server
portThe listen port number of the FTP server. Typically 21.
UserNameLog-in user name
PasswordLog-in password
time_outTimeout in system Time Ticks
Returns
A value greater than 0 is a FTP session handle, otherwise FTP Client Return Codes
See also
FTP_CloseSession()

◆ FTPActiveMode()

void FTPActiveMode ( int  ftp_Session)

Set mode to active.

Parameters
ftp_SessionFTP session number

◆ FTPDeleteDir()

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

Delete a directory.

Parameters
ftp_SessionFTP session number
dir_to_deleteDirectory to delete
timeoutTimeout in system Time Ticks
Returns
FTP Client Return Codes

◆ FTPDeleteFile()

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

Delete a file.

Parameters
ftp_SessionFTP session number
file_nameName of file to delete
timeoutTimeout in system Time Ticks
Returns
FTP Client Return Codes

◆ FTPGetCommandResult()

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

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:

Parameters
ftp_SessionFTP session number
cmd_bufThe buffer to hold the ASCII FTP server response. See FTP Server return codes for details.
nbytesThe maximum number of bytes cmd_buf can hold
timeoutTimeout in system Time Ticks
Returns
The FTP server response number on success, otherwise FTP Client Return Codes

◆ FTPGetDir()

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

Get the current working directory.

Parameters
ftp_SessionFTP session number
dir_bufThe buffer to copy the directory information into
nbytesMaximum number of bytes in the dir_buf
timeoutTimeout in system Time Ticks
Returns
FTP Client Return Codes

◆ FTPGetFile()

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.

This function opens a TCP connection to a FTP server so that a file may be read. it will return a file descritor 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:

Parameters
ftp_SessionFTP session number
full_file_nameFull file name being read, including the path
bBinaryModeTrue = read file as binary data, False = read file as ASCII data
timeoutTimeout in system Time Ticks
Returns
TCP file descriptor if greater than 0, otherwise FTP Client Return Codes
int fd = FTPGetFile(ftp, "testfile.txt", FALSE, 5 * TICKS_PER_SECOND); // Send file in ASCII mode
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 
)

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 descritor 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:

Parameters
ftp_SessionFTP session number
full_dir_nameFull directory name to read, including the path
timeoutTimeout in system Time Ticks
Returns
TCP file descriptor if greater than 0, otherwise FTP Client Return Codes

◆ FTPGetList()

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.

This function opens a TCP connection to a FTP server so that a directory list may be read. it will return a file descritor 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:

Parameters
ftp_SessionFTP session number
full_dir_nameFull directory name to read, including the path
timeoutTimeout in system Time Ticks
Returns
TCP file descriptor if greater than 0, otherwise FTP Client Return Codes

◆ FTPMakeDir()

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

Create a new directory.

Parameters
ftp_SessionFTP session number
dir_to_makeDirectory to create
timeoutTimeout in system Time Ticks
Returns
FTP Client Return Codes

◆ FTPPassiveMode()

void FTPPassiveMode ( int  ftp_Session)

Set mode to passive.

Parameters
ftp_SessionFTP session number

◆ FTPRawCommand()

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

Send a FTP command to the FTP server.

Parameters
ftp_SessionFTP session number.
cmdThe command to send. Do not include termination such as
.
cmd_bufThe buffer to hold the FTP server response, in ASCII.
nbytesThe maximum number of bytes the cmd_buf can hold.
timeoutTimeout in system Time Ticks.
Returns
The FTP server response code if greater than 0, otherwise FTP Client Return Codes

◆ FTPRawStreamCommand()

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.

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 FTPGetFiles().

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

Parameters
ftp_SessionFTP session number
cmdCommand to send
pResultThe server response code integer value
cmd_bufThe server response code ASCII value (include
)
nbytesMaximum number of bytes cmd_buf can hold
timeoutTimeout in system Time Ticks
Returns
TCP file descriptor if greater than 0, otherwise FTP Client Return Codes

◆ FTPRenameFile()

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

Rename a file.

Parameters
ftp_SessionFTP session number
old_file_nameName of file to rename
new_file_nameNew name of file
timeoutTimeout in system Time Ticks
Returns
FTP Client Return Codes

◆ FTPSendFile()

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

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

This function opens a TCP connection to a FTP server so that a file may be sent. it will return a file descritor 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:

Parameters
ftp_SessionFTP session number
full_file_nameName of the file being sent
bBinaryModeTrue = send file as binary data, False = send file as ASCII data
timeoutTimeout in system Time Ticks
Returns
TCP file descriptor if greater than 0, otherwise FTP Client Return Codes
int fd = FTPSendFile(ftp, "testfile.txt", FALSE, 5 * TICKS_PER_SECOND); // Send file in ASCII mode
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 
)

Set the current working directory.

Parameters
ftp_SessionFTP session number
new_dirDirectory path to set
timeoutTimeout in system Time Ticks
Returns
FTP Client Return Codes

◆ FTPUpDir()

int FTPUpDir ( int  ftp_Session,
uint16_t  timeout 
)

Move up one directory level.

Parameters
ftp_SessionFTP session number
timeoutTimeout in system Time Ticks
Returns
FTP Client Return Codes