1QUrlOperator(3qt)                                            QUrlOperator(3qt)
2
3
4

NAME

6       QUrlOperator - Common operations on URLs
7

SYNOPSIS

9       #include <qurloperator.h>
10
11       Inherits QObject and QUrl.
12
13   Public Members
14       QUrlOperator ()
15       QUrlOperator ( const QString & url )
16       QUrlOperator ( const QUrlOperator & url )
17       QUrlOperator ( const QUrlOperator & url, const QString & relUrl, bool
18           checkSlash = FALSE )
19       virtual ~QUrlOperator ()
20       virtual const QNetworkOperation * listChildren ()
21       virtual const QNetworkOperation * mkdir ( const QString & dirname )
22       virtual const QNetworkOperation * remove ( const QString & filename )
23       virtual const QNetworkOperation * rename ( const QString & oldname,
24           const QString & newname )
25       virtual const QNetworkOperation * get ( const QString & location =
26           QString::null )
27       virtual const QNetworkOperation * put ( const QByteArray & data, const
28           QString & location = QString::null )
29       virtual QPtrList<QNetworkOperation> copy ( const QString & from, const
30           QString & to, bool move = FALSE, bool toPath = TRUE )
31       virtual void copy ( const QStringList & files, const QString & dest,
32           bool move = FALSE )
33       virtual bool isDir ( bool * ok = 0 )
34       virtual void setNameFilter ( const QString & nameFilter )
35       QString nameFilter () const
36       virtual QUrlInfo info ( const QString & entry ) const
37       virtual void stop ()
38
39   Signals
40       void newChildren ( const QValueList<QUrlInfo> & i, QNetworkOperation *
41           op )
42       void finished ( QNetworkOperation * op )
43       void start ( QNetworkOperation * op )
44       void createdDirectory ( const QUrlInfo & i, QNetworkOperation * op )
45       void removed ( QNetworkOperation * op )
46       void itemChanged ( QNetworkOperation * op )
47       void data ( const QByteArray & data, QNetworkOperation * op )
48       void dataTransferProgress ( int bytesDone, int bytesTotal,
49           QNetworkOperation * op )
50       void startedNextCopy ( const QPtrList<QNetworkOperation> & lst )
51       void connectionStateChanged ( int state, const QString & data )
52
53   Protected Members
54       virtual void clearEntries ()
55       void getNetworkProtocol ()
56       void deleteNetworkProtocol ()
57
59       void qInitNetworkProtocols ()
60

DESCRIPTION

62       The QUrlOperator class provides common operations on URLs.
63
64       This class operates on hierarchical structures (such as filesystems)
65       using URLs. Its API facilitates all the common operations: <center>.nf
66
67       </center>
68
69       You can obtain additional information about the URL with isDir() and
70       info(). If a directory is to be traversed using listChildren(), a name
71       filter can be set with setNameFilter().
72
73       A QUrlOperator can be used like this, for example to download a file
74       (and assuming that the FTP protocol is registered):
75
76           QUrlOperator *op = new QUrlOperator();
77           op->copy( QString("ftp://ftp.trolltech.com/qt/source/qt-2.1.0.tar.gz"),
78                    "file:/tmp" );
79
80       If you want to be notified about success/failure, progress, etc., you
81       can connect to QUrlOperator's signals, e.g. to start(), newChildren(),
82       createdDirectory(), removed(), data(), dataTransferProgress(),
83       startedNextCopy(), connectionStateChanged(), finished(), etc. A network
84       operation can be stopped with stop().
85
86       The class uses the functionality of registered network protocols to
87       perform these operations. Depending of the protocol of the URL, it uses
88       an appropriate network protocol class for the operations. Each of the
89       operation functions of QUrlOperator creates a QNetworkOperation object
90       that describes the operation and puts it into the operation queue for
91       the network protocol used. If no suitable protocol could be found
92       (because no implementation of the necessary network protocol is
93       registered), the URL operator emits errors. Not every protocol supports
94       every operation, but error handling deals with this problem.
95
96       To register the available network protocols, use the
97       qInitNetworkProtocols() function. The protocols currently supported
98       are:
99
100       FTP,
101
102       HTTP,
103
104       local file system.
105
106       For more information about the Qt Network Architecture see the Qt
107       Network Documentation.
108
109       See also QNetworkProtocol, QNetworkOperation, Input/Output and
110       Networking, and Miscellaneous Classes.
111

