QUrlOperator Class Reference

The QUrlOperator class provides common operations on URLs (get() and more). More...

#include <qurloperator.h>

Inherits QObject and QUrl.

List of all member functions.

Public Members

• QUrlOperator () 
• QUrlOperator ( const QString & urL ) 
• QUrlOperator ( const QUrlOperator & url ) 
• QUrlOperator ( const QUrlOperator & url, const QString & relUrl, bool checkSlash = FALSE ) 
• virtual ~QUrlOperator () 
• virtual const QNetworkOperation* listChildren () 
• virtual const QNetworkOperation* mkdir ( const QString & dirname ) 
• virtual const QNetworkOperation* remove ( const QString & filename ) 
• virtual const QNetworkOperation* rename ( const QString & oldname, const QString & newname ) 
• virtual const QNetworkOperation* get ( const QString & location = QString::null ) 
• virtual const QNetworkOperation* put ( const QByteArray & data, const QString & location = QString::null ) 
• virtual QList<QNetworkOperation> copy ( const QString & from, const QString & to, bool move = FALSE ) 
• virtual void copy ( const QStringList & files, const QString & dest, bool move = FALSE ) 
• virtual bool isDir ( bool * ok = 0 ) 
• virtual void setNameFilter ( const QString & nameFilter ) 
• QString nameFilter () const
• virtual QUrlInfo info ( const QString & entry ) const
• virtual void stop () 

Signals

• void newChildren ( const QValueList<QUrlInfo> &, QNetworkOperation * res ) 
• void finished ( QNetworkOperation * res ) 
• void start ( QNetworkOperation * res ) 
• void createdDirectory ( const QUrlInfo &, QNetworkOperation * res ) 
• void removed ( QNetworkOperation * res ) 
• void itemChanged ( QNetworkOperation * res ) 
• void data ( const QByteArray &, QNetworkOperation * res ) 
• void dataTransferProgress ( int bytesDone, int bytesTotal, QNetworkOperation * res ) 
• void startedNextCopy ( const QList<QNetworkOperation> & lst ) 
• void connectionStateChanged ( int state, const QString & data ) 

Protected Members

• virtual void clearEntries () 
• void getNetworkProtocol () 
• void deleteNetworkProtocol () 

Detailed Description

This class operates on hierarchical structures (like filesystems) using URLs. Its API allows do all common operations on it (listing children, removing children, renaming, etc.). But the class itself contains no functionality for that. It uses the functionality of registered network protocols. This means, depending of the protocol of the URL, it uses a fitting network protocol class for the operations. In detail, each of the operation methods of QUrlOperator create a QNetworkOperation object which describes the operation and puts it into the operation queue of the used network protocol. If no fitting protocol could be found (because no implementation of the needed network protocol is registered), the url operator emits errors. Also not each protocol supports each operation - but the error handling deals with this problem.

A QUrlOperator can be used like this (for e.g. downloading a file)

  QUrlOperator op;
  op.copy( QString("ftp://ftp.trolltech.com/qt/source/qt-2.1.0.tar.gz"), "file:/tmp", FALSE );

Now, you also will connect to some signals of the QUrlOperator to get informed about success, errors, progress and more things.

Of course an implementation for the FTP protocol has to be registered for this example. In the Qt Network Extension Library there is an implementation of the FTP protocol.

For more information about the Qt Network Architecture take a look at the Qt Network Documentation.

See also QNetworkProtocol and QNetworkOperation.

Member Function Documentation

QUrlOperator::QUrlOperator ()

Constructs a QUrlOperator with an empty (i.e. invalid) URL.

QUrlOperator::QUrlOperator ( const QString & url )

Constructs a QUrlOperator using url and parses this string.

You can pass strings such as "/home/qt": in this case the protocol "file" is assumed.

QUrlOperator::QUrlOperator ( const QUrlOperator & url )

Copy constructor.

QUrlOperator::QUrlOperator ( const QUrlOperator & url, const QString & relUrl, bool checkSlash = FALSE )

Constructs a QUrlOperator. The URL on which this QUrlOperator works on is constructed out of the arguments url, relUrl and checkSlash; the meaning of those arguments is the same as the corresponding QUrl constructor takes.

QUrlOperator::~QUrlOperator () [virtual]

Destructor.

bool QUrlOperator::cdUp () [virtual]

Reimplemented for internal reasons; the API is not affected.

