1QNetworkProtocol(3qt)                                    QNetworkProtocol(3qt)
2
3
4

NAME

6       QNetworkProtocol - Common API for network protocols
7

SYNOPSIS

9       #include <qnetworkprotocol.h>
10
11       Inherits QObject.
12
13       Inherited by QFtp, QHttp, and QLocalFs.
14
15   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
37   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
51   Static Public Members
52       void registerNetworkProtocol ( const QString & protocol,
53           QNetworkProtocolFactoryBase * protocolFactory )
54       QNetworkProtocol * getNetworkProtocol ( const QString & protocol )
55       bool hasOnlyLocalFileSystem ()
56
57   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

DESCRIPTION

67       The QNetworkProtocol class provides a common API for network protocols.
68
69       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
73       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
80       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
85       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
89       See also Input/Output and Networking.
90
91   Member Type Documentation

QNetworkProtocol::ConnectionState

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
97       QNetworkProtocol::ConHostFound - Host has been found.
98
99       QNetworkProtocol::ConConnected - Connection to the host has been
100       established.
101
102       QNetworkProtocol::ConClosed - Connection has been closed.
103

QNetworkProtocol::Error

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
109       QNetworkProtocol::NoError - No error occurred.
110
111       QNetworkProtocol::ErrValid - The URL you are operating on is not valid.
112
113       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
118       QNetworkProtocol::ErrUnsupported - The operation is not supported by
119       the protocol.
120
121       QNetworkProtocol::ErrParse - The URL could not be parsed correctly.
122
123       QNetworkProtocol::ErrLoginIncorrect - You needed to login but the
124       username or password is wrong.
125
126       QNetworkProtocol::ErrHostNotFound - The specified host (in the URL)
127       couldn't be found.
128
129       QNetworkProtocol::ErrListChildren - An error occurred while listing the
130       children (files).
131
132       QNetworkProtocol::ErrMkDir - An error occurred when creating a
133       directory.
134
135       QNetworkProtocol::ErrRemove - An error occurred when removing a child
136       (file).
137
138       QNetworkProtocol::ErrRename - An error occurred when renaming a child
139       (file).
140
141       QNetworkProtocol::ErrGet - An error occurred while getting (retrieving)
142       data.
143
144       QNetworkProtocol::ErrPut - An error occurred while putting (uploading)
145       data.
146
147       QNetworkProtocol::ErrFileNotExisting - A file which is needed by the
148       operation doesn't exist.
149
150       QNetworkProtocol::ErrPermissionDenied - Permission for doing the
151       operation has been denied.
152
153       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

QNetworkProtocol::Operation

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
163       QNetworkProtocol::OpListChildren - List the children of a URL, e.g. of
164       a directory.
165
166       QNetworkProtocol::OpMkDir - Create a directory.
167
168       QNetworkProtocol::OpRemove - Remove a child (e.g. a file).
169
170       QNetworkProtocol::OpRename - Rename a child (e.g. a file).
171
172       QNetworkProtocol::OpGet - Get data from a location.
173
174       QNetworkProtocol::OpPut - Put data to a location.
175

QNetworkProtocol::State

177       This enum contains the state that a QNetworkOperation can have.
178
179       QNetworkProtocol::StWaiting - The operation is in the
180       QNetworkProtocol's queue waiting to be prcessed.
181
182       QNetworkProtocol::StInProgress - The operation is being processed.
183
184       QNetworkProtocol::StDone - The operation has been processed
185       succesfully.
186
187       QNetworkProtocol::StFailed - The operation has been processed but an
188       error occurred.
189
190       QNetworkProtocol::StStopped - The operation has been processed but has
191       been stopped before it finished, and is waiting to be processed.
192

MEMBER FUNCTION DOCUMENTATION

QNetworkProtocol::QNetworkProtocol ()

195       Constructor of the network protocol base class. Does some
196       initialization and connecting of signals and slots.
197

