QFtp(3qt)

📦 version 3.3.8b, in fedora 43, fedora 44

💖 QFtp 💖 (3qt)

okay bestie, sit DOWN, because today we're talking about the FTP protocol implementation that ships in Qt, and honestly? it's giving vintage-but-iconic. this is QFtp(3qt) and it's about to be your new hyperfixation. 🦋

✨ NAME ✨

QFtp — an implementation of the FTP protocol. that's it, that's the whole vibe. no cap.

🌸 SYNOPSIS 🌸

#include <qftp.h>

it inherits from QNetworkProtocol, which is a whole mood.

💅 Public Members 💅

QFtp ()
QFtp ( QObject * parent, const char * name = 0 )
virtual ~QFtp ()
enum State { Unconnected, HostLookup, Connecting, Connected, LoggedIn,
    Closing }
enum Error { NoError, UnknownError, HostNotFound, ConnectionRefused,
    NotConnected }
enum Command { None, ConnectToHost, Login, Close, List, Cd, Get, Put,
    Remove, Mkdir, Rmdir, Rename, RawCommand }
int connectToHost ( const QString & host, Q_UINT16 port = 21 )
int login ( const QString & user = QString::null, const QString &
    password = QString::null )
int close ()
int list ( const QString & dir = QString::null )
int cd ( const QString & dir )
int get ( const QString & file, QIODevice * dev = 0 )
int put ( const QByteArray & data, const QString & file )
int put ( QIODevice * dev, const QString & file )
int remove ( const QString & file )
int mkdir ( const QString & dir )
int rmdir ( const QString & dir )
int rename ( const QString & oldname, const QString & newname )
int rawCommand ( const QString & command )
Q_ULONG bytesAvailable () const
Q_LONG readBlock ( char * data, Q_ULONG maxlen )
QByteArray readAll ()
int currentId () const
QIODevice * currentDevice () const
Command currentCommand () const
bool hasPendingCommands () const
void clearPendingCommands ()
State state () const
Error error () const
QString errorString () const

🎀 Public Slots 🎀

void abort ()

⭐ Signals ⭐

void stateChanged ( int state )
void listInfo ( const QUrlInfo & i )
void readyRead ()
void dataTransferProgress ( int done, int total )
void rawCommandReply ( int replyCode, const QString & detail )
void commandStarted ( int id )
void commandFinished ( int id, bool error )
void done ( bool error )

🌈 DESCRIPTION 🌈

the QFtp class provides an implementation of the FTP protocol. periodt.

this class hands you two different interfaces, and the way that it does that is honestly so versatile of it:

one is the QNetworkProtocol interface, which lets you use FTP through the QUrlOperator abstraction ✨
the other is a direct interface to FTP, which gives you lower-level access to the FTP protocol so you get finer control. and with the direct interface you can also execute arbitrary FTP commands, which is main character energy fr fr.

do NOT mix the two interfaces. the behavior is not well-defined and we do not do that here. 🙈

if you want to use QFtp with the QNetworkProtocol interface, you don't use it directly — you use it through a QUrlOperator, like this:

QUrlOperator op( "ftp://ftp.trolltech.com" );
op.listChildren(); // Asks the server to provide a directory listing

this code will only work if the QFtp class is registered. to register the class you must call qInitNetworkProtocols() before using a QUrlOperator with QFtp. iykyk.

the rest of this descrption describes the direct interface to FTP. (yes, the original says "descrption", we are keeping the chaos, we don't fix what's iconic)

the class works asynchronously, so there are no blocking functions. if an operation cannot be executed immediately, the function will still return straight away and the operation will be scheduled for later execution. the results of scheduled operations are reported via signals. this approach depends on the event loop being in operation. 👑

the operations that can be scheduled (they are called "commands" in the rest of the documentation) are the following: connectToHost(), login(), close(), list(), cd(), get(), put(), remove(), mkdir(), rmdir(), rename() and rawCommand().

all of these commands return a unique identifier that allows you to keep track of the command that is currently being executed. when the execution of a command starts, the commandStarted() signal with the command's identifier is emitted. when the command is finished, the commandFinished() signal is emitted with the command's identifier and a bool that indicates whether the command finished with an error. 🫶

in some cases, you might want to execute a sequence of commands, e.g. if you want to connect and login to a FTP server. this is simply achieved:

QFtp *ftp = new QFtp( this ); // this is an optional QObject parent
ftp->connectToHost( "ftp.trolltech.com" );
ftp->login();

in this case two FTP commands have been scheduled. when the last scheduled command has finished, a done() signal is emitted with a bool argument that tells you whether the sequence finished with an error.

if an error occurs during the execution of one of the commands in a sequence of commands, all the pending commands (i.e. scheduled, but not yet executed commands) are cleared and no signals are emitted for them. 😭

some commands, e.g. list(), emit additional signals to report their results.

example: if you want to download the INSTALL file from Trolltech's FTP server, you would write this:

ftp->connectToHost( "ftp.trolltech.com" );  // id == 1
ftp->login();                               // id == 2
ftp->cd( "qt" );                            // id == 3
ftp->get( "INSTALL" );                      // id == 4
ftp->close();                               // id == 5

for this example the following sequence of signals is emitted (with small variations, depending on network traffic, etc.):

start( 1 )
stateChanged( HostLookup )
stateChanged( Connecting )
stateChanged( Connected )
finished( 1, FALSE )
start( 2 )
stateChanged( LoggedIn )
finished( 2, FALSE )
start( 3 )
finished( 3, FALSE )
start( 4 )
dataTransferProgress( 0, 3798 )
dataTransferProgress( 2896, 3798 )
readyRead()
dataTransferProgress( 3798, 3798 )
readyRead()
finished( 4, FALSE )
start( 5 )
stateChanged( Closing )
stateChanged( Unconnected )
finished( 5, FALSE )
done( FALSE )

