1QUrlOperator(3qt) QUrlOperator(3qt)
2
6 QUrlOperator - Common operations on URLs
7
9 #include <qurloperator.h>
10 Inherits QObject and QUrl.
12 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 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 Protected Members
54 virtual void clearEntries ()
55 void getNetworkProtocol ()
56 void deleteNetworkProtocol ()
57
59 void qInitNetworkProtocols ()
60
62 The QUrlOperator class provides common operations on URLs.
63 This class operates on hierarchical structures (such as filesystems)
65 using URLs. Its API facilitates all the common operations: <center>.nf
66 </center>
68 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 A QUrlOperator can be used like this, for example to download a file
74 (and assuming that the FTP protocol is registered):
75 QUrlOperator *op = new QUrlOperator();
77 op->copy( QString("ftp://ftp.trolltech.com/qt/source/qt-2.1.0.tar.gz"),
78 "file:/tmp" );
79 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 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 To register the available network protocols, use the
97 qInitNetworkProtocols() function. The protocols currently supported
98 are:
99 FTP,
101 HTTP,
103 local file system.
105 For more information about the Qt Network Architecture see the Qt
107 Network Documentation.
108 See also QNetworkProtocol, QNetworkOperation, Input/Output and
110 Networking, and Miscellaneous Classes.
111
114 Constructs a QUrlOperator with an empty (i.e. invalid) URL.
115
117 Constructs a QUrlOperator using url and parses this string.
118 If you pass strings like "/home/qt" the "file" protocol is assumed.
120
122 Constructs a copy of url.
123
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
131 Destructor.
132
134 Clears the cache of children.
135
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 data is a string that describes the change of the connection. This can
143 be used to display a message to the user.
144
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 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 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 See also get() and put().
172
174 bool move = FALSE ) [virtual]
175 This is an overloaded member function, provided for convenience. It
176 behaves essentially like the above function.
177 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 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
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 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 See also QNetworkOperation and QNetworkProtocol.
196
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 See also QNetworkOperation and QNetworkProtocol.
206
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 See also QNetworkOperation and QNetworkProtocol.
216
218 Deletes the currently used network protocol.
219
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 See also QNetworkOperation and QNetworkProtocol.
228
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 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 For example, to get a web page you might do something like this:
248 QUrlOperator op( "http://www.whatever.org/cgi-bin/search.pl?cmd=Hello" );
250 op.get();
251 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 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 This will get the data of ftp://ftp.whatever.org/pub/a_file.txt.
260 Never do anything like this:
262 QUrlOperator op( "http://www.whatever.org/cgi-bin" );
264 op.get( "search.pl?cmd=Hello" ); // WRONG!
265 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 See also copy().
273
275 Finds a network protocol for the URL and deletes the old network
276 protocol.
277
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
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
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 See also QNetworkOperation and QNetworkProtocol.
299
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 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 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
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 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 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
339 Returns the name filter of the URL.
340 See also QUrlOperator::setNameFilter() and QDir::nameFilter().
342
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 See also QNetworkOperation and QNetworkProtocol.
352
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 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 For putting some data to a file you can do the following:
371 QUrlOperator op( "ftp://ftp.whatever.com/home/me/filename.dat" );
373 op.put( data );
374 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 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 This will upload the data to
384 ftp://ftp.whatever.com/home/me/filename.dat.
385 See also copy().
387
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 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 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
407 This signal is emitted when remove() has been succesful and the file
408 has been removed.
409 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 See also QNetworkOperation and QNetworkProtocol.
415
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 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 This path of this QUrlOperator must to point to a directory because
432 oldname and newname are handled relative to this directory.
433
435 Sets the name filter of the URL to nameFilter.
436 See also QDir::setNameFilter().
438
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 See also QNetworkOperation and QNetworkProtocol.
446
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 See also copy().
453
455 Stops the current network operation and removes all this QUrlOperator's
456 waiting network operations.
457
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 This function is declared in qnetwork.h.
465
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
477 Generated automatically from the source code.
478
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 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 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).
493Trolltech AS 2 February 2007 QUrlOperator(3qt)