bool QUrlOperator::checkValid () [virtual protected]

Reimplemented for internal reasons; the API is not affected.

void QUrlOperator::clearEntries () [virtual protected]

Clears the cache of children.

void QUrlOperator::connectionStateChanged ( int state, const QString & data ) [signal]

This signal is emitted whenever the state of the connection of the network protocol of the url operator is changed. state describes the new state, which is one of QNetworkProtocol::ConHostFound, QNetworkProtocol::ConConnected, QNetworkProtocol::ConClosed This enum is defined in QNetworkProtocol data is a message text.

QList<QNetworkOperation> QUrlOperator::copy ( const QString & from, const QString & to, bool move = FALSE ) [virtual]

Copies the file from to to. If move is TRUE, the file is moved (copied and removed). from has to point to a file and to must point to a directory (into which from is copied). The copying is done using get() and put() operations. If you want to get notified about the progress of the operation, connect to the dataTransferProgress() signal. But you have to know, that the get() and the put() operations emit this signal through the QUrlOperator! So, the number of transferred and total bytes which you get as argument in this signal isn't related to the the whole copy operation, but first to the get() and then to the put() operation. So always check for the type of the operation from which the signal comes (you get this by asking for the type of the QNetworkOperation pointer you also get as last argument of this signal).

Also at the end finished() (on success or failure) is emitted, so check the state of the network operation object to see if the operation was successful or not.

As a copy operation consists of multiple operations (get(), put() and maybe remove() (depending if you copy or move)) this method doesn't return a single QNetworkOperation, but a list of them. They are in the order get(), put(), remove(). As discussed, the third one (remove) is optional.

See also get() and put().

void QUrlOperator::copy ( const QStringList & files, const QString & dest, bool move = FALSE ) [virtual]

Copies files to the directory dest. If move is TRUE, the files are moved and not copied. dest has to point to a directory.

This method is just a convenience function of the copy method above. It calls the copy above for each entry in files one after the other. You don't get a result from this method, but each time a new copy is started, startedNextCopy() is emitted, with a list of QNetworkOperations which describe the new copy operation.

void QUrlOperator::createdDirectory ( const QUrlInfo & i, QNetworkOperation * op ) [signal]

This signal is emitted when mkdir() has been succesful and the directory has been created. i holds the information about the new directory. op is the pointer to the operation object, which contains all infos of the operation, including the state and so on and using op->arg( 0 ) you also get the filename of the new directory.

See also QNetworkOperation and QNetworkProtocol.

void QUrlOperator::data ( const QByteArray & data, QNetworkOperation * op ) [signal]

This signal is emitted when new data has been received after e.g. calling get() or put(). op holds the name of the file which data is retrieved in the first argument and the data in the second argument (raw). You get them with op->arg( 0 ) and op->rawArg( 1 ).

op is the pointer to the operation object, which contains all infos of the operation, including the state and so on.

See also QNetworkOperation and QNetworkProtocol.

void QUrlOperator::dataTransferProgress ( int bytesDone, int bytesTotal, QNetworkOperation * op ) [signal]

When transferring data (using put() or get()) this signal is emitted during the progress. bytesDone tells how many bytes of bytesTotal are transferred. More information about the operation is stored in the op, the pointer to the network operation which is processed. bytesTotal may be -1, which means that the number of total bytes is not known.

See also QNetworkOperation and QNetworkProtocol.

void QUrlOperator::deleteNetworkProtocol () [protected]

Delete the currently used network protocol.

void QUrlOperator::finished ( QNetworkOperation * op ) [signal]

This signal is emitted when an operation of some sort finished. This signal is emitted always, this means on success and on failure. op is the pointer to the operation object, which contains all infos of the operation which has been finished, including the state and so on. To check if the operation was successful or not, check the state and error code of the operation object.

See also QNetworkOperation and QNetworkProtocol.

const QNetworkOperation * QUrlOperator::get ( const QString & location = QString::null ) [virtual]

Tells the network protocol to get data from location or, if this is QString::null, to get data from the location to which this URL points (see QUrl::fileName() and QUrl::encodedPathAndQuery()). What exactly happens then is depending on the network protocol. When data comes in, the data() signal is emitted. As it's unlikely that all the data comes in at once, multiple data() signals will be emitted. During processing the operation the dataTransferProgress() is emitted. Also at the end finished() (on success or failure) is emitted, so check the state of the network operation object to see if the operation was successful or not.

