From d796c9dd933ab96ec83b9a634feedd5d32e1ba3f Mon Sep 17 00:00:00 2001 From: Timothy Pearson Date: Tue, 8 Nov 2011 12:31:36 -0600 Subject: Test conversion to TQt3 from Qt3 8c6fc1f8e35fd264dd01c582ca5e7549b32ab731 --- doc/html/qftp.html | 693 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 693 insertions(+) create mode 100644 doc/html/qftp.html (limited to 'doc/html/qftp.html') diff --git a/doc/html/qftp.html b/doc/html/qftp.html new file mode 100644 index 000000000..8b2ce2b46 --- /dev/null +++ b/doc/html/qftp.html @@ -0,0 +1,693 @@ + + + + + +TQFtp Class + + + + + + + +
+ +Home + | +All Classes + | +Main Classes + | +Annotated + | +Grouped Classes + | +Functions +

TQFtp Class Reference
[network module]

+ +

The TQFtp class provides an implementation of the FTP protocol. +More... +

#include <qftp.h> +

Inherits TQNetworkProtocol. +

List of all member functions. +

Public Members

+ +

Public Slots

+ +

Signals

+ +

Detailed Description

+ + +The TQFtp class provides an implementation of the FTP protocol. + +

+ +

This class provides two different interfaces: one is the +TQNetworkProtocol interface that allows you to use FTP through the +TQUrlOperator abstraction. The other is a direct interface to FTP +that gives you lower-level access to the FTP protocol for finer +control. Using the direct interface you can also execute arbitrary +FTP commands. +

Don't mix the two interfaces, since the behavior is not +well-defined. +

If you want to use TQFtp with the TQNetworkProtocol interface, you +do not use it directly, but rather through a TQUrlOperator, for +example: +

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

This code will only work if the TQFtp class is registered; to +register the class, you must call qInitNetworkProtocols() before +using a TQUrlOperator with TQFtp. +

The rest of this descrption describes the direct interface to FTP. +

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

+    TQFtp *ftp = new TQFtp( this ); // this is an optional TQObject 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 +TQUrlOperator() 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 TQt Network Documentation, TQNetworkProtocol, TQUrlOperator, TQHttp, and Input/Output and Networking. + +

Member Type Documentation

+

TQFtp::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. +

See also currentCommand(). + +

TQFtp::Error

+ +

This enum identifies the error that occurred. +

See also error(). + +

TQFtp::State

+ +

This enum defines the connection state: +

See also stateChanged() and state(). + +

Member Function Documentation

+

TQFtp::TQFtp () +

+Constructs a TQFtp object. + +

TQFtp::TQFtp ( TQObject * parent, const char * name = 0 ) +

+Constructs a TQFtp object. The parent and name parameters +are passed to the TQObject constructor. + +

TQFtp::~TQFtp () [virtual] +

+Destructor. + +

void TQFtp::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. +

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 clearPendingCommands(). + +

Example: network/ftpclient/ftpmainwindow.ui.h. +

Q_ULONG TQFtp::bytesAvailable () const +

+Returns the number of bytes that can be read from the data socket +at the moment. +

See also get(), readyRead(), readBlock(), and readAll(). + +

int TQFtp::cd ( const TQString & dir ) +

+Changes the working directory of the server to dir. +

The function does not block and returns immediately. The command +is scheduled, and its execution is performed asynchronously. The +function returns a unique identifier which is passed by +commandStarted() and commandFinished(). +

When the command is started the commandStarted() signal is +emitted. When it is finished the commandFinished() signal is +emitted. +

See also commandStarted() and commandFinished(). + +

Example: network/ftpclient/ftpmainwindow.ui.h. +

void TQFtp::clearPendingCommands () +

+Deletes all pending commands from the list of scheduled commands. +This does not affect the command that is being executed. If you +want to stop this this as well, use abort(). +

See also hasPendingCommands() and abort(). + +

int TQFtp::close () +

+Closes the connection to the FTP server. +

The stateChanged() signal is emitted when the state of the +connecting process changes, e.g. to Closing, then Unconnected. +

The function does not block and returns immediately. The command +is scheduled, and its execution is performed asynchronously. The +function returns a unique identifier which is passed by +commandStarted() and commandFinished(). +

