1QHttp(3qt)                                                          QHttp(3qt)
2
3
4

NAME

6       QHttp - Implementation of the HTTP protocol
7

SYNOPSIS

9       #include <qhttp.h>
10
11       Inherits QNetworkProtocol.
12
13   Public Members
14       QHttp ()
15       QHttp ( QObject * parent, const char * name = 0 )
16       QHttp ( const QString & hostname, Q_UINT16 port = 80, QObject * parent
17           = 0, const char * name = 0 )
18       virtual ~QHttp ()
19       enum State { Unconnected, HostLookup, Connecting, Sending, Reading,
20           Connected, Closing }
21       enum Error { NoError, UnknownError, HostNotFound, ConnectionRefused,
22           UnexpectedClose, InvalidResponseHeader, WrongContentLength, Aborted
23           }
24       int setHost ( const QString & hostname, Q_UINT16 port = 80 )
25       int get ( const QString & path, QIODevice * to = 0 )
26       int post ( const QString & path, QIODevice * data, QIODevice * to = 0 )
27       int post ( const QString & path, const QByteArray & data, QIODevice *
28           to = 0 )
29       int head ( const QString & path )
30       int request ( const QHttpRequestHeader & header, QIODevice * data = 0,
31           QIODevice * to = 0 )
32       int request ( const QHttpRequestHeader & header, const QByteArray &
33           data, QIODevice * to = 0 )
34       int closeConnection ()
35       Q_ULONG bytesAvailable () const
36       Q_LONG readBlock ( char * data, Q_ULONG maxlen )
37       QByteArray readAll ()
38       int currentId () const
39       QIODevice * currentSourceDevice () const
40       QIODevice * currentDestinationDevice () const
41       QHttpRequestHeader currentRequest () const
42       bool hasPendingRequests () const
43       void clearPendingRequests ()
44       State state () const
45       Error error () const
46       QString errorString () const
47
48   Public Slots
49       void abort ()
50
51   Signals
52       void stateChanged ( int state )
53       void responseHeaderReceived ( const QHttpResponseHeader & resp )
54       void readyRead ( const QHttpResponseHeader & resp )
55       void dataSendProgress ( int done, int total )
56       void dataReadProgress ( int done, int total )
57       void requestStarted ( int id )
58       void requestFinished ( int id, bool error )
59       void done ( bool error )
60

DESCRIPTION

