1QNetworkProtocol(3qt) QNetworkProtocol(3qt)
2
6 QNetworkProtocol - Common API for network protocols
7
9 #include <qnetworkprotocol.h>
10 Inherits QObject.
12 Inherited by QFtp, QHttp, and QLocalFs.
14 Public Members
16 enum State { StWaiting = 0, StInProgress, StDone, StFailed, StStopped }
17 enum Operation { OpListChildren = 1, OpMkDir = 2, OpMkdir = OpMkDir,
18 OpRemove = 4, OpRename = 8, OpGet = 32, OpPut = 64 }
19 enum ConnectionState { ConHostFound, ConConnected, ConClosed }
20 enum Error { NoError = 0, ErrValid, ErrUnknownProtocol, ErrUnsupported,
21 ErrParse, ErrLoginIncorrect, ErrHostNotFound, ErrListChildren,
22 ErrListChlidren = ErrListChildren, ErrMkDir, ErrMkdir = ErrMkDir,
23 ErrRemove, ErrRename, ErrGet, ErrPut, ErrFileNotExisting,
24 ErrPermissionDenied }
25 QNetworkProtocol ()
26 virtual ~QNetworkProtocol ()
27 virtual void setUrl ( QUrlOperator * u )
28 virtual void setAutoDelete ( bool b, int i = 10000 )
29 bool autoDelete () const
30 virtual int supportedOperations () const
31 virtual void addOperation ( QNetworkOperation * op )
32 QUrlOperator * url () const
33 QNetworkOperation * operationInProgress () const
34 virtual void clearOperationQueue ()
35 virtual void stop ()
36 Signals
38 void data ( const QByteArray & data, QNetworkOperation * op )
39 void connectionStateChanged ( int state, const QString & data )
40 void finished ( QNetworkOperation * op )
41 void start ( QNetworkOperation * op )
42 void newChildren ( const QValueList<QUrlInfo> & i, QNetworkOperation *
43 op )
44 void newChild ( const QUrlInfo & i, QNetworkOperation * op )
45 void createdDirectory ( const QUrlInfo & i, QNetworkOperation * op )
46 void removed ( QNetworkOperation * op )
47 void itemChanged ( QNetworkOperation * op )
48 void dataTransferProgress ( int bytesDone, int bytesTotal,
49 QNetworkOperation * op )
50 Static Public Members
52 void registerNetworkProtocol ( const QString & protocol,
53 QNetworkProtocolFactoryBase * protocolFactory )
54 QNetworkProtocol * getNetworkProtocol ( const QString & protocol )
55 bool hasOnlyLocalFileSystem ()
56 Protected Members
58 virtual void operationListChildren ( QNetworkOperation * op )
59 virtual void operationMkDir ( QNetworkOperation * op )
60 virtual void operationRemove ( QNetworkOperation * op )
61 virtual void operationRename ( QNetworkOperation * op )
62 virtual void operationGet ( QNetworkOperation * op )
63 virtual void operationPut ( QNetworkOperation * op )
64 virtual bool checkConnection ( QNetworkOperation * op )
65
67 The QNetworkProtocol class provides a common API for network protocols.
68 This is a base class which should be used for network protocols
70 implementations that can then be used in Qt (e.g. in the file dialog)
71 together with the QUrlOperator.
72 The easiest way to implement a new network protocol is to reimplement
74 the operation*() methods, e.g. operationGet(), etc. Only the supported
75 operations should be reimplemented. To specify which operations are
76 supported, also reimplement supportedOperations() and return an int
77 that is OR'd together using the supported operations from the
78 QNetworkProtocol::Operation enum.
79 When you implement a network protocol this way, it is important to emit
81 the correct signals. Also, always emit the finished() signal when an
82 operation is done (on success and on failure). Qt relies on correctly
83 emitted finished() signals.
84 For a detailed description of the Qt Network Architecture and how to
86 implement and use network protocols in Qt, see the Qt Network
87 Documentation.
88 See also Input/Output and Networking.
90 Member Type Documentation
93 When the connection state of a network protocol changes it emits the
94 signal connectionStateChanged(). The first argument is one of the
95 following values:
96 QNetworkProtocol::ConHostFound - Host has been found.
98 QNetworkProtocol::ConConnected - Connection to the host has been
100 established.
101 QNetworkProtocol::ConClosed - Connection has been closed.
103
105 When an operation fails (finishes unsuccessfully), the
106 QNetworkOperation of the operation returns an error code which has one
107 of the following values:
108 QNetworkProtocol::NoError - No error occurred.
110 QNetworkProtocol::ErrValid - The URL you are operating on is not valid.
112 QNetworkProtocol::ErrUnknownProtocol - There is no protocol
114 implementation available for the protocol of the URL you are operating
115 on (e.g. if the protocol is http and no http implementation has been
116 registered).
117 QNetworkProtocol::ErrUnsupported - The operation is not supported by
119 the protocol.
120 QNetworkProtocol::ErrParse - The URL could not be parsed correctly.
122 QNetworkProtocol::ErrLoginIncorrect - You needed to login but the
124 username or password is wrong.
125 QNetworkProtocol::ErrHostNotFound - The specified host (in the URL)
127 couldn't be found.
128 QNetworkProtocol::ErrListChildren - An error occurred while listing the
130 children (files).
131 QNetworkProtocol::ErrMkDir - An error occurred when creating a
133 directory.
134 QNetworkProtocol::ErrRemove - An error occurred when removing a child
136 (file).
137 QNetworkProtocol::ErrRename - An error occurred when renaming a child
139 (file).
140 QNetworkProtocol::ErrGet - An error occurred while getting (retrieving)
142 data.
143 QNetworkProtocol::ErrPut - An error occurred while putting (uploading)
145 data.
146 QNetworkProtocol::ErrFileNotExisting - A file which is needed by the
148 operation doesn't exist.
149 QNetworkProtocol::ErrPermissionDenied - Permission for doing the
151 operation has been denied.
152 You should also use these error codes when implementing custom network
154 protocols. If this is not possible, you can define your own error codes
155 by using integer values that don't conflict with any of these values.
156
158 This enum lists the possible operations that a network protocol can
159 support. supportedOperations() returns an int of these that is OR'd
160 together. Also, the type() of a QNetworkOperation is always one of
161 these values.
162 QNetworkProtocol::OpListChildren - List the children of a URL, e.g. of
164 a directory.
165 QNetworkProtocol::OpMkDir - Create a directory.
167 QNetworkProtocol::OpRemove - Remove a child (e.g. a file).
169 QNetworkProtocol::OpRename - Rename a child (e.g. a file).
171 QNetworkProtocol::OpGet - Get data from a location.
173 QNetworkProtocol::OpPut - Put data to a location.
175
177 This enum contains the state that a QNetworkOperation can have.
178 QNetworkProtocol::StWaiting - The operation is in the
180 QNetworkProtocol's queue waiting to be prcessed.
181 QNetworkProtocol::StInProgress - The operation is being processed.
183 QNetworkProtocol::StDone - The operation has been processed
185 succesfully.
186 QNetworkProtocol::StFailed - The operation has been processed but an
188 error occurred.
189 QNetworkProtocol::StStopped - The operation has been processed but has
191 been stopped before it finished, and is waiting to be processed.
192
195 Constructor of the network protocol base class. Does some
196 initialization and connecting of signals and slots.
197
199 Destructor.
200
202 Adds the operation op to the operation queue. The operation will be
203 processed as soon as possible. This method returns immediately.
204
206 Returns TRUE if auto-deleting is enabled; otherwise returns FALSE.
207 See also QNetworkProtocol::setAutoDelete().
209
211 protected]
212 For processing operations the network protocol base class calls this
213 method quite often. This should be reimplemented by new network
214 protocols. It should return TRUE if the connection is OK (open);
215 otherwise it should return FALSE. If the connection is not open the
216 protocol should open it.
217 If the connection can't be opened (e.g. because you already tried but
219 the host couldn't be found), set the state of op to
220 QNetworkProtocol::StFailed and emit the finished() signal with this
221 QNetworkOperation as argument.
222 op is the operation that needs an open connection.
224 Example: network/networkprotocol/nntp.cpp.
226
228 Clears the operation queue.
229
231 data ) [signal]
232 This signal is emitted whenever the state of the connection of the
233 network protocol is changed. state describes the new state, which is
234 one of, ConHostFound, ConConnected or ConClosed. data is a message
235 text.
236
238 QNetworkOperation * op ) [signal]
239 This signal is emitted when mkdir() has been succesful and the
240 directory has been created. i holds the information about the new
241 directory. op is the pointer to the operation object which contains all
242 the information about the operation, including the state, etc. Using
243 op->arg( 0 ), you can get the file name of the new directory.
244 When a protocol emits this signal, QNetworkProtocol is smart enough to
246 let the QUrlOperator, which is used by the network protocol, emit its
247 corresponding signal.
248
250 ) [signal]
251 This signal is emitted when new data has been received after calling
252 get() or put(). op holds the name of the file from which data is
253 retrieved or uploaded in its first argument, and the (raw) data in its
254 second argument. You can get them with op->arg( 0 ) and op->rawArg( 1
255 ). op is the pointer to the operation object, which contains all the
256 information about the operation, including the state, etc.
257 When a protocol emits this signal, QNetworkProtocol is smart enough to
259 let the QUrlOperator (which is used by the network protocol) emit its
260 corresponding signal.
261
263 QNetworkOperation * op ) [signal]
264 This signal is emitted during the transfer of data (using put() or
265 get()). bytesDone is how many bytes of bytesTotal have been
266 transferred. bytesTotal may be -1, which means that the total number of
267 bytes is not known. op is the pointer to the operation object which
268 contains all the information about the operation, including the state,
269 etc.
270 When a protocol emits this signal, QNetworkProtocol is smart enough to
272 let the QUrlOperator, which is used by the network protocol, emit its
273 corresponding signal.
274
276 This signal is emitted when an operation finishes. This signal is
277 always emitted, for both success and failure. op is the pointer to the
278 operation object which contains all the information about the
279 operation, including the state, etc. Check the state and error code of
280 the operation object to determine whether or not the operation was
281 successful.
282 When a protocol emits this signal, QNetworkProtocol is smart enough to
284 let the QUrlOperator, which is used by the network protocol, emit its
285 corresponding signal.
286
288 protocol ) [static]
289 Static method to get a new instance of the network protocol protocol.
290 For example, if you need to do some FTP operations, do the following:
291 QFtp *ftp = QNetworkProtocol::getNetworkProtocol( "ftp" );
293 This returns a pointer to a new instance of an ftp implementation or
294 null if no protocol for ftp was registered. The ownership of the
295 pointer is transferred to you, so you must delete it if you don't need
296 it anymore.
297 Normally you should not work directly with network protocols, so you
299 will not need to call this method yourself. Instead, use QUrlOperator,
300 which makes working with network protocols much more convenient.
301 See also QUrlOperator.
303
305 Returns TRUE if the only protocol registered is for working on the
306 local filesystem; returns FALSE if other network protocols are also
307 registered.
308
310 This signal is emitted whenever a file which is a child of this URL has
311 been changed, e.g. by successfully calling rename(). op holds the
312 original and the new file names in the first and second arguments,
313 accessible with op->arg( 0 ) and op->arg( 1 ) respectively. op is the
314 pointer to the operation object which contains all the information
315 about the operation, including the state, etc.
316 When a protocol emits this signal, QNetworkProtocol is smart enough to
318 let the QUrlOperator, which is used by the network protocol, emit its
319 corresponding signal.
320
322 [signal]
323 This signal is emitted if a new child (file) has been read.
324 QNetworkProtocol automatically connects it to a slot which creates a
325 list of QUrlInfo objects (with just one QUrlInfo i) and emits the
326 newChildren() signal with this list. op is the pointer to the operation
327 object which contains all the information about the operation that has
328 finished, including the state, etc.
329 This is just a convenience signal useful for implementing your own
331 network protocol. In all other cases connect to the newChildren()
332 signal with its list of QUrlInfo objects.
333
335 QNetworkOperation * op ) [signal]
336 This signal is emitted after listChildren() was called and new children
337 (files) have been read from the list of files. i holds the information
338 about the new children. op is the pointer to the operation object which
339 contains all the information about the operation, including the state,
340 etc.
341 When a protocol emits this signal, QNetworkProtocol is smart enough to
343 let the QUrlOperator, which is used by the network protocol, emit its
344 corresponding signal.
345 When implementing your own network protocol and reading children, you
347 usually don't read one child at once, but rather a list of them. That's
348 why this signal takes a list of QUrlInfo objects. If you prefer to read
349 just one child at a time you can use the convenience signal newChild(),
350 which takes a single QUrlInfo object.
351
353 protected]
354 When implementing a new network protocol, this method should be
355 reimplemented if the protocol supports getting data; this method should
356 then process the QNetworkOperation.
357 When you reimplement this method it's very important that you emit the
359 correct signals at the correct time (especially the finished() signal
360 after processing an operation). Take a look at the Qt Network
361 Documentation which describes in detail how to reimplement this method.
362 You may also want to look at the example implementation in
363 examples/network/networkprotocol/nntp.cpp.
364 op is the pointer to the operation object which contains all the
366 information on the operation that has finished, including the state,
367 etc.
368 Example: network/networkprotocol/nntp.cpp.
370
372 Returns the operation, which is being processed, or 0 of no operation
373 is being processed at the moment.
374
376 [virtual protected]
377 When implementing a new network protocol, this method should be
378 reimplemented if the protocol supports listing children (files); this
379 method should then process this QNetworkOperation.
380 When you reimplement this method it's very important that you emit the
382 correct signals at the correct time (especially the finished() signal
383 after processing an operation). Take a look at the Qt Network
384 Documentation which describes in detail how to reimplement this method.
385 You may also want to look at the example implementation in
386 examples/network/networkprotocol/nntp.cpp.
387 op is the pointer to the operation object which contains all the
389 information on the operation that has finished, including the state,
390 etc.
391 Example: network/networkprotocol/nntp.cpp.
393
395 protected]
396 When implementing a new network protocol, this method should be
397 reimplemented if the protocol supports making directories; this method
398 should then process this QNetworkOperation.
399 When you reimplement this method it's very important that you emit the
401 correct signals at the correct time (especially the finished() signal
402 after processing an operation). Take a look at the Qt Network
403 Documentation which describes in detail how to reimplement this method.
404 You may also want to look at the example implementation in
405 examples/network/networkprotocol/nntp.cpp.
406 op is the pointer to the operation object which contains all the
408 information on the operation that has finished, including the state,
409 etc.
410
412 protected]
413 When implementing a new network protocol, this method should be
414 reimplemented if the protocol supports putting (uploading) data; this
415 method should then process the QNetworkOperation.
416 When you reimplement this method it's very important that you emit the
418 correct signals at the correct time (especially the finished() signal
419 after processing an operation). Take a look at the Qt Network
420 Documentation which describes in detail how to reimplement this method.
421 You may also want to look at the example implementation in
422 examples/network/networkprotocol/nntp.cpp.
423 op is the pointer to the operation object which contains all the
425 information on the operation that has finished, including the state,
426 etc.
427
429 protected]
430 When implementing a new network protocol, this method should be
431 reimplemented if the protocol supports removing children (files); this
432 method should then process this QNetworkOperation.
433 When you reimplement this method it's very important that you emit the
435 correct signals at the correct time (especially the finished() signal
436 after processing an operation). Take a look at the Qt Network
437 Documentation which is describes in detail how to reimplement this
438 method. You may also want to look at the example implementation in
439 examples/network/networkprotocol/nntp.cpp.
440 op is the pointer to the operation object which contains all the
442 information on the operation that has finished, including the state,
443 etc.
444
446 protected]
447 When implementing a new newtork protocol, this method should be
448 reimplemented if the protocol supports renaming children (files); this
449 method should then process this QNetworkOperation.
450 When you reimplement this method it's very important that you emit the
452 correct signals at the correct time (especially the finished() signal
453 after processing an operation). Take a look at the Qt Network
454 Documentation which describes in detail how to reimplement this method.
455 You may also want to look at the example implementation in
456 examples/network/networkprotocol/nntp.cpp.
457 op is the pointer to the operation object which contains all the
459 information on the operation that has finished, including the state,
460 etc.
461
463 QNetworkProtocolFactoryBase * protocolFactory ) [static]
464 Static method to register a network protocol for Qt. For example, if
465 you have an implementation of NNTP (called Nntp) which is derived from
466 QNetworkProtocol, call:
467 QNetworkProtocol::registerNetworkProtocol( "nntp", new QNetworkProtocolFactory<Nntp> );
469 after which your implementation is registered for future nntp
470 operations.
471 The name of the protocol is given in protocol and a pointer to the
473 protocol factory is given in protocolFactory.
474
476 This signal is emitted when remove() has been succesful and the file
477 has been removed. op holds the file name of the removed file in the
478 first argument, accessible with op->arg( 0 ). op is the pointer to the
479 operation object which contains all the information about the
480 operation, including the state, etc.
481 When a protocol emits this signal, QNetworkProtocol is smart enough to
483 let the QUrlOperator, which is used by the network protocol, emit its
484 corresponding signal.
485
487 Because it's sometimes hard to take care of removing network protocol
488 instances, QNetworkProtocol provides an auto-delete mechanism. If you
489 set b to TRUE, the network protocol instance is removed after it has
490 been inactive for i milliseconds (i.e. i milliseconds after the last
491 operation has been processed). If you set b to FALSE the auto-delete
492 mechanism is switched off.
493 If you switch on auto-delete, the QNetworkProtocol also deletes its
495 QUrlOperator.
496
498 Sets the QUrlOperator, on which the protocol works, to u.
499 See also QUrlOperator.
501
503 Some operations (such as listChildren()) emit this signal when they
504 start processing the operation. op is the pointer to the operation
505 object which contains all the information about the operation,
506 including the state, etc.
507 When a protocol emits this signal, QNetworkProtocol is smart enough to
509 let the QUrlOperator, which is used by the network protocol, emit its
510 corresponding signal.
511
513 Stops the current operation that is being processed and clears all
514 waiting operations.
515
517 Returns an int that is OR'd together using the enum values of
518 QNetworkProtocol::Operation, which describes which operations are
519 supported by the network protocol. Should be reimplemented by new
520 network protocols.
521 Example: network/networkprotocol/nntp.cpp.
523
525 Returns the QUrlOperator on which the protocol works.
526
529 http://doc.trolltech.com/qnetworkprotocol.html
530 http://www.trolltech.com/faq/tech.html
531
533 Copyright 1992-2007 Trolltech ASA, http://www.trolltech.com. See the
534 license file included in the distribution for a complete license
535 statement.
536
538 Generated automatically from the source code.
539
541 If you find a bug in Qt, please report it as described in
542 http://doc.trolltech.com/bughowto.html. Good bug reports help us to
543 help you. Thank you.
544 The definitive Qt documentation is provided in HTML format; it is
546 located at $QTDIR/doc/html and can be read using Qt Assistant or with a
547 web browser. This man page is provided as a convenience for those users
548 who prefer man pages, although this format is not officially supported
549 by Trolltech.
550 If you find errors in this manual page, please report them to qt-
552 bugs@trolltech.com. Please include the name of the manual page
553 (qnetworkprotocol.3qt) and the Qt version (3.3.8).
554Trolltech AS 2 February 2007 QNetworkProtocol(3qt)