1QHttp(3qt) QHttp(3qt)
2
6 QHttp - Implementation of the HTTP protocol
7
9 #include <qhttp.h>
10 Inherits QNetworkProtocol.
12 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 Public Slots
49 void abort ()
50 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
62 The QHttp class provides an implementation of the HTTP protocol.
63 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 Don't mix the two interfaces, since the behavior is not well-defined.
71 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 QUrlOperator op( "http://www.trolltech.com" );
76 op.get( "index.html" );
77 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 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 The rest of this descrption describes the direct interface to HTTP.
87 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 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 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 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 QHttpRequestHeader header( "GET", "/index.html" );
111 header.setValue( "Host", "www.trolltech.com" );
112 http->setHost( "www.trolltech.com" );
113 http->request( header );
114 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 http->setHost( "www.trolltech.com" ); // id == 1
121 http->get( "/index.html" ); // id == 2
122 For this example the following sequence of signals is emitted (with
124 small variations, depending on network traffic, etc.):
125 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 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 When the response header is read, it is reported with the
152 responseHeaderReceived() signal.
153 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 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 For example, if you have the following sequence of reqeusts
164 http->setHost( "www.foo.bar" ); // id == 1
166 http->get( "/index.html" ); // id == 2
167 http->post( "register.html", data ); // id == 3
168 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 requestStarted( 1 )
173 requestFinished( 1, FALSE )
174 requestStarted( 2 )
175 stateChanged( HostLookup )
176 requestFinished( 2, TRUE )
177 done( TRUE )
178 stateChanged( Unconnected )
179 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 The functions currentId() and currentRequest() provide more information
188 about the currently executing request.
189 The functions hasPendingRequests() and clearPendingRequests() allow you
191 to query and clear the list of pending requests.
192 See also Qt Network Documentation, QNetworkProtocol, QUrlOperator,
194 QFtp, and Input/Output and Networking.
195 Member Type Documentation
198 This enum identifies the error that occurred.
199 QHttp::NoError - No error occurred.
201 QHttp::HostNotFound - The host name lookup failed.
203 QHttp::ConnectionRefused - The server refused the connection.
205 QHttp::UnexpectedClose - The server closed the connection unexpectedly.
207 QHttp::InvalidResponseHeader - The server sent an invalid response
209 header.
210 QHttp::WrongContentLength - The client could not read the content
212 correctly because an error with respect to the content length occurred.
213 QHttp::Aborted - The request was aborted with abort().
215 QHttp::UnknownError - An error other than those specified above
217 occurred.
218 See also error().
220
222 This enum is used to specify the state the client is in:
223 QHttp::Unconnected - There is no connection to the host.
225 QHttp::HostLookup - A host name lookup is in progress.
227 QHttp::Connecting - An attempt to connect to the host is in progress.
229 QHttp::Sending - The client is sending its request to the server.
231 QHttp::Reading - The client's request has been sent and the client is
233 reading the server's response.
234 QHttp::Connected - The connection to the host is open, but the client
236 is neither sending a request, nor waiting for a response.
237 QHttp::Closing - The connection is closing down, but is not yet closed.
239 (The state will be Unconnected when the connection is closed.)
240 See also stateChanged() and state().
242
245 Constructs a QHttp object.
246
248 Constructs a QHttp object. The parameters parent and name are passed on
249 to the QObject constructor.
250
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 See also setHost().
258
260 Destroys the QHttp object. If there is an open connection, it is
261 closed.
262
264 Aborts the current request and deletes all scheduled requests.
265 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 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 See also clearPendingRequests().
275
277 Returns the number of bytes that can be read from the response content
278 at the moment.
279 See also get(), post(), request(), readyRead(), readBlock(), and
281 readAll().
282
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 See also hasPendingRequests() and abort().
289
291 Closes the connection; this is useful if you have a keep-alive
292 connection and want to close it.
293 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 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 When the request is started the requestStarted() signal is emitted.
305 When it is finished the requestFinished() signal is emitted.
306 If you want to close the connection immediately, you have to use
308 abort() instead.
309 See also stateChanged(), abort(), requestStarted(), requestFinished(),
311 and done().
312
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 This function can be used to delete the QIODevice in the slot connected
320 to the requestFinished() signal.
321 See also get(), post(), and request().
323
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 See also currentRequest().
329
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 See also currentId().
337
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 This function can be used to delete the QIODevice in the slot connected
345 to the requestFinished() signal.
346 See also currentDestinationDevice(), post(), and request().
348
350 This signal is emitted when this object reads data from a HTTP server
351 to indicate the current progress of the download.
352 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 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 See also dataSendProgress(), get(), post(), request(), and
364 QProgressBar::progress.
365
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 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 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 See also dataReadProgress(), post(), request(), and
381 QProgressBar::progress.
382
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 See also requestFinished(), error(), and errorString().
390
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 If you start a new request, the error status is reset to NoError.
397
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
404 Sends a get request for path to the server set by setHost() or as
405 specified in the constructor.
406 path must be an absolute path like /index.html or an absolute URI like
408 http://www.trolltech.com/index.html.
409 If the IO device to is 0 the readyRead() signal is emitted every time
411 new content data is available to read.
412 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 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 When the request is started the requestStarted() signal is emitted.
424 When it is finished the requestFinished() signal is emitted.
425 See also setHost(), post(), head(), request(), requestStarted(),
427 requestFinished(), and done().
428
430 Returns TRUE if there are any requests scheduled that have not yet been
431 executed; otherwise returns FALSE.
432 The request that is being executed is not considered as a scheduled
434 request.
435 See also clearPendingRequests(), currentId(), and currentRequest().
437
439 Sends a header request for path to the server set by setHost() or as
440 specified in the constructor.
441 path must be an absolute path like /index.html or an absolute URI like
443 http://www.trolltech.com/index.html.
444 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 When the request is started the requestStarted() signal is emitted.
451 When it is finished the requestFinished() signal is emitted.
452 See also setHost(), get(), post(), request(), requestStarted(),
454 requestFinished(), and done().
455
457 Sends a post request for path to the server set by setHost() or as
459 specified in the constructor.
460 path must be an absolute path like /index.html or an absolute URI like
462 http://www.trolltech.com/index.html.
463 The incoming data comes via the data IO device.
465 If the IO device to is 0 the readyRead() signal is emitted every time
467 new content data is available to read.
468 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 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 When the request is started the requestStarted() signal is emitted.
480 When it is finished the requestFinished() signal is emitted.
481 See also setHost(), get(), head(), request(), requestStarted(),
483 requestFinished(), and done().
484
486 to = 0 )
487 This is an overloaded member function, provided for convenience. It
488 behaves essentially like the above function.
489 data is used as the content data of the HTTP request.
491
493 Reads all the bytes from the response content and returns them.
494 See also get(), post(), request(), readyRead(), bytesAvailable(), and
496 readBlock().
497
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 See also get(), post(), request(), readyRead(), bytesAvailable(), and
503 readAll().
504
506 This signal is emitted when there is new response data to read.
507 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 The response header is passed in resp.
513 You can read the data with the readAll() or readBlock() functions
515 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 See also get(), post(), request(), readAll(), readBlock(), and
522 bytesAvailable().
523
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 The incoming data comes via the data IO device.
532 If the IO device to is 0 the readyRead() signal is emitted every time
534 new content data is available to read.
535 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 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 When the request is started the requestStarted() signal is emitted.
547 When it is finished the requestFinished() signal is emitted.
548 See also setHost(), get(), post(), head(), requestStarted(),
550 requestFinished(), and done().
551
553 data, QIODevice * to = 0 )
554 This is an overloaded member function, provided for convenience. It
555 behaves essentially like the above function.
556 data is used as the content data of the HTTP request.
558
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 See also requestStarted(), done(), error(), and errorString().
565
567 This signal is emitted when processing the request identified by id
568 starts.
569 See also requestFinished() and done().
571
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 See also get(), post(), head(), request(), and readyRead().
578
580 Sets the HTTP server that is used for requests to hostname on port
581 port.
582 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 When the request is started the requestStarted() signal is emitted.
589 When it is finished the requestFinished() signal is emitted.
590 See also get(), post(), head(), request(), requestStarted(),
592 requestFinished(), and done().
593
595 Returns the current state of the object. When the state changes, the
596 stateChanged() signal is emitted.
597 See also State and stateChanged().
599
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 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 See also get(), post(), head(), request(), closeConnection(), state(),
610 and State.
611
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
623 Generated automatically from the source code.
624
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 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 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).
639Trolltech AS 2 February 2007 QHttp(3qt)