62       The QHttp class provides an implementation of the HTTP protocol.
63
64       This class provides two different interfaces: one is the
65       QNetworkProtocol interface that allows you to use HTTP through the
66       QUrlOperator abstraction. The other is a direct interface to HTTP that
67       allows you to have more control over the requests and that allows you
68       to access the response header fields.
69
70       Don't mix the two interfaces, since the behavior is not well-defined.
71
72       If you want to use QHttp with the QNetworkProtocol interface, you do
73       not use it directly, but rather through a QUrlOperator, for example:
74
75           QUrlOperator op( "http://www.trolltech.com" );
76           op.get( "index.html" );
77
78       This code will only work if the QHttp class is registered; to register
79       the class, you must call qInitNetworkProtocols() before using a
80       QUrlOperator with HTTP.
81
82       The QNetworkProtocol interface for HTTP only supports the operations
83       operationGet() and operationPut(), i.e. QUrlOperator::get() and
84       QUrlOperator::put(), if you use it with a QUrlOperator.
85
86       The rest of this descrption describes the direct interface to HTTP.
87
88       The class works asynchronously, so there are no blocking functions. If
89       an operation cannot be executed immediately, the function will still
90       return straight away and the operation will be scheduled for later
91       execution. The results of scheduled operations are reported via
92       signals. This approach depends on the event loop being in operation.
93
94       The operations that can be scheduled (they are called "requests" in the
95       rest of the documentation) are the following: setHost(), get(), post(),
96       head() and request().
97
98       All of these requests return a unique identifier that allows you to
99       keep track of the request that is currently executed. When the
100       execution of a request starts, the requestStarted() signal with the
101       identifier is emitted and when the request is finished, the
102       requestFinished() signal is emitted with the identifier and a bool that
103       indicates if the request finished with an error.
104
105       To make an HTTP request you must set up suitable HTTP headers. The
106       following example demonstrates, how to request the main HTML page from
107       the Trolltech home page (i.e. the URL
108       http://www.trolltech.com/index.html):
109
110           QHttpRequestHeader header( "GET", "/index.html" );
111           header.setValue( "Host", "www.trolltech.com" );
112           http->setHost( "www.trolltech.com" );
113           http->request( header );
114
115       For the common HTTP requests GET, POST and HEAD, QHttp provides the
116       convenience functions get(), post() and head(). They already use a
117       reasonable header and if you don't have to set special header fields,
118       they are easier to use. The above example can also be written as:
119
120           http->setHost( "www.trolltech.com" ); // id == 1
121           http->get( "/index.html" );           // id == 2
122
123       For this example the following sequence of signals is emitted (with
124       small variations, depending on network traffic, etc.):
125
126           requestStarted( 1 )
127           requestFinished( 1, FALSE )
128           requestStarted( 2 )
129           stateChanged( Connecting )
130           stateChanged( Sending )
131           dataSendProgress( 77, 77 )
132           stateChanged( Reading )
133           responseHeaderReceived( responseheader )
134           dataReadProgress( 5388, 0 )
135           readyRead( responseheader )
136           dataReadProgress( 18300, 0 )
137           readyRead( responseheader )
138           stateChanged( Connected )
139           requestFinished( 2, FALSE )
140           done( FALSE )
141           stateChanged( Closing )
142           stateChanged( Unconnected )
143
144       The dataSendProgress() and dataReadProgress() signals in the above
145       example are useful if you want to show a progressbar to inform the user
146       about the progress of the download. The second argument is the total
147       size of data. In certain cases it is not possible to know the total
148       amount in advance, in which case the second argument is 0. (If you
149       connect to a QProgressBar a total of 0 results in a busy indicator.)
150
151       When the response header is read, it is reported with the
152       responseHeaderReceived() signal.
153
154       The readyRead() signal tells you that there is data ready to be read.
155       The amount of data can then be queried with the bytesAvailable()
156       function and it can be read with the readBlock() or readAll()
157       functions.
158
159       If an error occurs during the execution of one of the commands in a
160       sequence of commands, all the pending commands (i.e. scheduled, but not
161       yet executed commands) are cleared and no signals are emitted for them.
162
163       For example, if you have the following sequence of reqeusts
164
165           http->setHost( "www.foo.bar" );       // id == 1
166           http->get( "/index.html" );           // id == 2
167           http->post( "register.html", data );  // id == 3
168
169       and the get() request fails because the host lookup fails, then the
170       post() request is never executed and the signals would look like this:
171
172           requestStarted( 1 )
173           requestFinished( 1, FALSE )
174           requestStarted( 2 )
175           stateChanged( HostLookup )
176           requestFinished( 2, TRUE )
177           done( TRUE )
178           stateChanged( Unconnected )
179
180       You can then get details about the error with the error() and
181       errorString() functions. Note that only unexpected behaviour, like
182       network failure is considered as an error. If the server response
183       contains an error status, like a 404 response, this is reported as a
184       normal response case. So you should always check the status code of the
185       response header.
186
187       The functions currentId() and currentRequest() provide more information
188       about the currently executing request.
189
190       The functions hasPendingRequests() and clearPendingRequests() allow you
191       to query and clear the list of pending requests.
192
193       See also Qt Network Documentation, QNetworkProtocol, QUrlOperator,
194       QFtp, and Input/Output and Networking.
195
196   Member Type Documentation

QHttp::Error

198       This enum identifies the error that occurred.
199
200       QHttp::NoError - No error occurred.
201
202       QHttp::HostNotFound - The host name lookup failed.
203
204       QHttp::ConnectionRefused - The server refused the connection.
205
206       QHttp::UnexpectedClose - The server closed the connection unexpectedly.
207
208       QHttp::InvalidResponseHeader - The server sent an invalid response
209       header.
210
211       QHttp::WrongContentLength - The client could not read the content
212       correctly because an error with respect to the content length occurred.
213
214       QHttp::Aborted - The request was aborted with abort().
215
216       QHttp::UnknownError - An error other than those specified above
217       occurred.
218
219       See also error().
220

QHttp::State

222       This enum is used to specify the state the client is in:
223
224       QHttp::Unconnected - There is no connection to the host.
225
226       QHttp::HostLookup - A host name lookup is in progress.
227
228       QHttp::Connecting - An attempt to connect to the host is in progress.
229
230       QHttp::Sending - The client is sending its request to the server.
231
232       QHttp::Reading - The client's request has been sent and the client is
233       reading the server's response.
234
235       QHttp::Connected - The connection to the host is open, but the client
236       is neither sending a request, nor waiting for a response.
237
238       QHttp::Closing - The connection is closing down, but is not yet closed.
239       (The state will be Unconnected when the connection is closed.)
240
241       See also stateChanged() and state().
242

MEMBER FUNCTION DOCUMENTATION

QHttp::QHttp ()

245       Constructs a QHttp object.
246

QHttp::QHttp ( QObject * parent, const char * name = 0 )

248       Constructs a QHttp object. The parameters parent and name are passed on
249       to the QObject constructor.
250

QHttp::QHttp ( const QString & hostname, Q_UINT16 port = 80, QObject * parent

252       = 0, const char * name = 0 )
253       Constructs a QHttp object. Subsequent requests are done by connecting
254       to the server hostname on port port. The parameters parent and name are
255       passed on to the QObject constructor.
256
257       See also setHost().
258

QHttp::~QHttp () [virtual]

260       Destroys the QHttp object. If there is an open connection, it is
261       closed.
262

void QHttp::abort () [slot]

264       Aborts the current request and deletes all scheduled requests.
265
266       For the current request, the requestFinished() signal with the error
267       argument TRUE is emitted. For all other requests that are affected by
268       the abort(), no signals are emitted.
269
270       Since this slot also deletes the scheduled requests, there are no
271       requests left and the done() signal is emitted (with the error argument
272       TRUE).
273
274       See also clearPendingRequests().
275

Q_ULONG QHttp::bytesAvailable () const

277       Returns the number of bytes that can be read from the response content
278       at the moment.
279
280       See also get(), post(), request(), readyRead(), readBlock(), and
281       readAll().
282

void QHttp::clearPendingRequests ()

284       Deletes all pending requests from the list of scheduled requests. This
285       does not affect the request that is being executed. If you want to stop
286       this this as well, use abort().
287
288       See also hasPendingRequests() and abort().
289

int QHttp::closeConnection ()

291       Closes the connection; this is useful if you have a keep-alive
292       connection and want to close it.
293
294       For the requests issued with get(), post() and head(), QHttp sets the
295       connection to be keep-alive. You can also do this using the header you
296       pass to the request() function. QHttp only closes the connection to the
297       HTTP server if the response header requires it to do so.
298
299       The function does not block and returns immediately. The request is
300       scheduled, and its execution is performed asynchronously. The function
301       returns a unique identifier which is passed by requestStarted() and
302       requestFinished().
303
304       When the request is started the requestStarted() signal is emitted.
305       When it is finished the requestFinished() signal is emitted.
306
307       If you want to close the connection immediately, you have to use
308       abort() instead.
309
310       See also stateChanged(), abort(), requestStarted(), requestFinished(),
311       and done().
312

QIODevice * QHttp::currentDestinationDevice () const

314       Returns the QIODevice pointer that is used as to store the data of the
315       HTTP request being executed. If there is no current request or if the
316       request does not store the data to an IO device, this function returns
317       0.
318
319       This function can be used to delete the QIODevice in the slot connected
320       to the requestFinished() signal.
321
322       See also get(), post(), and request().
323

int QHttp::currentId () const

325       Returns the identifier of the HTTP request being executed or 0 if there
326       is no request being executed (i.e. they've all finished).
327
328       See also currentRequest().
329

QHttpRequestHeader QHttp::currentRequest () const

331       Returns the request header of the HTTP request being executed. If the
332       request is one issued by setHost() or closeConnection(), it returns an
333       invalid request header, i.e. QHttpRequestHeader::isValid() returns
334       FALSE.
335
336       See also currentId().
337

QIODevice * QHttp::currentSourceDevice () const

339       Returns the QIODevice pointer that is used as the data source of the
340       HTTP request being executed. If there is no current request or if the
341       request does not use an IO device as the data source, this function
342       returns 0.
343
344       This function can be used to delete the QIODevice in the slot connected
345       to the requestFinished() signal.
346
347       See also currentDestinationDevice(), post(), and request().
348

void QHttp::dataReadProgress ( int done, int total ) [signal]

350       This signal is emitted when this object reads data from a HTTP server
351       to indicate the current progress of the download.
352
353       done is the amount of data that has already arrived and total is the
354       total amount of data. It is possible that the total amount of data that
355       should be transferred cannot be determined, in which case total is
356       0.(If you connect to a QProgressBar, the progress bar shows a busy
357       indicator if the total is 0).
358
359       Warning: done and total are not necessarily the size in bytes, since
360       for large files these values might need to be" scaled" to avoid
361       overflow.
362
363       See also dataSendProgress(), get(), post(), request(), and
364       QProgressBar::progress.
365

void QHttp::dataSendProgress ( int done, int total ) [signal]

367       This signal is emitted when this object sends data to a HTTP server to
368       inform it about the progress of the upload.
369
370       done is the amount of data that has already arrived and total is the
371       total amount of data. It is possible that the total amount of data that
372       should be transferred cannot be determined, in which case total is
373       0.(If you connect to a QProgressBar, the progress bar shows a busy
374       indicator if the total is 0).
375
376       Warning: done and total are not necessarily the size in bytes, since
377       for large files these values might need to be" scaled" to avoid
378       overflow.
379
380       See also dataReadProgress(), post(), request(), and
381       QProgressBar::progress.
382

void QHttp::done ( bool error ) [signal]

384       This signal is emitted when the last pending request has finished; (it
385       is emitted after the last request's requestFinished() signal). error is
386       TRUE if an error occurred during the processing; otherwise error is
387       FALSE.
388
389       See also requestFinished(), error(), and errorString().
390

Error QHttp::error () const

392       Returns the last error that occurred. This is useful to find out what
393       happened when receiving a requestFinished() or a done() signal with the
394       error argument TRUE.
395
396       If you start a new request, the error status is reset to NoError.
397

QString QHttp::errorString () const

399       Returns a human-readable description of the last error that occurred.
400       This is useful to present a error message to the user when receiving a
401       requestFinished() or a done() signal with the error argument TRUE.
402

int QHttp::get ( const QString & path, QIODevice * to = 0 )

404       Sends a get request for path to the server set by setHost() or as
405       specified in the constructor.
406
407       path must be an absolute path like /index.html or an absolute URI like
408       http://www.trolltech.com/index.html.
409
410       If the IO device to is 0 the readyRead() signal is emitted every time
411       new content data is available to read.
412
413       If the IO device to is not 0, the content data of the response is
414       written directly to the device. Make sure that the to pointer is valid
415       for the duration of the operation (it is safe to delete it when the
416       requestFinished() signal is emitted).
417
418       The function does not block and returns immediately. The request is
419       scheduled, and its execution is performed asynchronously. The function
420       returns a unique identifier which is passed by requestStarted() and
421       requestFinished().
422
423       When the request is started the requestStarted() signal is emitted.
424       When it is finished the requestFinished() signal is emitted.
425
426       See also setHost(), post(), head(), request(), requestStarted(),
427       requestFinished(), and done().
428

bool QHttp::hasPendingRequests () const

430       Returns TRUE if there are any requests scheduled that have not yet been
431       executed; otherwise returns FALSE.
432
433       The request that is being executed is not considered as a scheduled
434       request.
435
436       See also clearPendingRequests(), currentId(), and currentRequest().
437

int QHttp::head ( const QString & path )

439       Sends a header request for path to the server set by setHost() or as
440       specified in the constructor.
441
442       path must be an absolute path like /index.html or an absolute URI like
443       http://www.trolltech.com/index.html.
444
445       The function does not block and returns immediately. The request is
446       scheduled, and its execution is performed asynchronously. The function
447       returns a unique identifier which is passed by requestStarted() and
448       requestFinished().
449
450       When the request is started the requestStarted() signal is emitted.
451       When it is finished the requestFinished() signal is emitted.
452
453       See also setHost(), get(), post(), request(), requestStarted(),
454       requestFinished(), and done().
455

int QHttp::post ( const QString & path, QIODevice * data, QIODevice * to = 0 )

457
458       Sends a post request for path to the server set by setHost() or as
459       specified in the constructor.
460
461       path must be an absolute path like /index.html or an absolute URI like
462       http://www.trolltech.com/index.html.
463
464       The incoming data comes via the data IO device.
465
466       If the IO device to is 0 the readyRead() signal is emitted every time
467       new content data is available to read.
468
469       If the IO device to is not 0, the content data of the response is
470       written directly to the device. Make sure that the to pointer is valid
471       for the duration of the operation (it is safe to delete it when the
472       requestFinished() signal is emitted).
473
474       The function does not block and returns immediately. The request is
475       scheduled, and its execution is performed asynchronously. The function
476       returns a unique identifier which is passed by requestStarted() and
477       requestFinished().
478
479       When the request is started the requestStarted() signal is emitted.
480       When it is finished the requestFinished() signal is emitted.
481
482       See also setHost(), get(), head(), request(), requestStarted(),
483       requestFinished(), and done().
484

int QHttp::post ( const QString & path, const QByteArray & data, QIODevice *

486       to = 0 )
487       This is an overloaded member function, provided for convenience. It
488       behaves essentially like the above function.
489
490       data is used as the content data of the HTTP request.
491

QByteArray QHttp::readAll ()

493       Reads all the bytes from the response content and returns them.
494
495       See also get(), post(), request(), readyRead(), bytesAvailable(), and
496       readBlock().
497

Q_LONG QHttp::readBlock ( char * data, Q_ULONG maxlen )

499       Reads maxlen bytes from the response content into data and returns the
500       number of bytes read. Returns -1 if an error occurred.
501
502       See also get(), post(), request(), readyRead(), bytesAvailable(), and
503       readAll().
504

void QHttp::readyRead ( const QHttpResponseHeader & resp ) [signal]

506       This signal is emitted when there is new response data to read.
507
508       If you specified a device in the request where the data should be
509       written to, then this signal is not emitted; instead the data is
510       written directly to the device.
511
512       The response header is passed in resp.
513
514       You can read the data with the readAll() or readBlock() functions
515
516       This signal is useful if you want to process the data in chunks as soon
517       as it becomes available. If you are only interested in the complete
518       data, just connect to the requestFinished() signal and read the data
519       then instead.
520
521       See also get(), post(), request(), readAll(), readBlock(), and
522       bytesAvailable().
523

int QHttp::request ( const QHttpRequestHeader & header, QIODevice * data = 0,

525       QIODevice * to = 0 )
526       Sends a request to the server set by setHost() or as specified in the
527       constructor. Uses the header as the HTTP request header. You are
528       responsible for setting up a header that is appropriate for your
529       request.
530
531       The incoming data comes via the data IO device.
532
533       If the IO device to is 0 the readyRead() signal is emitted every time
534       new content data is available to read.
535
536       If the IO device to is not 0, the content data of the response is
537       written directly to the device. Make sure that the to pointer is valid
538       for the duration of the operation (it is safe to delete it when the
539       requestFinished() signal is emitted).
540
541       The function does not block and returns immediately. The request is
542       scheduled, and its execution is performed asynchronously. The function
543       returns a unique identifier which is passed by requestStarted() and
544       requestFinished().
545
546       When the request is started the requestStarted() signal is emitted.
547       When it is finished the requestFinished() signal is emitted.
548
549       See also setHost(), get(), post(), head(), requestStarted(),
550       requestFinished(), and done().
551

int QHttp::request ( const QHttpRequestHeader & header, const QByteArray &

553       data, QIODevice * to = 0 )
554       This is an overloaded member function, provided for convenience. It
555       behaves essentially like the above function.
556
557       data is used as the content data of the HTTP request.
558

void QHttp::requestFinished ( int id, bool error ) [signal]

560       This signal is emitted when processing the request identified by id has
561       finished. error is TRUE if an error occurred during the processing;
562       otherwise error is FALSE.
563
564       See also requestStarted(), done(), error(), and errorString().
565

void QHttp::requestStarted ( int id ) [signal]

567       This signal is emitted when processing the request identified by id
568       starts.
569
570       See also requestFinished() and done().
571

void QHttp::responseHeaderReceived ( const QHttpResponseHeader & resp )

573       [signal]
574       This signal is emitted when the HTTP header of a server response is
575       available. The header is passed in resp.
576
577       See also get(), post(), head(), request(), and readyRead().
578

int QHttp::setHost ( const QString & hostname, Q_UINT16 port = 80 )

580       Sets the HTTP server that is used for requests to hostname on port
581       port.
582
583       The function does not block and returns immediately. The request is
584       scheduled, and its execution is performed asynchronously. The function
585       returns a unique identifier which is passed by requestStarted() and
586       requestFinished().
587
588       When the request is started the requestStarted() signal is emitted.
589       When it is finished the requestFinished() signal is emitted.
590
591       See also get(), post(), head(), request(), requestStarted(),
592       requestFinished(), and done().
593

State QHttp::state () const

595       Returns the current state of the object. When the state changes, the
596       stateChanged() signal is emitted.
597
598       See also State and stateChanged().
599

void QHttp::stateChanged ( int state ) [signal]

601       This signal is emitted when the state of the QHttp object changes. The
602       argument state is the new state of the connection; it is one of the
603       State values.
604
605       This usually happens when a request is started, but it can also happen
606       when the server closes the connection or when a call to
607       closeConnection() succeeded.
608
609       See also get(), post(), head(), request(), closeConnection(), state(),
610       and State.
611
612

SEE ALSO

614       http://doc.trolltech.com/qhttp.html
615       http://www.trolltech.com/faq/tech.html
616
618       Copyright 1992-2007 Trolltech ASA, http://www.trolltech.com.  See the
619       license file included in the distribution for a complete license
620       statement.
621

AUTHOR

623       Generated automatically from the source code.
624

BUGS

626       If you find a bug in Qt, please report it as described in
627       http://doc.trolltech.com/bughowto.html.  Good bug reports help us to
628       help you. Thank you.
629
630       The definitive Qt documentation is provided in HTML format; it is
631       located at $QTDIR/doc/html and can be read using Qt Assistant or with a
632       web browser. This man page is provided as a convenience for those users
633       who prefer man pages, although this format is not officially supported
634       by Trolltech.
635
636       If you find errors in this manual page, please report them to qt-
637       bugs@trolltech.com.  Please include the name of the manual page
638       (qhttp.3qt) and the Qt version (3.3.8).
639
640
641
642Trolltech AS                    2 February 2007                     QHttp(3qt)
Impressum