QObexFtpClient Class Reference
[QtBaseModule]

Detailed Description

The QObexFtpClient class provides an implementation of the OBEX file-transfer mechanism.

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: connect(), disconnect(), list(), cd(), cdUp(), get(), put(), remove(), mkdir(), rmdir()

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.

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.

An example of using this class is:

    ftp->connect();                             // id == 1
    ftp->cd("foo");                             // id == 2
    ftp->get("bar");                            // id == 3
    ftp->disconnect();                          // id == 4

get() and put() operations report the progress of the transfer using the dataTransferProgress() signal. If no IODevice is associated with a get, then the readyRead() signal is emitted. In this case the data can be obtained with the read() or readAll().

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.

See also QObexFolderListingEntryInfo.

Member Type Documentation

enum QObexFtpClient::Command

This enum is used to represent the different types of commands supported by the QObexFtpClient.

enum QObexFtpClient::Error

The errors that may occur for an OBEX client.

enum QObexFtpClient::State

This enum is used to represent the states that a QObexFtpClient can be in.

Member Function Documentation

QObexFtpClient::QObexFtpClient ( QIODevice * device, QObject * parent = 0 )

Constructs a new OBEX FTP Client object. The device to use is given by device. The device should already be opened in order to perform requests.

The parent parameter specifies the QObject parent.

See also state().

QObexFtpClient::~QObexFtpClient ()

Deconstructs an OBEX FTP Client.

void QObexFtpClient::abort ()   [slot]

Attempts to abort the current operation. This will also clear all pending operations. If no operations are in progress or pending, then this function has no effect.

See also clearPendingCommands().

qint64 QObexFtpClient::bytesAvailable () const

Returns the number of bytes available in the ftp stream.

See also read() and readAll().

int QObexFtpClient::cd ( const QString & dir = QString() )

Change the current working directory to a directory given by dir. If dir is an empty string, then request the root directory to become the current working directory.

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 QObexFtpClient::cdUp ()

Changes the current working directory to be the parent of the current working directory. Root directories do not have parent directories, and it is an error to cd to parent directory of the root directory.

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

void QObexFtpClient::clearPendingCommands ()

Clears all pending commands. If there are no pending commands, this method has no effect.

See also hasPendingCommands(), currentId(), and currentCommand().

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

This signal is emitted whenever a queued command has been performed. The id parameter holds the id of the command finished. The error parameter holds whether an error occurred.

See also commandStarted().

void QObexFtpClient::commandStarted ( int id )   [signal]

This signal is emitted whenever a queued command has been started. The id parameter holds the id of the command.

See also commandFinished().

int QObexFtpClient::connect ()

Requests the client to connect to the server. The device will be used to establish the OBEX transport connection if the socket is not yet 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(), commandFinished(), and disconnect().

QObexFtpClient::Command QObexFtpClient::currentCommand () const

Returns the command type of the current operation in progress. If no operation is in progress, a QObexFtpClient::None is returned.

See also currentId().

QIODevice * QObexFtpClient::currentDevice () const

Returns the current QIODevice that is being used for a get / put operation. If no device is being used, a NULL is returned.

See also put() and get().

int QObexFtpClient::currentId () const

Returns the id of the operation currently in progress. If no operation is in progress a 0 is returned.

See also currentCommand().

void QObexFtpClient::dataTransferProgress ( qint64 completed, qint64 total )   [signal]

This signal is emitted reports the progress of the file send operation. The completed parameter reports how many bytes were sent, and total parameter reports the total number of bytes. If the total is not known, it will be reported as 0.

See also get() and put().

int QObexFtpClient::disconnect ()

Disconnect 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 stateChanged(), commandStarted(), commandFinished(), and connect().

void QObexFtpClient::done ( bool error )   [signal]

This signal is emitted whenever all pending requests have been completed. The error parameter reports whether an error occurred during processing.

See also commandStarted() and commandFinished().

Error QObexFtpClient::error () const

Returns the last error that occurred. This is useful for finding out what happened when receiving an requestFinished() or done() signal that has the error argument set to true.

See also errorString().

QString QObexFtpClient::errorString () const