When the command is started the commandStarted() signal is +emitted. When it is finished the commandFinished() signal is +emitted. +

See also stateChanged(), commandStarted(), and commandFinished(). + +

Example: network/ftpclient/ftpmainwindow.ui.h. +

void TQFtp::commandFinished ( int id, bool error ) [signal] +

+ +

This signal is emitted when processing the command identified by +id has finished. error is TRUE if an error occurred during +the processing; otherwise error is FALSE. +

See also commandStarted(), done(), error(), and errorString(). + +

Example: network/ftpclient/ftpmainwindow.ui.h. +

void TQFtp::commandStarted ( int id ) [signal] +

+ +

This signal is emitted when processing the command identified by +id starts. +

See also commandFinished() and done(). + +

Example: network/ftpclient/ftpmainwindow.ui.h. +

int TQFtp::connectToHost ( const TQString & host, Q_UINT16 port = 21 ) +

+Connects to the FTP server host using port port. +

The stateChanged() signal is emitted when the state of the +connecting process changes, e.g. to HostLookup, then Connecting, then Connected. +

The function does not block and returns immediately. The command +is scheduled, and its execution is performed asynchronously. The +function returns a unique identifier which is passed by +commandStarted() and commandFinished(). +

When the command is started the commandStarted() signal is +emitted. When it is finished the commandFinished() signal is +emitted. +

See also stateChanged(), commandStarted(), and commandFinished(). + +

Example: network/ftpclient/ftpmainwindow.ui.h. +

Command TQFtp::currentCommand () const +

+Returns the command type of the FTP command being executed or None if there is no command being executed. +

See also currentId(). + +

Example: network/ftpclient/ftpmainwindow.ui.h. +

TQIODevice * TQFtp::currentDevice () const +

+Returns the TQIODevice pointer that is used by the FTP command to read data +from or store data to. If there is no current FTP command being executed or +if the command does not use an IO device, this function returns 0. +

This function can be used to delete the TQIODevice in the slot connected to +the commandFinished() signal. +

See also get() and put(). + +

Example: network/ftpclient/ftpmainwindow.ui.h. +

int TQFtp::currentId () const +

+Returns the identifier of the FTP command that is being executed +or 0 if there is no command being executed. +

See also currentCommand(). + +

void TQFtp::dataTransferProgress ( int done, int total ) [signal] +

+ +

This signal is emitted in response to a get() or put() request to +indicate the current progress of the download or upload. +

done is the amount of data that has already been transferred +and total is the total amount of data to be read or written. It +is possible that the TQFtp class is not able to determine the total +amount of data that should be transferred, in which case total +is 0. (If you connect this signal to a TQProgressBar, the progress +bar shows a busy indicator if the total is 0). +

Warning: done and total are not necessarily the size in +bytes, since for large files these values might need to be +"scaled" to avoid overflow. +

See also get(), put(), and TQProgressBar::progress. + +

Example: network/ftpclient/ftpmainwindow.ui.h. +

void TQFtp::done ( bool error ) [signal] +

+ +