MEMBER FUNCTION DOCUMENTATION

QUrlOperator::QUrlOperator ()

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

QUrlOperator::QUrlOperator ( const QString & url )

117       Constructs a QUrlOperator using url and parses this string.
118
119       If you pass strings like "/home/qt" the "file" protocol is assumed.
120

QUrlOperator::QUrlOperator ( const QUrlOperator & url )

122       Constructs a copy of url.
123

QUrlOperator::QUrlOperator ( const QUrlOperator & url, const QString & relUrl,

125       bool checkSlash = FALSE )
126       Constructs a QUrlOperator. The URL on which this QUrlOperator operates
127       is constructed out of the arguments url, relUrl and checkSlash: see the
128       corresponding QUrl constructor for an explanation of these arguments.
129

QUrlOperator::~QUrlOperator () [virtual]

131       Destructor.
132

void QUrlOperator::clearEntries () [virtual protected]

134       Clears the cache of children.
135

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

137       [signal]
138       This signal is emitted whenever the URL operator's connection state
139       changes. state describes the new state, which is a
140       QNetworkProtocol::ConnectionState value.
141
142       data is a string that describes the change of the connection. This can
143       be used to display a message to the user.
144

QPtrList<QNetworkOperation> QUrlOperator::copy ( const QString & from, const

146       QString & to, bool move = FALSE, bool toPath = TRUE ) [virtual]
147       Copies the file from to to. If move is TRUE, the file is moved (copied
148       and removed). from must point to a file and to must point to a
149       directory (into which from is copied) unless toPath is set to FALSE. If
150       toPath is set to FALSE then the to variable is assumed to be the
151       absolute file path (destination file path + file name). The copying is
152       done using the get() and put() operations. If you want to be notified
153       about the progress of the operation, connect to the
154       dataTransferProgress() signal. Bear in mind that the get() and put()
155       operations emit this signal through the QUrlOperator. The number of
156       transferred bytes and the total bytes that you receive as arguments in
157       this signal do not relate to the the whole copy operation; they relate
158       first to the get() and then to the put() operation. Always check what
159       type of operation the signal comes from; this is given in the signal's
160       last argument.
161
162       At the end, finished() (with success or failure) is emitted, so check
163       the state of the network operation object to see whether or not the
164       operation was successful.
165
166       Because a move or copy operation consists of multiple operations
167       (get(), put() and maybe remove()), this function doesn't return a
168       single QNetworkOperation, but rather a list of them. They are in the
169       order: get(), put() and (if applicable) remove().
170
171       See also get() and put().
172

void QUrlOperator::copy ( const QStringList & files, const QString & dest,

174       bool move = FALSE ) [virtual]
175       This is an overloaded member function, provided for convenience. It
176       behaves essentially like the above function.
177
178       Copies the files to the directory dest. If move is TRUE the files are
179       moved, not copied. dest must point to a directory.
180
181       This function calls copy() for each entry in files in turn. You don't
182       get a result from this function; each time a new copy begins,
183       startedNextCopy() is emitted, with a list of QNetworkOperations that
184       describe the new copy operation.
185

void QUrlOperator::createdDirectory ( const QUrlInfo & i, QNetworkOperation *

187       op ) [signal]
188       This signal is emitted when mkdir() succeeds and the directory has been
189       created. i holds the information about the new directory.
190
191       op is a pointer to the operation object, which contains all the
192       information about the operation, including the state. op->arg(0) holds
193       the new directory's name.
194
195       See also QNetworkOperation and QNetworkProtocol.
196

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