the dataTransferProgress() signal in the above example is useful if you want to show a progressbar to inform the user about the progress of the download. the readyRead() signal tells you that there is data ready to be read. the amount of data can be queried then with the bytesAvailable() function and it can be read with the readBlock() or readAll() function. 💖

if the login fails for the above example, the signals would look like this:

start( 1 )
stateChanged( HostLookup )
stateChanged( Connecting )
stateChanged( Connected )
finished( 1, FALSE )
start( 2 )
finished( 2, TRUE )
done( TRUE )

you can then get details about the error with the error() and errorString() functions.

the functions currentId() and currentCommand() provide more information about the currently executing command.

the functions hasPendingCommands() and clearPendingCommands() allow you to query and clear the list of pending commands.

the safest and easiest way to use the FTP protocol is to use QUrlOperator() or the FTP commands described above. if you are an experienced network programmer and want to have complete control you can use rawCommand() to execute arbitrary FTP commands. 🔥

see also Qt Network Documentation, QNetworkProtocol, QUrlOperator, QHttp, and Input/Output and Networking.

🧚 Member Type Documentation 🧚

`QFtp::Command`

this enum is used as the return value for the currentCommand() function. this allows you to perform specific actions for particular commands, e.g. in a FTP client, you might want to clear the directory view when a list() command is started; in this case you can simply check in the slot connected to the start() signal if the currentCommand() is List. big brain move ngl.

QFtp::None — No command is being executed.
QFtp::ConnectToHost — connectToHost() is being executed.
QFtp::Login — login() is being executed.
QFtp::Close — close() is being executed.
QFtp::List — list() is being executed.
QFtp::Cd — cd() is being executed.
QFtp::Get — get() is being executed.
QFtp::Put — put() is being executed.
QFtp::Remove — remove() is being executed.
QFtp::Mkdir — mkdir() is being executed.
QFtp::Rmdir — rmdir() is being executed.
QFtp::Rename — rename() is being executed.
QFtp::RawCommand — rawCommand() is being executed.

`QFtp::Error`

this enum identifies the error that occurred.

QFtp::NoError — No error occurred.
QFtp::HostNotFound — The host name lookup failed.
QFtp::ConnectionRefused — The server refused the connection.
QFtp::NotConnected — Tried to send a command, but there is no connection to a server.
QFtp::UnknownError — An error other than those specified above occurred.

`QFtp::State`

this enum defines the connection state:

QFtp::Unconnected — There is no connection to the host.
QFtp::HostLookup — A host name lookup is in progress.
QFtp::Connecting — An attempt to connect to the host is in progress.
QFtp::Connected — Connection to the host has been achieved.
QFtp::LoggedIn — Connection and user login have been achieved.
QFtp::Closing — The connection is closing down, but it is not yet closed. (The state will be Unconnected when the connection is closed.)

see also stateChanged() and state().

👑 MEMBER FUNCTION DOCUMENTATION 👑

`QFtp::QFtp ()`

Constructs a QFtp object. ✨

`QFtp::QFtp ( QObject * parent, const char * name = 0 )`

Constructs a QFtp object. The parent and name parameters are passed to the QObject constructor.

`QFtp::~QFtp ()` `[virtual]`

Destructor. 🫡

`void QFtp::abort ()` `[slot]`

Aborts the current command and deletes all scheduled commands.

if there is an unfinished command (i.e. a command for which the commandStarted() signal has been emitted, but for which the commandFinished() signal has not been emitted), this function sends an ABORT command to the server. when the server replies that the command is aborted, the commandFinished() signal with the error argument set to TRUE is emitted for the command. due to timing issues, it is possible that the command had already finished before the abort request reached the server, in which case, the commandFinished() signal is emitted with the error argument set to FALSE. 💀 timing is everything bestie.

for all other commands that are affected by the abort(), no signals are emitted.

if you don't start further FTP commands directly after the abort(), there won't be any scheduled commands and the done() signal is emitted.

Warning: Some FTP servers, for example the BSD FTP daemon (version 0.3), wrongly return a positive reply even when an abort has occurred. For these servers the commandFinished() signal has its error flag set to FALSE, even though the command did not complete successfully. 😭

🌈 SEE ALSO 🌈

🎀 COPYRIGHT 🎀

✨ AUTHOR ✨

Generated automatically from the source code. (yes bestie, the robots wrote this one 🙈)

💀 BUGS 💀

If you find a bug in Qt, please report it as described in http://doc.trolltech.com/bughowto.html. Good bug reports help us to help you. Thank you 🫶

The definitive Qt documentation is provided in HTML format; it is located at $QTDIR/doc/html and can be read using Qt Assistant or with a web browser. This man page is provided as a convenience for those users who prefer man pages, although this format is not officially supported by Trolltech.

If you find errors in this manual page, please report them to qt-bugs@trolltech.com. Please include the name of the manual page (qftp.3qt) and the Qt version (3.3.8) ⭐

okay that's literally the whole page bestie, you made it 💖 this one's from Trolltech AS, dated 2 February 2007, and it's QFtp(3qt) — go forth and FTP responsibly, mwah 💅✨

📦 where this page comes from

fedora 43: qt3-devel-docs 3.3.8b-102.fc43 · QPL-1.0 OR GPL-2.0-only OR GPL-3.0-only
fedora 44: qt3-devel-docs 3.3.8b-103.fc44 · QPL-1.0 OR GPL-2.0-only OR GPL-3.0-only
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-10-14: a language model's rewrite of the original, under its terms