This signal is emitted when the last pending command has finished; +(it is emitted after the last command's commandFinished() signal). +error is TRUE if an error occurred during the processing; +otherwise error is FALSE. +

See also commandFinished(), error(), and errorString(). + +

Example: network/ftpclient/ftpmainwindow.ui.h. +

Error TQFtp::error () const +

+Returns the last error that occurred. This is useful to find out +what when wrong when receiving a commandFinished() or a done() +signal with the error argument set to TRUE. +

If you start a new command, the error status is reset to NoError. + +

TQString TQFtp::errorString () const +

+Returns a human-readable description of the last error that +occurred. This is useful for presenting a error message to the +user when receiving a commandFinished() or a done() signal with +the error argument set to TRUE. +

The error string is often (but not always) the reply from the +server, so it is not always possible to translate the string. If +the message comes from TQt, the string has already passed through +tr(). + +

Example: network/ftpclient/ftpmainwindow.ui.h. +

int TQFtp::get ( const TQString & file, TQIODevice * dev = 0 ) +

+Downloads the file file from the server. +

If dev is 0, then the readyRead() signal is emitted when there +is data available to read. You can then read the data with the +readBlock() or readAll() functions. +

If dev is not 0, the data is written directly to the device dev. Make sure that the dev pointer is valid for the duration +of the operation (it is safe to delete it when the +commandFinished() signal is emitted). In this case the readyRead() +signal is not emitted and you cannot read data with the +readBlock() or readAll() functions. +

If you don't read the data immediately it becomes available, i.e. +when the readyRead() signal is emitted, it is still available +until the next command is started. +

For example, if you want to present the data to the user as soon +as there is something available, connect to the readyRead() signal +and read the data immediately. On the other hand, if you only want +to work with the complete data, you can connect to the +commandFinished() signal and read the data when the get() command +is finished. +

The function does not block and returns immediately. The command +is scheduled, and its execution is performed asynchronously. The +function returns a unique identifier which is passed by +commandStarted() and commandFinished(). +

When the command is started the commandStarted() signal is +emitted. When it is finished the commandFinished() signal is +emitted. +

See also readyRead(), dataTransferProgress(), commandStarted(), and commandFinished(). + +

Example: network/ftpclient/ftpmainwindow.ui.h. +

bool TQFtp::hasPendingCommands () const +

+Returns TRUE if there are any commands scheduled that have not yet +been executed; otherwise returns FALSE. +

The command that is being executed is not considered as a +scheduled command. +

See also clearPendingCommands(), currentId(), and currentCommand(). + +

int TQFtp::list ( const TQString & dir = TQString::null ) +

+Lists the contents of directory dir on the FTP server. If dir is empty, it lists the contents of the current directory. +

The listInfo() signal is emitted for each directory entry found. +

The function does not block and returns immediately. The command +is scheduled, and its execution is performed asynchronously. The +function returns a unique identifier which is passed by +commandStarted() and commandFinished(). +

When the command is started the commandStarted() signal is +emitted. When it is finished the commandFinished() signal is +emitted. +

See also listInfo(), commandStarted(), and commandFinished(). + +

Example: network/ftpclient/ftpmainwindow.ui.h. +

void TQFtp::listInfo ( const TQUrlInfo & i ) [signal] +

+ +

This signal is emitted for each directory entry the list() command +finds. The details of the entry are stored in i. +

See also list(). + +

Example: network/ftpclient/ftpmainwindow.ui.h. +

int TQFtp::login ( const TQString & user = TQString::null, const TQString & password = TQString::null ) +

+Logs in to the FTP server with the username user and the +password password. +

The stateChanged() signal is emitted when the state of the +connecting process changes, e.g. to LoggedIn. +

The function does not block and returns immediately. The command +is scheduled, and its execution is performed asynchronously. The +function returns a unique identifier which is passed by +commandStarted() and commandFinished(). +

When the command is started the commandStarted() signal is +emitted. When it is finished the commandFinished() signal is +emitted. +

See also commandStarted() and commandFinished(). + +

Example: network/ftpclient/ftpmainwindow.ui.h. +

int TQFtp::mkdir ( const TQString & dir ) +

+Creates a directory called dir on the server. +

The function does not block and returns immediately. The command +is scheduled, and its execution is performed asynchronously. The +function returns a unique identifier which is passed by +commandStarted() and commandFinished(). +

When the command is started the commandStarted() signal is +emitted. When it is finished the commandFinished() signal is +emitted. +

See also commandStarted() and commandFinished(). + +

int TQFtp::put ( TQIODevice * dev, const TQString & file ) +

+Reads the data from the IO device dev, and writes it to the +file called file on the server. The data is read in chunks from +the IO device, so this overload allows you to transmit large +amounts of data without the need to read all the data into memory +at once. +

Make sure that the dev pointer is valid for the duration of the +operation (it is safe to delete it when the commandFinished() is +emitted). + +

Example: network/ftpclient/ftpmainwindow.ui.h. +

int TQFtp::put ( const TQByteArray & data, const TQString & file ) +

+This is an overloaded member function, provided for convenience. It behaves essentially like the above function. +

Writes the data data to the file called file on the server. +The progress of the upload is reported by the +dataTransferProgress() signal. +

The function does not block and returns immediately. The command +is scheduled, and its execution is performed asynchronously. The +function returns a unique identifier which is passed by +commandStarted() and commandFinished(). +

When the command is started the commandStarted() signal is +emitted. When it is finished the commandFinished() signal is +emitted. +

See also dataTransferProgress(), commandStarted(), and commandFinished(). + +

int TQFtp::rawCommand ( const TQString & command ) +

+Sends the raw FTP command command to the FTP server. This is +useful for low-level FTP access. If the operation you wish to +perform has an equivalent TQFtp function, we recommend using the +function instead of raw FTP commands since the functions are +easier and safer. +

The function does not block and returns immediately. The command +is scheduled, and its execution is performed asynchronously. The +function returns a unique identifier which is passed by +commandStarted() and commandFinished(). +

When the command is started the commandStarted() signal is +emitted. When it is finished the commandFinished() signal is +emitted. +

See also rawCommandReply(), commandStarted(), and commandFinished(). + +

Example: network/ftpclient/ftpmainwindow.ui.h. +

void TQFtp::rawCommandReply ( int replyCode, const TQString & detail ) [signal] +

+ +

This signal is emitted in response to the rawCommand() function. +replyCode is the 3 digit reply code and detail is the text +that follows the reply code. +

See also rawCommand(). + +

Example: network/ftpclient/ftpmainwindow.ui.h. +

TQByteArray TQFtp::readAll () +

+Reads all the bytes available from the data socket and returns +them. +

See also get(), readyRead(), bytesAvailable(), and readBlock(). + +

Q_LONG TQFtp::readBlock ( char * data, Q_ULONG maxlen ) +

+Reads maxlen bytes from the data socket into data and +returns the number of bytes read. Returns -1 if an error occurred. +

See also get(), readyRead(), bytesAvailable(), and readAll(). + +

void TQFtp::readyRead () [signal] +

+ +

This signal is emitted in response to a get() command when there +is new data to read. +

If you specify a device as the second argument in the get() +command, this signal is not emitted; instead the data is +written directly to the device. +

You can read the data with the readAll() or readBlock() functions. +

This signal is useful if you want to process the data in chunks as +soon as it becomes available. If you are only interested in the +complete data, just connect to the commandFinished() signal and +read the data then instead. +

See also get(), readBlock(), readAll(), and bytesAvailable(). + +

int TQFtp::remove ( const TQString & file ) +

+Deletes the file called file from the server. +

The function does not block and returns immediately. The command +is scheduled, and its execution is performed asynchronously. The +function returns a unique identifier which is passed by +commandStarted() and commandFinished(). +

When the command is started the commandStarted() signal is +emitted. When it is finished the commandFinished() signal is +emitted. +

See also commandStarted() and commandFinished(). + +

Example: network/ftpclient/ftpmainwindow.ui.h. +

int TQFtp::rename ( const TQString & oldname, const TQString & newname ) +

+Renames the file called oldname to newname on the server. +

The function does not block and returns immediately. The command +is scheduled, and its execution is performed asynchronously. The +function returns a unique identifier which is passed by +commandStarted() and commandFinished(). +

When the command is started the commandStarted() signal is +emitted. When it is finished the commandFinished() signal is +emitted. +

See also commandStarted() and commandFinished(). + +

int TQFtp::rmdir ( const TQString & dir ) +

+Removes the directory called dir from the server. +

The function does not block and returns immediately. The command +is scheduled, and its execution is performed asynchronously. The +function returns a unique identifier which is passed by +commandStarted() and commandFinished(). +

When the command is started the commandStarted() signal is +emitted. When it is finished the commandFinished() signal is +emitted. +

See also commandStarted() and commandFinished(). + +

State TQFtp::state () const +

+Returns the current state of the object. When the state changes, +the stateChanged() signal is emitted. +

See also State and stateChanged(). + +

Example: network/ftpclient/ftpmainwindow.ui.h. +

void TQFtp::stateChanged ( int state ) [signal] +

+ +

This signal is emitted when the state of the connection changes. +The argument state is the new state of the connection; it is +one of the State values. +

It is usually emitted in response to a connectToHost() or close() +command, but it can also be emitted "spontaneously", e.g. when the +server closes the connection unexpectedly. +

See also connectToHost(), close(), state(), and State. + +

Example: network/ftpclient/ftpmainwindow.ui.h. + +

+This file is part of the TQt toolkit. +Copyright © 1995-2007 +Trolltech. All Rights Reserved.

+ +
Copyright © 2007 +TrolltechTrademarks +
TQt 3.3.8
+
+ -- cgit v1.2.1