QNetworkProtocol::~QNetworkProtocol () [virtual]

199       Destructor.
200

void QNetworkProtocol::addOperation ( QNetworkOperation * op ) [virtual]

202       Adds the operation op to the operation queue. The operation will be
203       processed as soon as possible. This method returns immediately.
204

bool QNetworkProtocol::autoDelete () const

206       Returns TRUE if auto-deleting is enabled; otherwise returns FALSE.
207
208       See also QNetworkProtocol::setAutoDelete().
209

bool QNetworkProtocol::checkConnection ( QNetworkOperation * op ) [virtual

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
218       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
223       op is the operation that needs an open connection.
224
225       Example: network/networkprotocol/nntp.cpp.
226

void QNetworkProtocol::clearOperationQueue () [virtual]

228       Clears the operation queue.
229

void QNetworkProtocol::connectionStateChanged ( int state, const QString &

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

void QNetworkProtocol::createdDirectory ( const QUrlInfo & i,

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
245       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

void QNetworkProtocol::data ( const QByteArray & data, QNetworkOperation * op

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
258       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

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

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
271       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

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

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
283       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

QNetworkProtocol * QNetworkProtocol::getNetworkProtocol ( const QString &

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
292           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
298       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
302       See also QUrlOperator.
303

bool QNetworkProtocol::hasOnlyLocalFileSystem () [static]

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

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

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
317       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

void QNetworkProtocol::newChild ( const QUrlInfo & i, QNetworkOperation * op )

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
330       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

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

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
342       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
346       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

void QNetworkProtocol::operationGet ( QNetworkOperation * op ) [virtual

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
358       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
365       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
369       Example: network/networkprotocol/nntp.cpp.
370

QNetworkOperation * QNetworkProtocol::operationInProgress () const

372       Returns the operation, which is being processed, or 0 of no operation
373       is being processed at the moment.
374

void QNetworkProtocol::operationListChildren ( QNetworkOperation * op )

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
381       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
388       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
392       Example: network/networkprotocol/nntp.cpp.
393

void QNetworkProtocol::operationMkDir ( QNetworkOperation * op ) [virtual

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
400       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
407       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

void QNetworkProtocol::operationPut ( QNetworkOperation * op ) [virtual

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
417       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
424       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

void QNetworkProtocol::operationRemove ( QNetworkOperation * op ) [virtual

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
434       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
441       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

void QNetworkProtocol::operationRename ( QNetworkOperation * op ) [virtual

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
451       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
458       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

void QNetworkProtocol::registerNetworkProtocol ( const QString & protocol,

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
468           QNetworkProtocol::registerNetworkProtocol( "nntp", new QNetworkProtocolFactory<Nntp> );
469       after which your implementation is registered for future nntp
470       operations.
471
472       The name of the protocol is given in protocol and a pointer to the
473       protocol factory is given in protocolFactory.
474

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

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
482       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

void QNetworkProtocol::setAutoDelete ( bool b, int i = 10000 ) [virtual]

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
494       If you switch on auto-delete, the QNetworkProtocol also deletes its
495       QUrlOperator.
496

void QNetworkProtocol::setUrl ( QUrlOperator * u ) [virtual]

498       Sets the QUrlOperator, on which the protocol works, to u.
499
500       See also QUrlOperator.
501

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

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
508       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

void QNetworkProtocol::stop () [virtual]

513       Stops the current operation that is being processed and clears all
514       waiting operations.
515

int QNetworkProtocol::supportedOperations () const [virtual]

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
522       Example: network/networkprotocol/nntp.cpp.
523

QUrlOperator * QNetworkProtocol::url () const

525       Returns the QUrlOperator on which the protocol works.
526
527

SEE ALSO

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

AUTHOR

538       Generated automatically from the source code.
539

BUGS

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
545       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
551       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).
554
555
556
557Trolltech AS                    2 February 2007          QNetworkProtocol(3qt)
Impressum