QUrlOperator(3qt)QUrlOperator(3qt)NAMEQUrlOperator - Common operations on URLs (
#include <qurloperator.h>
Inherits QObject and QUrl.
Public Members
QUrlOperator ( const QUrlOperator & url )
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 ()
Trolltech AS 13 June 2001 1
QUrlOperator(3qt)QUrlOperator(3qt)DESCRIPTION
The QUrlOperator class provides common operations on URLs
(get() and more).
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( "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 DOCUMENTATIONQUrlOperator::QUrlOperator ()
Reimplemented for internal reasons; the API is not
affected.
QUrlOperator::QUrlOperator ( const QString & url )
Reimplemented for internal reasons; the API is not
affected.
QUrlOperator::QUrlOperator ( const QUrlOperator & url )
Copy constructor.
QUrlOperator::QUrlOperator ( const QUrlOperator & url, const
QString & relUrl, bool checkSlash = FALSE )
Trolltech AS 13 June 2001 2
QUrlOperator(3qt)QUrlOperator(3qt)
Reimplemented for internal reasons; the API is not
affected.
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
Trolltech AS 13 June 2001 3
QUrlOperator(3qt)QUrlOperator(3qt)
(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.
Trolltech AS 13 June 2001 4
QUrlOperator(3qt)QUrlOperator(3qt)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" );
Trolltech AS 13 June 2001 5
QUrlOperator(3qt)QUrlOperator(3qt)
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
Trolltech AS 13 June 2001 6
QUrlOperator(3qt)QUrlOperator(3qt)
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.
Trolltech AS 13 June 2001 7
QUrlOperator(3qt)QUrlOperator(3qt)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
Trolltech AS 13 June 2001 8
QUrlOperator(3qt)QUrlOperator(3qt)
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.
Trolltech AS 13 June 2001 9
QUrlOperator(3qt)QUrlOperator(3qt)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.
SEE ALSO
http://doc.trolltech.com/qurloperator.html
http://www.trolltech.com/faq/tech.html
COPYRIGHT
Copyright 1992-2001 Trolltech AS,
http://www.trolltech.com. See the license file included
in the distribution for a complete license statement.
AUTHOR
Generated automatically from the source code.
BUGS
If you find a bug in Qt, please report it as described in
http://doc.trolltech.com/bughowto.html. Good bug reports
make our job much simpler. Thank you.
In case of content or formattting problems with this
manual page, please report them to qt-bugs@trolltech.com.
Please include the name of the manual page
(qurloperator.3qt) and the Qt version (2.3.1).
Trolltech AS 13 June 2001 10