Now, if location is QString::null, the path of this QUrlOperator should point to a file when you use this operation. If location is not empty, it can be relative (a child of the path to which the QUrlOperator points) or an absolute URL.

E.g. for getting a Web page you might do something like

  QUrlOperator op( "http://www.whatever.org/cgi-bin/search.pl?cmd=Hallo" );
  op.get();

But as for the most other operations it is required that the path of the QUrlOperator points to a directory, you could do following if you want e.g. download a file

  QUrlOperator op( "ftp://ftp.whatever.org/pub" );
  // do some other stuff like op.listChildren() or op.mkdir( "new Dir" )
  op.get( "a_file.txt" );

This will get the data of ftp://ftp.whatever.org/pub/a_file.txt.

But never do something like

  QUrlOperator op( "http://www.whatever.org/cgi-bin" );
  op.get( "search.pl?cmd=Hallo" );

This means if location is not empty and relative, it must not contain any queries or references, just the name of a child. So, if you need to specify a query or reference do it like in the first example or specify the full URL (like http://www.whatever.org/cgi-bin/search.pl?cmd=Hallo) as location.

See also copy().

void QUrlOperator::getNetworkProtocol () [protected]

Finds a network protocol for the URL and deletes the old network protocol.

QUrlInfo QUrlOperator::info ( const QString & entry ) const [virtual]

Returns the URL information for the child entry or en empty QUrlInfo object of there is no information available about entry.

bool QUrlOperator::isDir ( bool * ok = 0 ) [virtual]

Returns TRUE if the url is a directory, else returns FALSE. This may not always work correctly, if the protocol of the URL is something else than file (local filesystem)! If you pass a bool as ok argument, this is set to TRUE, if the result of this method is correct for sure, else ok is set to FALSE.

void QUrlOperator::itemChanged ( QNetworkOperation * op ) [signal]

This signal is emitted whenever a file, which is a child of this URL, has been changed e.g. by successfully calling rename(). op holds the original and the new filenames in the first and second arguments. You get them with op->arg( 0 ) and op->arg( 1 ).

op is the pointer to the operation object, which contains all infos of the operation, including the state and so on.

See also QNetworkOperation and QNetworkProtocol.

const QNetworkOperation * QUrlOperator::listChildren () [virtual]

Starts listing the children of this URL (e.g. of a directory). The signal start() is emitted, before the first entry is listed, and after the last one finished() is emitted. For each list of new entries, the newChildren() signals is emitted. If an error occurs, also the signal finished() is emitted, so check the state of the network operation pointer!

As the operation will not be executed immediately, a pointer to the QNetworkOperation object, which is created by this method, is returned. This object contains all data about the operation and is used to refer to this operation later (e.g. in the signals which are emitted by the QUrlOperator). The return value can be also 0 if the operation object couldn't be created.

The path of this QUrlOperator has to point to a directory, because the children of this directory will be listed, and not to a file, else this operation might not work!.

const QNetworkOperation * QUrlOperator::mkdir ( const QString & dirname ) [virtual]

Tries to create a directory (child) with the name dirname. If it has been successful a newChildren() signal with the new child is emitted, and the createdDirectory() signal with the information about the new child is emitted too. Also finished() (on success or failure) is emitted, after the operation has been processed, so check the state of the network operation object to see if the operation was successful or not.

As the operation will not be executed immediately, a pointer to the QNetworkOperation object, which is created by this method, is returned. This object contains all data about the operation and is used to refer to this operation later (e.g. in the signals which are emitted by the QUrlOperator). The return value can be also 0 if the operation object couldn't be created.

This path of this QUrlOperator has to point to a directory, as the new directory will be created in this path, and not to a file, else this operation might not work!.

QString QUrlOperator::nameFilter () const

Returns the name filter of the URL

See also QUrlOperator::setNameFilter() and QDir::nameFilter().

void QUrlOperator::newChildren ( const QValueList<QUrlInfo> & i, QNetworkOperation * op ) [signal]

This signal is emitted after listChildren() was called and new children (e.g. files) have been read from a list of files. i holds the information about the new children. op is the pointer to the operation object, which contains all infos of the operation, including the state and so on.

See also QNetworkOperation and QNetworkProtocol.

QUrlOperator& QUrlOperator::operator= ( const QString & url )

Reimplemented for internal reasons; the API is not affected.

QUrlOperator& QUrlOperator::operator= ( const QUrlOperator & url )

Reimplemented for internal reasons; the API is not affected.

bool QUrlOperator::parse ( const QString & url ) [virtual protected]

Reimplemented for internal reasons; the API is not affected.

const QNetworkOperation * QUrlOperator::put ( const QByteArray & data, const QString & location = QString::null ) [virtual]

Tells the network protocol to put data to location, or if this is empty (QString::null) it puts the data to the location to which the URL points. What exactly happens is depending on the network protocol. Also depending on the network protocol after putting data some data might come back. In this case the data() signal is emitted. During processing the operation the dataTransferProgress() is emitted. Also at the end finished() (on success or failure) is emitted, so check the state of the network operation object to see if the operation was successful or not.

Now, if location is QString::null, the path of this QUrlOperator should point to a file when you use this operation. If location is not empty, it can be relative (a child of the path to which the QUrlOperator points) or an absolute URL.

E.g. for putting some data to a file you can do

  QUrlOperator op( "ftp://ftp.whatever.com/home/me/filename" );
  op.put( data );

But as for the most other operations it is required that the path of the QUrlOperator points to a directory, you could do following if you want e.g. upload data to a file

  QUrlOperator op( "ftp://ftp.whatever.com/home/me" );
  // do some other stuff like op.listChildren() or op.mkdir( "new Dir" )
  op.put( data, "filename" );

This will upload the data to ftp://ftp.whatever.com/home/me/filename.

See also copy().

const QNetworkOperation * QUrlOperator::remove ( const QString & filename ) [virtual]

Tries to remove the file (child) filename. If it has been successful the signal removed() is emitted. Also finished() (on success or failure) is emitted after the operation has been processed, so check the state of the network operation object to see if the operation was successful or not.

As the operation will not be executed immediately, a pointer to the QNetworkOperation object, which is created by this method, is returned. This object contains all data about the operation and is used to refer to this operation later (e.g. in the signals which are emitted by the QUrlOperator). The return value can be also 0 if the operation object couldn't be created.

This path of this QUrlOperator has to point to a directory, because if filename is relative, it will be tried to remove it in this directory, and not to a file, else this operation might not work!.

void QUrlOperator::removed ( QNetworkOperation * op ) [signal]

This signal is emitted when remove() has been succesful and the file has been removed. op holds the filename of the removed file in the first argument, you get it with op->arg( 0 ).

op is the pointer to the operation object, which contains all infos of the operation, including the state and so on.

See also QNetworkOperation and QNetworkProtocol.

const QNetworkOperation * QUrlOperator::rename ( const QString & oldname, const QString & newname ) [virtual]

Tries to rename the file (child) oldname by newname. If it has been successful the signal itemChanged() is emitted. Also finished() (on success or failure) is emitted after the operation has been processed, so check the state of the network operation object to see if the operation was successful or not.

As the operation will not be executed immediately, a pointer to the QNetworkOperation object, which is created by this method, is returned. This object contains all data about the operation and is used to refer to this operation later (e.g. in the signals which are emitted by the QUrlOperator). The return value can be also 0 if the operation object couldn't be created.

This path of this QUrlOperator has to point to a directory, as oldname and newname are handled relatively to this directory, and not to a file, else this operation might not work!.

void QUrlOperator::reset () [virtual protected]

Reimplemented for internal reasons; the API is not affected.

void QUrlOperator::setNameFilter ( const QString & nameFilter ) [virtual]

Sets the name filter of the URL

See also QDir::setNameFilter().

void QUrlOperator::setPath ( const QString & path ) [virtual]

Reimplemented for internal reasons; the API is not affected.

void QUrlOperator::start ( QNetworkOperation * op ) [signal]

Some operations (like listChildren()) emit this signal when they start processing the operation. op is the pointer to the operation object, which contains all infos of the operation, including the state and so on.

See also QNetworkOperation and QNetworkProtocol.

void QUrlOperator::startedNextCopy ( const QList<QNetworkOperation> & lst ) [signal]

This signal is emitted if copy() started a new copy operation. lst contains all QNetworkOperations which describe this copy operation.

See also copy().

void QUrlOperator::stop () [virtual]

Stops the current network operation which is just processed and removes all waiting network operations of this QUrlOperator.

Search the documentation, FAQ, qt-interest archive and more (uses www.trolltech.com):

This file is part of the Qt toolkit, copyright © 1995-2005 Trolltech, all rights reserved.