Returns a human-readable description of the last error that occurred.

The error string is reset when a new request is started.

See also error().

int QObexFtpClient::get ( const QString & file, QIODevice * dev = 0 )

Attempts to retrieve file from the server. If dev is NULL, then the readyRead() signal is emitted when there is data available to read. You can then read the data with the read() 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 read() 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.

The transfer progress 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 readyRead(), dataTransferProgress(), commandStarted(), commandFinished(), and getInfo().

void QObexFtpClient::getInfo ( const QString & mimetype, const QString & description, const QDateTime & lastModified )   [signal]

Some OBEX servers can provide additional information about a file in the headers sent with the GET command response that might not appear in the directory listing. These attributes are returned in this signal. An empty, default-constructed value is given if the GET response did not specify any additional information.

The mimetype parameter holds the contents of the Type header. The description parameter holds the contents of the Description header. The lastModified holds the contents of the Time header.

See also get() and listInfo().

bool QObexFtpClient::hasPendingCommands () const

Returns true if the Ftp Client has pending operations, and false otherwise.

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

QObex::ResponseCode QObexFtpClient::lastCommandResponse () const

Returns the last response from the remote service. This could be used to find out the reason a command might have failed (e.g. unauthorized, unsupported, etc)

int QObexFtpClient::list ( const QString & dir = QString() )

Obtains the content listing of the directory given by dir. If dir is an empty string, then the contents of the current working directory are returned.

The listInfo() signal will be sent for all contents of the directory being listed.

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

void QObexFtpClient::listInfo ( const QObexFolderListingEntryInfo & info )   [signal]

This signal is emitted whenever a directory listing information is obtained from the remote service. The directory entry is reported in info.

See also list().

int QObexFtpClient::mkdir ( const QString & dir )

Create a new directory on the server. The directory name is given by dir. If the command succeeds, the current working directory will be the directory just created.

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 QObexFtpClient::put ( QIODevice * dev, const QString & file, qint64 size = 0, const QString & mimetype = QString(), const QString & description = QString(), const QDateTime & lastModified = QDateTime() )

Reads the data from dev and puts it in a 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.

If size is not 0, then it is used for OBEX Length header contents. If mimetype is not empty, it is used for OBEX Type header contents. If description is not empty, it is used for OBEX Description header contents. If lastModified is valid, it is used for OBEX Time header contents.

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

The upload progress 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 QObexFtpClient::put ( const QByteArray & data, const QString & file, const QString & mimetype = QString(), const QString & description = QString(), const QDateTime & lastModified = QDateTime() )

This is an overloaded member function, provided for convenience.

This is an overloaded member function provided for convenience. It is the same as the above function, except the data is obtained directory from data instead of an IO device. The size information is obtained from the size of the byte array. The file, mimetype, description and lastModified parameters have the same meaning as discussed previously.

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

qint64 QObexFtpClient::read ( char * data, qint64 maxlen )

Attempts to read maxlen bytes from the ftp stream and store them in a location pointed to by data.

Returns the number of bytes read or -1 if an error occurred.

See also readAll() and bytesAvailable().

QByteArray QObexFtpClient::readAll ()

Reads all the bytes available from the ftp stream and returns them as a byte array.

See also read() and bytesAvailable().

void QObexFtpClient::readyRead ()   [signal]

This signal is emitted whenever data is ready to be read from the ftp stream.

See also read(), readAll(), and bytesAvailable().

int QObexFtpClient::remove ( const QString & file )

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

int QObexFtpClient::rmdir ( const QString & dir )

Remove the directory dir on the server. Some servers do not allow deletion of non-empty directories. The server should report a PreconditionFailed response code in this case. In general the client should recursively delete all contents of the directory before using this command.

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

QIODevice * QObexFtpClient::sessionDevice () const

Returns the device used by the Ftp Client, as provided in the constructor.

QObexFtpClient::State QObexFtpClient::state () const

Returns the current state of the client.

See also stateChanged().

void QObexFtpClient::stateChanged ( QObexFtpClient::State state )   [signal]

This signal is emitted whenever the Ftp Client has changed state. The new state is reported in state.

See also state().