198       [signal]
199       This signal is emitted when new data has been received after calling
200       get() or put(). op is a pointer to the operation object which contains
201       all the information about the operation, including the state.
202       op->arg(0) holds the name of the file whose data is retrieved and
203       op->rawArg(1) holds the (raw) data.
204
205       See also QNetworkOperation and QNetworkProtocol.
206

void QUrlOperator::dataTransferProgress ( int bytesDone, int bytesTotal,

208       QNetworkOperation * op ) [signal]
209       This signal is emitted during data transfer (using put() or get()).
210       bytesDone specifies how many bytes of bytesTotal have been transferred.
211       More information about the operation is stored in op, a pointer to the
212       network operation that is processed. bytesTotal may be -1, which means
213       that the total number of bytes is not known.
214
215       See also QNetworkOperation and QNetworkProtocol.
216

void QUrlOperator::deleteNetworkProtocol () [protected]

218       Deletes the currently used network protocol.
219

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

221       This signal is emitted when an operation of some sort finishes, whether
222       with success or failure. op is a pointer to the operation object, which
223       contains all the information, including the state, of the operation
224       which has been finished. Check the state and error code of the
225       operation object to see whether or not the operation was successful.
226
227       See also QNetworkOperation and QNetworkProtocol.
228

const QNetworkOperation * QUrlOperator::get ( const QString & location =

230       QString::null ) [virtual]
231       Tells the network protocol to get data from location or, if this is
232       QString::null, to get data from the location to which this URL points
233       (see QUrl::fileName() and QUrl::encodedPathAndQuery()). What happens
234       then depends on the network protocol. The data() signal is emitted when
235       data comes in. Because it's unlikely that all data will come in at
236       once, it is common for multiple data() signals to be emitted. The
237       dataTransferProgress() signal is emitted while processing the
238       operation. At the end, finished() (with success or failure) is emitted,
239       so check the state of the network operation object to see whether or
240       not the operation was successful.
241
242       If location is QString::null, the path of this QUrlOperator should
243       point to a file when you use this operation. If location is not empty,
244       it can be a relative URL (a child of the path to which the QUrlOperator
245       points) or an absolute URL.
246
247       For example, to get a web page you might do something like this:
248
249           QUrlOperator op( "http://www.whatever.org/cgi-bin/search.pl?cmd=Hello" );
250           op.get();
251
252       For most other operations, the path of the QUrlOperator must point to a
253       directory. If you want to download a file you could do the following:
254
255           QUrlOperator op( "ftp://ftp.whatever.org/pub" );
256           // do some other stuff like op.listChildren() or op.mkdir( "new_dir" )
257           op.get( "a_file.txt" );
258
259       This will get the data of ftp://ftp.whatever.org/pub/a_file.txt.
260
261       Never do anything like this:
262
263           QUrlOperator op( "http://www.whatever.org/cgi-bin" );
264           op.get( "search.pl?cmd=Hello" ); // WRONG!
265
266       If location is not empty and relative it must not contain any queries
267       or references, just the name of a child. So if you need to specify a
268       query or reference, do it as shown in the first example or specify the
269       full URL (such as http://www.whatever.org/cgi-bin/search.pl?cmd=Hello)
270       as location.
271
272       See also copy().
273

void QUrlOperator::getNetworkProtocol () [protected]

275       Finds a network protocol for the URL and deletes the old network
276       protocol.
277

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

279       Returns the URL information for the child entry, or returns an empty
280       QUrlInfo object if there is no information available about entry.
281       Information about entry is only available after a successfully finished
282       listChildren() operation.
283

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

285       Returns TRUE if the URL is a directory; otherwise returns FALSE. This
286       may not always work correctly, if the protocol of the URL is something
287       other than file (local filesystem). If you pass a bool pointer as the
288       ok argument, *ok is set to TRUE if the result of this function is known
289       to be correct, and to FALSE otherwise.
290

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

292       This signal is emitted whenever a file which is a child of the URL has
293       been changed, for example by successfully calling rename(). op is a
294       pointer to the operation object which contains all the information
295       about the operation, including the state. op->arg(0) holds the original
296       file name and op->arg(1) holds the new file name (if it was changed).
297
298       See also QNetworkOperation and QNetworkProtocol.
299

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

301       Starts listing the children of this URL (e.g. the files in the
302       directory). The start() signal is emitted before the first entry is
303       listed and finished() is emitted after the last one. The newChildren()
304       signal is emitted for each list of new entries. If an error occurs, the
305       signal finished() is emitted, so be sure to check the state of the
306       network operation pointer.
307
308       Because the operation may not be executed immediately, a pointer to the
309       QNetworkOperation object created by this function is returned. This
310       object contains all the data about the operation and is used to refer
311       to this operation later (e.g. in the signals that are emitted by the
312       QUrlOperator). The return value can also be 0 if the operation object
313       couldn't be created.
314
315       The path of this QUrlOperator must to point to a directory (because the
316       children of this directory will be listed), not to a file.
317

const QNetworkOperation * QUrlOperator::mkdir ( const QString & dirname )

319       [virtual]
320       Tries to create a directory (child) with the name dirname. If it is
321       successful, a newChildren() signal with the new child is emitted, and
322       the createdDirectory() signal with the information about the new child
323       is also emitted. The finished() signal (with success or failure) is
324       emitted after the operation has been processed, so check the state of
325       the network operation object to see whether or not the operation was
326       successful.
327
328       Because the operation will not be executed immediately, a pointer to
329       the QNetworkOperation object created by this function is returned. This
330       object contains all the data about the operation and is used to refer
331       to this operation later (e.g. in the signals that are emitted by the
332       QUrlOperator). The return value can also be 0 if the operation object
333       couldn't be created.
334
335       The path of this QUrlOperator must to point to a directory (not a file)
336       because the new directory will be created in this path.
337

QString QUrlOperator::nameFilter () const

339       Returns the name filter of the URL.
340
341       See also QUrlOperator::setNameFilter() and QDir::nameFilter().
342

void QUrlOperator::newChildren ( const QValueList<QUrlInfo> & i,

344       QNetworkOperation * op ) [signal]
345       This signal is emitted after listChildren() was called and new children
346       (i.e. files) have been read from a list of files. i holds the
347       information about the new files. op is a pointer to the operation
348       object which contains all the information about the operation,
349       including the state.
350
351       See also QNetworkOperation and QNetworkProtocol.
352

const QNetworkOperation * QUrlOperator::put ( const QByteArray & data, const

354       QString & location = QString::null ) [virtual]
355       This function tells the network protocol to put data in location. If
356       location is empty (QString::null), it puts the data in the location to
357       which the URL points. What happens depends on the network protocol.
358       Depending on the network protocol, some data might come back after
359       putting data, in which case the data() signal is emitted. The
360       dataTransferProgress() signal is emitted during processing of the
361       operation. At the end, finished() (with success or failure) is emitted,
362       so check the state of the network operation object to see whether or
363       not the operation was successful.
364
365       If location is QString::null, the path of this QUrlOperator should
366       point to a file when you use this operation. If location is not empty,
367       it can be a relative (a child of the path to which the QUrlOperator
368       points) or an absolute URL.
369
370       For putting some data to a file you can do the following:
371
372           QUrlOperator op( "ftp://ftp.whatever.com/home/me/filename.dat" );
373           op.put( data );
374
375       For most other operations, the path of the QUrlOperator must point to a
376       directory. If you want to upload data to a file you could do the
377       following:
378
379           QUrlOperator op( "ftp://ftp.whatever.com/home/me" );
380           // do some other stuff like op.listChildren() or op.mkdir( "new_dir" )
381           op.put( data, "filename.dat" );
382
383       This will upload the data to
384       ftp://ftp.whatever.com/home/me/filename.dat.
385
386       See also copy().
387

const QNetworkOperation * QUrlOperator::remove ( const QString & filename )

389       [virtual]
390       Tries to remove the file (child) filename. If it succeeds the removed()
391       signal is emitted. finished() (with success or failure) is also emitted
392       after the operation has been processed, so check the state of the
393       network operation object to see whether or not the operation was
394       successful.
395
396       Because the operation will not be executed immediately, a pointer to
397       the QNetworkOperation object created by this function is returned. This
398       object contains all the data about the operation and is used to refer
399       to this operation later (e.g. in the signals that are emitted by the
400       QUrlOperator). The return value can also be 0 if the operation object
401       couldn't be created.
402
403       The path of this QUrlOperator must point to a directory; because if
404       filename is relative, it will try to remove it in this directory.
405

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

407       This signal is emitted when remove() has been succesful and the file
408       has been removed.
409
410       op is a pointer to the operation object which contains all the
411       information about the operation, including the state. op->arg(0) holds
412       the name of the file that was removed.
413
414       See also QNetworkOperation and QNetworkProtocol.
415

const QNetworkOperation * QUrlOperator::rename ( const QString & oldname,

417       const QString & newname ) [virtual]
418       Tries to rename the file (child) called oldname to newname. If it
419       succeeds, the itemChanged() signal is emitted. finished() (with success
420       or failure) is also emitted after the operation has been processed, so
421       check the state of the network operation object to see whether or not
422       the operation was successful.
423
424       Because the operation may not be executed immediately, a pointer to the
425       QNetworkOperation object created by this function is returned. This
426       object contains all the data about the operation and is used to refer
427       to this operation later (e.g. in the signals that are emitted by the
428       QUrlOperator). The return value can also be 0 if the operation object
429       couldn't be created.
430
431       This path of this QUrlOperator must to point to a directory because
432       oldname and newname are handled relative to this directory.
433

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

435       Sets the name filter of the URL to nameFilter.
436
437       See also QDir::setNameFilter().
438

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

440       Some operations (such as listChildren()) emit this signal when they
441       start processing the operation. op is a pointer to the operation object
442       which contains all the information about the operation, including the
443       state.
444
445       See also QNetworkOperation and QNetworkProtocol.
446

void QUrlOperator::startedNextCopy ( const QPtrList<QNetworkOperation> & lst )

448       [signal]
449       This signal is emitted if copy() starts a new copy operation. lst
450       contains all QNetworkOperations related to this copy operation.
451
452       See also copy().
453

void QUrlOperator::stop () [virtual]

455       Stops the current network operation and removes all this QUrlOperator's
456       waiting network operations.
457

void qInitNetworkProtocols ()

460       This function registers the network protocols for FTP and HTTP. You
461       must call this function before you use QUrlOperator for these
462       protocols.
463
464       This function is declared in qnetwork.h.
465
466

SEE ALSO

468       http://doc.trolltech.com/qurloperator.html
469       http://www.trolltech.com/faq/tech.html
470
472       Copyright 1992-2007 Trolltech ASA, http://www.trolltech.com.  See the
473       license file included in the distribution for a complete license
474       statement.
475

AUTHOR

477       Generated automatically from the source code.
478

BUGS

480       If you find a bug in Qt, please report it as described in
481       http://doc.trolltech.com/bughowto.html.  Good bug reports help us to
482       help you. Thank you.
483
484       The definitive Qt documentation is provided in HTML format; it is
485       located at $QTDIR/doc/html and can be read using Qt Assistant or with a
486       web browser. This man page is provided as a convenience for those users
487       who prefer man pages, although this format is not officially supported
488       by Trolltech.
489
490       If you find errors in this manual page, please report them to qt-
491       bugs@trolltech.com.  Please include the name of the manual page
492       (qurloperator.3qt) and the Qt version (3.3.8).
493
494
495
496Trolltech AS                    2 February 2007              QUrlOperator(3qt)
Impressum