Main Page | Class Hierarchy | Alphabetical List | Class List | File List | Class Members | File Members

CFTPClient Class Reference

A low-level, asynchronous FTP client based on RFC 959. More...

#include <FTPClient.h>

List of all members.

Public Types

Signals

Public Member Functions

Static Public Attributes


Detailed Description

A low-level, asynchronous FTP client based on RFC 959.

This class implements an FTP client. It allows the usual things done through FTP (uploading, downloading, dir-listing, etc), but at a very basic level.

It may be a bit difficult to use, because it is so low level. It isn't as simple as "open ftp server, do dir-listing, upload file, close". All these functions are there, but they are asynchronuous. That is, they return immediately and don't wait for the end result. Nor can you queue commands: only one command can be executed at a time. This means you will have to do the high-level protocol stuff in your own class. On the other hand, it allows you to accurately follow the progress of your commands. Think of it as a wrapper around the FTP protocol itself, with some helper functions for the data transfers.

With this class you have to make a distinction between 'commands' and 'state'. A command is just that: the user demands a certain action, and the class executes it. A string is sent to the FTP server to perform the command; if a data stream is needed that is opened as well.

A command will cause various changes in the class that can be tracked through the ref StateChange signal. For example, uploading a file will cause the following states: SendingPort, WaitData, Transfer, ClosingData, Idle (or Failed). It reflects the various steps necessary by the FTP protocol to perform an actual filetransfer. It is up to the calling class to interpret these responses (most aren't really interesting to the user anyway).

All commands will end in either "Idle" (== success) or "Failed" state. "Failed" indicates something went wrong; the result code from StateChange contains the numeric FTP response code that explains the error. "Idle", which also doubles as "Success", indicates completion of the command without error.

Note that it is possible for a state to be set multiple times in a row. If, for example, Login was succesful and was followed by a "Change Dir" that also succeeds, StateChange will be emitted twice with state "Idle". This is okay; 2 commands were issued, so you get two StateChange(Idle) (possibly intermingled with other StateChange()s).

Most commands listed below show a short state transition diagram, so you know what StateChange()s to expect.


Member Enumeration Documentation

enum CFTPClient::Commands
 

Enumeration values:
cmdNop 
cmdLogin 
cmdLogout 
cmdSetType 
cmdChangeDir 
cmdListDir 
cmdUpload 
cmdDownload 
cmdRename 
cmdPassive 
cmdDeleteLocalFile  For destructive uploads.
cmdDestroy 

enum CFTPClient::States
 

Enumeration values:
stNOC  Not connected.
stDNSBusy  Looking up hostname...
stConnecting  Busy connecting to server.
stConnected  Server reached; awaiting response from FTP daemon.
stLogin  Sending username.
stAuthenticate  Sending password.
stIdle  Connected OK, but not doing anything.
stSendingPort  Sending PORT command to remote end.
stWaitData  Waiting for data connection.
stTransfer  Transfering data.
stClosingData  Waiting for 226.
stFailed  Failed status; can happen at every command.
stUnknown  Unkown or unexpected result code.

enum CFTPClient::TransferMethods
 

Enumeration values:
tmUnknown 
tmAscii 
tmBinary 


Constructor & Destructor Documentation

CFTPClient::CFTPClient QObject *  parent = 0,
const char *  name = 0
 

CFTPClient::~CFTPClient  ) 
 


Member Function Documentation

void CFTPClient::ChangeDir const QString &  new_dir  ) 
 

Change to remote directory on server.

void CFTPClient::Connect const QString &  user,
const QString &  pass,
const QString &  server,
int  port = 21
 

Initiate connection to FTP server.

Parameters:
user The username
pass The password
server The server name
port Port number on the server
This function initiates a connection to the server. Since Qt provides asynchronuous DNS lookups, we don't even block here. However, that means we are not connected yet when this function returns.

void CFTPClient::ControlPortClosed  )  [signal]
 

Emitted when the control connection was closed (either by us or the remote party).

int CFTPClient::GetCommand  )  const
 

QString CFTPClient::GetErrorString int  result  )  const
 

int CFTPClient::GetState  )  const
 

void CFTPClient::ListDir  ) 
 

List contents of remote directory.

This command will retrieve the list of filenames of the directory on the remote server. The found files are emitted one by one through ListDirEntry(const QString &filename).

Note: make sure you set the transfer type to ASCII first.

void CFTPClient::ListDirEntry const QString &  filename  )  [signal]
 

void CFTPClient::LoggedIn  )  [signal]
 

Emitted when login was succesfull.

void CFTPClient::LoginFailed  )  [signal]
 

Emitted when login failed.

void CFTPClient::Logout  ) 
 

void CFTPClient::Progress int  offset  )  [signal]
 

Emitted every now and then to report on progress. Reports total amount of bytes transfered so far.

void CFTPClient::Rename const QString &  from,
const QString &  to
 

Rename a file on the server.

Parameters:
from The existing filename
to The new filename
This command will instruct the FTP server to rename a file on the remote filesystem. A rename across directories (effectively moving the file) may be possible. A rename across filesystems most likely is not.

void CFTPClient::SetActive  ) 
 

Turns off passive mode; see SetPassive.

void CFTPClient::SetLogging bool  log  ) 
 

void CFTPClient::SetPassive  ) 
 

Set transfer mode to passive.

Usually FTP transfers (both up- and downloads) are initiated by the server, after the command has been sent by the client. However, this does not always work (firewalls, braindead FTP implementations, etc) and the client has to do the work; this is called 'passive mode', and this function turns this mode on.

Note: this function does not trigger a state change.

void CFTPClient::SetTypeAscii  ) 
 

void CFTPClient::SetTypeBinary  ) 
 

void CFTPClient::StateChange int  command,
int  new_state,
int  result,
const QString &  server_msg
[signal]
 

This signal is emitted whenever the internal state machine changes. The result is the numeric FTP result code, if known. There are however a few extra 'result' codes defined, for situations that do not apply to FTP servers:

800 Local file not found (upload) 810 Server name not resolved 811 Failed to connect to server

void CFTPClient::TimeOut  )  [signal]
 

void CFTPClient::Upload const QString &  local_file,
const QString &  remote_file = QString::null
 

Upload file to remote site.

Parameters:
local_file The filename on the local machine
remote_file The filename on the remote machine; if not present, the same as local_file


Member Data Documentation

const char * CFTPClient::CommandStr [static]
 

Initial value:

{ "Nop", "Login", "Logout", "SetType", "ChangeDir", "ListDir", "Upload", "Download", "Rename", "Passive", "DeleteLocalFile", "Destroy", }

const char * CFTPClient::StateStr [static]
 

Initial value:

{ "NOC", "Resolving servername", "Connecting", "Connected", "Login", "Authenticate", "Idle", "SendingPort", "WaitData", "Transfer", "ClosingData", "Failed", "Unknown", }


The documentation for this class was generated from the following files:
Generated on Wed Dec 13 23:38:47 2006 for CamStream by doxygen 1.3.7