source: trunk/doc/html/qhttp.html

Last change on this file was 190, checked in by rudi, 14 years ago

reference documentation added
File size: 37.7 KB
RevLine 
[190]1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
2<!-- /home/espenr/tmp/qt-3.3.8-espenr-2499/qt-x11-free-3.3.8/src/network/qhttp.cpp:1010 -->
3<html>
4<head>
5<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
6<title>QHttp Class</title>
7<style type="text/css"><!--
8fn { margin-left: 1cm; text-indent: -1cm; }
9a:link { color: #004faf; text-decoration: none }
10a:visited { color: #672967; text-decoration: none }
11body { background: #ffffff; color: black; }
12--></style>
13</head>
14<body>
15
16<table border="0" cellpadding="0" cellspacing="0" width="100%">
17<tr bgcolor="#E5E5E5">
18<td valign=center>
19 <a href="index.html">
20<font color="#004faf">Home</font></a>
21 | <a href="classes.html">
22<font color="#004faf">All&nbsp;Classes</font></a>
23 | <a href="mainclasses.html">
24<font color="#004faf">Main&nbsp;Classes</font></a>
25 | <a href="annotated.html">
26<font color="#004faf">Annotated</font></a>
27 | <a href="groups.html">
28<font color="#004faf">Grouped&nbsp;Classes</font></a>
29 | <a href="functions.html">
30<font color="#004faf">Functions</font></a>
31</td>
32<td align="right" valign="center"><img src="logo32.png" align="right" width="64" height="32" border="0"></td></tr></table><h1 align=center>QHttp Class Reference<br><small>[<a href="network.html">network module</a>]</small></h1>
33
34<p>The QHttp class provides an implementation of the HTTP protocol.
35<a href="#details">More...</a>
36<p><tt>#include &lt;<a href="qhttp-h.html">qhttp.h</a>&gt;</tt>
37<p>Inherits <a href="qnetworkprotocol.html">QNetworkProtocol</a>.
38<p><a href="qhttp-members.html">List of all member functions.</a>
39<h2>Public Members</h2>
40<ul>
41<li class=fn><a href="#QHttp"><b>QHttp</b></a> ()</li>
42<li class=fn><a href="#QHttp-2"><b>QHttp</b></a> ( QObject&nbsp;*&nbsp;parent, const&nbsp;char&nbsp;*&nbsp;name = 0 )</li>
43<li class=fn><a href="#QHttp-3"><b>QHttp</b></a> ( const&nbsp;QString&nbsp;&amp;&nbsp;hostname, Q_UINT16&nbsp;port = 80, QObject&nbsp;*&nbsp;parent = 0, const&nbsp;char&nbsp;*&nbsp;name = 0 )</li>
44<li class=fn>virtual <a href="#~QHttp"><b>~QHttp</b></a> ()</li>
45<li class=fn>enum <a href="#State-enum"><b>State</b></a> { Unconnected, HostLookup, Connecting, Sending, Reading, Connected, Closing }</li>
46<li class=fn>enum <a href="#Error-enum"><b>Error</b></a> { NoError, UnknownError, HostNotFound, ConnectionRefused, UnexpectedClose, InvalidResponseHeader, WrongContentLength, Aborted }</li>
47<li class=fn>int <a href="#setHost"><b>setHost</b></a> ( const&nbsp;QString&nbsp;&amp;&nbsp;hostname, Q_UINT16&nbsp;port = 80 )</li>
48<li class=fn>int <a href="#get"><b>get</b></a> ( const&nbsp;QString&nbsp;&amp;&nbsp;path, QIODevice&nbsp;*&nbsp;to = 0 )</li>
49<li class=fn>int <a href="#post"><b>post</b></a> ( const&nbsp;QString&nbsp;&amp;&nbsp;path, QIODevice&nbsp;*&nbsp;data, QIODevice&nbsp;*&nbsp;to = 0 )</li>
50<li class=fn>int <a href="#post-2"><b>post</b></a> ( const&nbsp;QString&nbsp;&amp;&nbsp;path, const&nbsp;QByteArray&nbsp;&amp;&nbsp;data, QIODevice&nbsp;*&nbsp;to = 0 )</li>
51<li class=fn>int <a href="#head"><b>head</b></a> ( const&nbsp;QString&nbsp;&amp;&nbsp;path )</li>
52<li class=fn>int <a href="#request"><b>request</b></a> ( const&nbsp;QHttpRequestHeader&nbsp;&amp;&nbsp;header, QIODevice&nbsp;*&nbsp;data = 0, QIODevice&nbsp;*&nbsp;to = 0 )</li>
53<li class=fn>int <a href="#request-2"><b>request</b></a> ( const&nbsp;QHttpRequestHeader&nbsp;&amp;&nbsp;header, const&nbsp;QByteArray&nbsp;&amp;&nbsp;data, QIODevice&nbsp;*&nbsp;to = 0 )</li>
54<li class=fn>int <a href="#closeConnection"><b>closeConnection</b></a> ()</li>
55<li class=fn>Q_ULONG <a href="#bytesAvailable"><b>bytesAvailable</b></a> () const</li>
56<li class=fn>Q_LONG <a href="#readBlock"><b>readBlock</b></a> ( char&nbsp;*&nbsp;data, Q_ULONG&nbsp;maxlen )</li>
57<li class=fn>QByteArray <a href="#readAll"><b>readAll</b></a> ()</li>
58<li class=fn>int <a href="#currentId"><b>currentId</b></a> () const</li>
59<li class=fn>QIODevice * <a href="#currentSourceDevice"><b>currentSourceDevice</b></a> () const</li>
60<li class=fn>QIODevice * <a href="#currentDestinationDevice"><b>currentDestinationDevice</b></a> () const</li>
61<li class=fn>QHttpRequestHeader <a href="#currentRequest"><b>currentRequest</b></a> () const</li>
62<li class=fn>bool <a href="#hasPendingRequests"><b>hasPendingRequests</b></a> () const</li>
63<li class=fn>void <a href="#clearPendingRequests"><b>clearPendingRequests</b></a> ()</li>
64<li class=fn>State <a href="#state"><b>state</b></a> () const</li>
65<li class=fn>Error <a href="#error"><b>error</b></a> () const</li>
66<li class=fn>QString <a href="#errorString"><b>errorString</b></a> () const</li>
67</ul>
68<h2>Public Slots</h2>
69<ul>
70<li class=fn>void <a href="#abort"><b>abort</b></a> ()</li>
71</ul>
72<h2>Signals</h2>
73<ul>
74<li class=fn>void <a href="#stateChanged"><b>stateChanged</b></a> ( int&nbsp;state )</li>
75<li class=fn>void <a href="#responseHeaderReceived"><b>responseHeaderReceived</b></a> ( const&nbsp;QHttpResponseHeader&nbsp;&amp;&nbsp;resp )</li>
76<li class=fn>void <a href="#readyRead"><b>readyRead</b></a> ( const&nbsp;QHttpResponseHeader&nbsp;&amp;&nbsp;resp )</li>
77<li class=fn>void <a href="#dataSendProgress"><b>dataSendProgress</b></a> ( int&nbsp;done, int&nbsp;total )</li>
78<li class=fn>void <a href="#dataReadProgress"><b>dataReadProgress</b></a> ( int&nbsp;done, int&nbsp;total )</li>
79<li class=fn>void <a href="#requestStarted"><b>requestStarted</b></a> ( int&nbsp;id )</li>
80<li class=fn>void <a href="#requestFinished"><b>requestFinished</b></a> ( int&nbsp;id, bool&nbsp;error )</li>
81<li class=fn>void <a href="#done"><b>done</b></a> ( bool&nbsp;error )</li>
82</ul>
83<hr><a name="details"></a><h2>Detailed Description</h2>
84
85
86The QHttp class provides an implementation of the HTTP protocol.
87
88<p>
89
90<p> This class provides two different interfaces: one is the
91<a href="qnetworkprotocol.html">QNetworkProtocol</a> interface that allows you to use HTTP through the
92<a href="qurloperator.html">QUrlOperator</a> abstraction. The other is a direct interface to HTTP
93that allows you to have more control over the requests and that
94allows you to access the response header fields.
95<p> Don't mix the two interfaces, since the behavior is not
96well-defined.
97<p> If you want to use QHttp with the QNetworkProtocol interface, you
98do not use it directly, but rather through a QUrlOperator, for
99example:
100<p> <pre>
101 <a href="qurloperator.html">QUrlOperator</a> op( "http://www.trolltech.com" );
102 op.<a href="qurloperator.html#get">get</a>( "index.html" );
103 </pre>
104
105<p> This code will only work if the QHttp class is registered; to
106register the class, you must call <a href="qurloperator.html#qInitNetworkProtocols">qInitNetworkProtocols</a>() before
107using a QUrlOperator with HTTP.
108<p> The QNetworkProtocol interface for HTTP only supports the
109operations <a href="qnetworkprotocol.html#operationGet">operationGet</a>() and <a href="qnetworkprotocol.html#operationPut">operationPut</a>(), i.e.
110<a href="qurloperator.html#get">QUrlOperator::get</a>() and <a href="qurloperator.html#put">QUrlOperator::put</a>(), if you use it with a
111<a href="qurloperator.html">QUrlOperator</a>.
112<p> The rest of this descrption describes the direct interface to
113HTTP.
114<p> The class works asynchronously, so there are no blocking
115functions. If an operation cannot be executed immediately, the
116function will still return straight away and the operation will be
117scheduled for later execution. The results of scheduled operations
118are reported via signals. This approach depends on the event loop
119being in operation.
120<p> The operations that can be scheduled (they are called "requests"
121in the rest of the documentation) are the following: <a href="#setHost">setHost</a>(),
122<a href="#get">get</a>(), <a href="#post">post</a>(), <a href="#head">head</a>() and <a href="#request">request</a>().
123<p> All of these requests return a unique identifier that allows you
124to keep track of the request that is currently executed. When the
125execution of a request starts, the <a href="#requestStarted">requestStarted</a>() signal with
126the identifier is emitted and when the request is finished, the
127<a href="#requestFinished">requestFinished</a>() signal is emitted with the identifier and a bool
128that indicates if the request finished with an error.
129<p> To make an HTTP request you must set up suitable HTTP headers. The
130following example demonstrates, how to request the main HTML page
131from the Trolltech home page (i.e. the URL
132http://www.trolltech.com/index.html):
133<p> <pre>
134 <a href="qhttprequestheader.html">QHttpRequestHeader</a> header( "GET", "/index.html" );
135 header.<a href="qhttpheader.html#setValue">setValue</a>( "Host", "www.trolltech.com" );
136 http-&gt;setHost( "www.trolltech.com" );
137 http-&gt;request( header );
138 </pre>
139
140<p> For the common HTTP requests <tt>GET</tt>, <tt>POST</tt> and <tt>HEAD</tt>, QHttp
141provides the convenience functions <a href="#get">get</a>(), <a href="#post">post</a>() and <a href="#head">head</a>(). They
142already use a reasonable header and if you don't have to set
143special header fields, they are easier to use. The above example
144can also be written as:
145<p> <pre>
146 http-&gt;setHost( "www.trolltech.com" ); // id == 1
147 http-&gt;get( "/index.html" ); // id == 2
148 </pre>
149
150<p> For this example the following sequence of signals is emitted
151(with small variations, depending on network traffic, etc.):
152<p> <pre>
153 <a href="#requestStarted">requestStarted</a>( 1 )
154 <a href="#requestFinished">requestFinished</a>( 1, FALSE )
155
156 <a href="#requestStarted">requestStarted</a>( 2 )
157 <a href="#stateChanged">stateChanged</a>( <a href="#State-enum">Connecting</a> )
158 <a href="#stateChanged">stateChanged</a>( <a href="#State-enum">Sending</a> )
159 <a href="#dataSendProgress">dataSendProgress</a>( 77, 77 )
160 <a href="#stateChanged">stateChanged</a>( <a href="#State-enum">Reading</a> )
161 <a href="#responseHeaderReceived">responseHeaderReceived</a>( responseheader )
162 <a href="#dataReadProgress">dataReadProgress</a>( 5388, 0 )
163 <a href="#readyRead">readyRead</a>( responseheader )
164 <a href="#dataReadProgress">dataReadProgress</a>( 18300, 0 )
165 <a href="#readyRead">readyRead</a>( responseheader )
166 <a href="#stateChanged">stateChanged</a>( <a href="#State-enum">Connected</a> )
167 <a href="#requestFinished">requestFinished</a>( 2, FALSE )
168
169 <a href="#done">done</a>( FALSE )
170
171 <a href="#stateChanged">stateChanged</a>( <a href="#State-enum">Closing</a> )
172 <a href="#stateChanged">stateChanged</a>( <a href="#State-enum">Unconnected</a> )
173 </pre>
174
175<p> The <a href="#dataSendProgress">dataSendProgress</a>() and <a href="#dataReadProgress">dataReadProgress</a>() signals in the above
176example are useful if you want to show a <a href="qprogressbar.html">progressbar</a> to inform the user about the progress of the
177download. The second argument is the total size of data. In
178certain cases it is not possible to know the total amount in
179advance, in which case the second argument is 0. (If you connect
180to a <a href="qprogressbar.html">QProgressBar</a> a total of 0 results in a busy indicator.)
181<p> When the response header is read, it is reported with the
182<a href="#responseHeaderReceived">responseHeaderReceived</a>() signal.
183<p> The <a href="#readyRead">readyRead</a>() signal tells you that there is data ready to be
184read. The amount of data can then be queried with the
185<a href="#bytesAvailable">bytesAvailable</a>() function and it can be read with the <a href="#readBlock">readBlock</a>()
186or <a href="#readAll">readAll</a>() functions.
187<p> If an error occurs during the execution of one of the commands in
188a sequence of commands, all the pending commands (i.e. scheduled,
189but not yet executed commands) are cleared and no signals are
190emitted for them.
191<p> For example, if you have the following sequence of reqeusts
192<p> <pre>
193 http-&gt;setHost( "www.foo.bar" ); // id == 1
194 http-&gt;get( "/index.html" ); // id == 2
195 http-&gt;post( "register.html", data ); // id == 3
196 </pre>
197
198<p> and the <a href="#get">get</a>() request fails because the host lookup fails, then
199the <a href="#post">post</a>() request is never executed and the signals would look
200like this:
201<p> <pre>
202 <a href="#requestStarted">requestStarted</a>( 1 )
203 <a href="#requestFinished">requestFinished</a>( 1, FALSE )
204
205 <a href="#requestStarted">requestStarted</a>( 2 )
206 <a href="#stateChanged">stateChanged</a>( <a href="#State-enum">HostLookup</a> )
207 <a href="#requestFinished">requestFinished</a>( 2, TRUE )
208
209 <a href="#done">done</a>( TRUE )
210
211 <a href="#stateChanged">stateChanged</a>( <a href="#State-enum">Unconnected</a> )
212 </pre>
213
214<p> You can then get details about the error with the <a href="#error">error</a>() and
215<a href="#errorString">errorString</a>() functions. Note that only unexpected behaviour, like
216network failure is considered as an error. If the server response
217contains an error status, like a 404 response, this is reported as
218a normal response case. So you should always check the <a href="qhttpresponseheader.html#statusCode">status code</a> of the
219response header.
220<p> The functions <a href="#currentId">currentId</a>() and <a href="#currentRequest">currentRequest</a>() provide more
221information about the currently executing request.
222<p> The functions <a href="#hasPendingRequests">hasPendingRequests</a>() and <a href="#clearPendingRequests">clearPendingRequests</a>()
223allow you to query and clear the list of pending requests.
224<p> <p>See also <a href="network.html">Qt Network Documentation</a>, <a href="qnetworkprotocol.html">QNetworkProtocol</a>, <a href="qurloperator.html">QUrlOperator</a>, <a href="qftp.html">QFtp</a>, and <a href="io.html">Input/Output and Networking</a>.
225
226<hr><h2>Member Type Documentation</h2>
227<h3 class=fn><a name="Error-enum"></a>QHttp::Error</h3>
228<p> This enum identifies the error that occurred.
229<ul>
230<li><tt>QHttp::NoError</tt> - No error occurred.
231<li><tt>QHttp::HostNotFound</tt> - The host name lookup failed.
232<li><tt>QHttp::ConnectionRefused</tt> - The server refused the connection.
233<li><tt>QHttp::UnexpectedClose</tt> - The server closed the connection unexpectedly.
234<li><tt>QHttp::InvalidResponseHeader</tt> - The server sent an invalid response header.
235<li><tt>QHttp::WrongContentLength</tt> - The client could not read the content correctly
236because an error with respect to the content length occurred.
237<li><tt>QHttp::Aborted</tt> - The request was aborted with <a href="#abort">abort</a>().
238<li><tt>QHttp::UnknownError</tt> - An error other than those specified above
239occurred.
240</ul><p> <p>See also <a href="#error">error</a>().
241
242<h3 class=fn><a name="State-enum"></a>QHttp::State</h3>
243
244<p> This enum is used to specify the state the client is in:
245<ul>
246<li><tt>QHttp::Unconnected</tt> - There is no connection to the host.
247<li><tt>QHttp::HostLookup</tt> - A host name lookup is in progress.
248<li><tt>QHttp::Connecting</tt> - An attempt to connect to the host is in progress.
249<li><tt>QHttp::Sending</tt> - The client is sending its request to the server.
250<li><tt>QHttp::Reading</tt> - The client's request has been sent and the client
251is reading the server's response.
252<li><tt>QHttp::Connected</tt> - The connection to the host is open, but the client is
253neither sending a request, nor waiting for a response.
254<li><tt>QHttp::Closing</tt> - The connection is closing down, but is not yet
255closed. (The state will be <a href="#State-enum">Unconnected</a> when the connection is
256closed.)
257</ul><p> <p>See also <a href="#stateChanged">stateChanged</a>() and <a href="#state">state</a>().
258
259<hr><h2>Member Function Documentation</h2>
260<h3 class=fn><a name="QHttp"></a>QHttp::QHttp ()
261</h3>
262Constructs a QHttp object.
263
264<h3 class=fn><a name="QHttp-2"></a>QHttp::QHttp ( <a href="qobject.html">QObject</a>&nbsp;*&nbsp;parent, const&nbsp;char&nbsp;*&nbsp;name = 0 )
265</h3>
266Constructs a QHttp object. The parameters <em>parent</em> and <em>name</em>
267are passed on to the <a href="qobject.html">QObject</a> constructor.
268
269<h3 class=fn><a name="QHttp-3"></a>QHttp::QHttp ( const&nbsp;<a href="qstring.html">QString</a>&nbsp;&amp;&nbsp;hostname, Q_UINT16&nbsp;port = 80, <a href="qobject.html">QObject</a>&nbsp;*&nbsp;parent = 0, const&nbsp;char&nbsp;*&nbsp;name = 0 )
270</h3>
271Constructs a QHttp object. Subsequent requests are done by
272connecting to the server <em>hostname</em> on port <em>port</em>. The
273parameters <em>parent</em> and <em>name</em> are passed on to the <a href="qobject.html">QObject</a>
274constructor.
275<p> <p>See also <a href="#setHost">setHost</a>().
276
277<h3 class=fn><a name="~QHttp"></a>QHttp::~QHttp ()<tt> [virtual]</tt>
278</h3>
279Destroys the QHttp object. If there is an open connection, it is
280closed.
281
282<h3 class=fn>void <a name="abort"></a>QHttp::abort ()<tt> [slot]</tt>
283</h3>
284Aborts the current request and deletes all scheduled requests.
285<p> For the current request, the <a href="#requestFinished">requestFinished</a>() signal with the <tt>error</tt> argument <tt>TRUE</tt> is emitted. For all other requests that are
286affected by the <a href="#abort">abort</a>(), no signals are emitted.
287<p> Since this slot also deletes the scheduled requests, there are no
288requests left and the <a href="#done">done</a>() signal is emitted (with the <tt>error</tt>
289argument <tt>TRUE</tt>).
290<p> <p>See also <a href="#clearPendingRequests">clearPendingRequests</a>().
291
292<h3 class=fn>Q_ULONG <a name="bytesAvailable"></a>QHttp::bytesAvailable () const
293</h3>
294Returns the number of bytes that can be read from the response
295content at the moment.
296<p> <p>See also <a href="#get">get</a>(), <a href="#post">post</a>(), <a href="#request">request</a>(), <a href="#readyRead">readyRead</a>(), <a href="#readBlock">readBlock</a>(), and <a href="#readAll">readAll</a>().
297
298<h3 class=fn>void <a name="clearPendingRequests"></a>QHttp::clearPendingRequests ()
299</h3>
300Deletes all pending requests from the list of scheduled requests.
301This does not affect the request that is being executed. If
302you want to stop this this as well, use <a href="#abort">abort</a>().
303<p> <p>See also <a href="#hasPendingRequests">hasPendingRequests</a>() and <a href="#abort">abort</a>().
304
305<h3 class=fn>int <a name="closeConnection"></a>QHttp::closeConnection ()
306</h3>
307Closes the connection; this is useful if you have a keep-alive
308connection and want to close it.
309<p> For the requests issued with <a href="#get">get</a>(), <a href="#post">post</a>() and <a href="#head">head</a>(), QHttp sets
310the connection to be keep-alive. You can also do this using the
311header you pass to the <a href="#request">request</a>() function. QHttp only closes the
312connection to the HTTP server if the response header requires it
313to do so.
314<p> The function does not block and returns immediately. The request
315is scheduled, and its execution is performed asynchronously. The
316function returns a unique identifier which is passed by
317<a href="#requestStarted">requestStarted</a>() and <a href="#requestFinished">requestFinished</a>().
318<p> When the request is started the requestStarted() signal is
319emitted. When it is finished the requestFinished() signal is
320emitted.
321<p> If you want to close the connection immediately, you have to use
322<a href="#abort">abort</a>() instead.
323<p> <p>See also <a href="#stateChanged">stateChanged</a>(), <a href="#abort">abort</a>(), <a href="#requestStarted">requestStarted</a>(), <a href="#requestFinished">requestFinished</a>(), and <a href="#done">done</a>().
324
325<h3 class=fn><a href="qiodevice.html">QIODevice</a>&nbsp;* <a name="currentDestinationDevice"></a>QHttp::currentDestinationDevice () const
326</h3>
327Returns the <a href="qiodevice.html">QIODevice</a> pointer that is used as to store the data of the HTTP
328request being executed. If there is no current request or if the request
329does not store the data to an IO device, this function returns 0.
330<p> This function can be used to delete the QIODevice in the slot connected to
331the <a href="#requestFinished">requestFinished</a>() signal.
332<p> <p>See also <a href="#get">get</a>(), <a href="#post">post</a>(), and <a href="#request">request</a>().
333
334<h3 class=fn>int <a name="currentId"></a>QHttp::currentId () const
335</h3>
336Returns the identifier of the HTTP request being executed or 0 if
337there is no request being executed (i.e. they've all finished).
338<p> <p>See also <a href="#currentRequest">currentRequest</a>().
339
340<h3 class=fn><a href="qhttprequestheader.html">QHttpRequestHeader</a> <a name="currentRequest"></a>QHttp::currentRequest () const
341</h3>
342Returns the request header of the HTTP request being executed. If
343the request is one issued by <a href="#setHost">setHost</a>() or <a href="#closeConnection">closeConnection</a>(), it
344returns an invalid request header, i.e.
345<a href="qhttpheader.html#isValid">QHttpRequestHeader::isValid</a>() returns FALSE.
346<p> <p>See also <a href="#currentId">currentId</a>().
347
348<h3 class=fn><a href="qiodevice.html">QIODevice</a>&nbsp;* <a name="currentSourceDevice"></a>QHttp::currentSourceDevice () const
349</h3>
350Returns the <a href="qiodevice.html">QIODevice</a> pointer that is used as the data source of the HTTP
351request being executed. If there is no current request or if the request
352does not use an IO device as the data source, this function returns 0.
353<p> This function can be used to delete the QIODevice in the slot connected to
354the <a href="#requestFinished">requestFinished</a>() signal.
355<p> <p>See also <a href="#currentDestinationDevice">currentDestinationDevice</a>(), <a href="#post">post</a>(), and <a href="#request">request</a>().
356
357<h3 class=fn>void <a name="dataReadProgress"></a>QHttp::dataReadProgress ( int&nbsp;done, int&nbsp;total )<tt> [signal]</tt>
358</h3>
359
360<p> This signal is emitted when this object reads data from a HTTP
361server to indicate the current progress of the download.
362<p> <em>done</em> is the amount of data that has already arrived and <em>total</em> is the total amount of data. It is possible that the total
363amount of data that should be transferred cannot be determined, in
364which case <em>total</em> is 0.(If you connect to a <a href="qprogressbar.html">QProgressBar</a>, the
365progress bar shows a busy indicator if the total is 0).
366<p> <b>Warning:</b> <em>done</em> and <em>total</em> are not necessarily the size in
367bytes, since for large files these values might need to be
368"scaled" to avoid overflow.
369<p> <p>See also <a href="#dataSendProgress">dataSendProgress</a>(), <a href="#get">get</a>(), <a href="#post">post</a>(), <a href="#request">request</a>(), and <a href="qprogressbar.html#progress-prop">QProgressBar::progress</a>.
370
371<h3 class=fn>void <a name="dataSendProgress"></a>QHttp::dataSendProgress ( int&nbsp;done, int&nbsp;total )<tt> [signal]</tt>
372</h3>
373
374<p> This signal is emitted when this object sends data to a HTTP
375server to inform it about the progress of the upload.
376<p> <em>done</em> is the amount of data that has already arrived and <em>total</em> is the total amount of data. It is possible that the total
377amount of data that should be transferred cannot be determined, in
378which case <em>total</em> is 0.(If you connect to a <a href="qprogressbar.html">QProgressBar</a>, the
379progress bar shows a busy indicator if the total is 0).
380<p> <b>Warning:</b> <em>done</em> and <em>total</em> are not necessarily the size in
381bytes, since for large files these values might need to be
382"scaled" to avoid overflow.
383<p> <p>See also <a href="#dataReadProgress">dataReadProgress</a>(), <a href="#post">post</a>(), <a href="#request">request</a>(), and <a href="qprogressbar.html#progress-prop">QProgressBar::progress</a>.
384
385<h3 class=fn>void <a name="done"></a>QHttp::done ( bool&nbsp;error )<tt> [signal]</tt>
386</h3>
387
388<p> This signal is emitted when the last pending request has finished;
389(it is emitted after the last request's <a href="#requestFinished">requestFinished</a>() signal).
390<em>error</em> is TRUE if an error occurred during the processing;
391otherwise <em>error</em> is FALSE.
392<p> <p>See also <a href="#requestFinished">requestFinished</a>(), <a href="#error">error</a>(), and <a href="#errorString">errorString</a>().
393
394<h3 class=fn><a href="qhttp.html#Error-enum">Error</a> <a name="error"></a>QHttp::error () const
395</h3>
396Returns the last error that occurred. This is useful to find out
397what happened when receiving a <a href="#requestFinished">requestFinished</a>() or a <a href="#done">done</a>()
398signal with the <tt>error</tt> argument <tt>TRUE</tt>.
399<p> If you start a new request, the error status is reset to <a href="#Error-enum">NoError</a>.
400
401<h3 class=fn><a href="qstring.html">QString</a> <a name="errorString"></a>QHttp::errorString () const
402</h3>
403Returns a human-readable description of the last error that
404occurred. This is useful to present a error message to the user
405when receiving a <a href="#requestFinished">requestFinished</a>() or a <a href="#done">done</a>() signal with the <tt>error</tt> argument <tt>TRUE</tt>.
406
407<h3 class=fn>int <a name="get"></a>QHttp::get ( const&nbsp;<a href="qstring.html">QString</a>&nbsp;&amp;&nbsp;path, <a href="qiodevice.html">QIODevice</a>&nbsp;*&nbsp;to = 0 )
408</h3>
409Sends a get request for <em>path</em> to the server set by <a href="#setHost">setHost</a>() or
410as specified in the constructor.
411<p> <em>path</em> must be an absolute path like <tt>/index.html</tt> or an
412absolute URI like <a href="http://www.trolltech.com/index.html">http://www.trolltech.com/index.html</a>.
413<p> If the IO device <em>to</em> is 0 the <a href="#readyRead">readyRead</a>() signal is emitted
414every time new content data is available to read.
415<p> If the IO device <em>to</em> is not 0, the content data of the response
416is written directly to the device. Make sure that the <em>to</em>
417pointer is valid for the duration of the operation (it is safe to
418delete it when the <a href="#requestFinished">requestFinished</a>() signal is emitted).
419<p> The function does not block and returns immediately. The request
420is scheduled, and its execution is performed asynchronously. The
421function returns a unique identifier which is passed by
422<a href="#requestStarted">requestStarted</a>() and requestFinished().
423<p> When the request is started the requestStarted() signal is
424emitted. When it is finished the requestFinished() signal is
425emitted.
426<p> <p>See also <a href="#setHost">setHost</a>(), <a href="#post">post</a>(), <a href="#head">head</a>(), <a href="#request">request</a>(), <a href="#requestStarted">requestStarted</a>(), <a href="#requestFinished">requestFinished</a>(), and <a href="#done">done</a>().
427
428<h3 class=fn>bool <a name="hasPendingRequests"></a>QHttp::hasPendingRequests () const
429</h3>
430Returns TRUE if there are any requests scheduled that have not yet
431been executed; otherwise returns FALSE.
432<p> The request that is being executed is <em>not</em> considered as a
433scheduled request.
434<p> <p>See also <a href="#clearPendingRequests">clearPendingRequests</a>(), <a href="#currentId">currentId</a>(), and <a href="#currentRequest">currentRequest</a>().
435
436<h3 class=fn>int <a name="head"></a>QHttp::head ( const&nbsp;<a href="qstring.html">QString</a>&nbsp;&amp;&nbsp;path )
437</h3>
438Sends a header request for <em>path</em> to the server set by <a href="#setHost">setHost</a>()
439or as specified in the constructor.
440<p> <em>path</em> must be an absolute path like <tt>/index.html</tt> or an
441absolute URI like <a href="http://www.trolltech.com/index.html">http://www.trolltech.com/index.html</a>.
442<p> The function does not block and returns immediately. The request
443is scheduled, and its execution is performed asynchronously. The
444function returns a unique identifier which is passed by
445<a href="#requestStarted">requestStarted</a>() and <a href="#requestFinished">requestFinished</a>().
446<p> When the request is started the requestStarted() signal is
447emitted. When it is finished the requestFinished() signal is
448emitted.
449<p> <p>See also <a href="#setHost">setHost</a>(), <a href="#get">get</a>(), <a href="#post">post</a>(), <a href="#request">request</a>(), <a href="#requestStarted">requestStarted</a>(), <a href="#requestFinished">requestFinished</a>(), and <a href="#done">done</a>().
450
451<h3 class=fn>int <a name="post"></a>QHttp::post ( const&nbsp;<a href="qstring.html">QString</a>&nbsp;&amp;&nbsp;path, <a href="qiodevice.html">QIODevice</a>&nbsp;*&nbsp;data, <a href="qiodevice.html">QIODevice</a>&nbsp;*&nbsp;to = 0 )
452</h3>
453Sends a post request for <em>path</em> to the server set by <a href="#setHost">setHost</a>() or
454as specified in the constructor.
455<p> <em>path</em> must be an absolute path like <tt>/index.html</tt> or an
456absolute URI like <a href="http://www.trolltech.com/index.html">http://www.trolltech.com/index.html</a>.
457<p> The incoming data comes via the <em>data</em> IO device.
458<p> If the IO device <em>to</em> is 0 the <a href="#readyRead">readyRead</a>() signal is emitted
459every time new content data is available to read.
460<p> If the IO device <em>to</em> is not 0, the content data of the response
461is written directly to the device. Make sure that the <em>to</em>
462pointer is valid for the duration of the operation (it is safe to
463delete it when the <a href="#requestFinished">requestFinished</a>() signal is emitted).
464<p> The function does not block and returns immediately. The request
465is scheduled, and its execution is performed asynchronously. The
466function returns a unique identifier which is passed by
467<a href="#requestStarted">requestStarted</a>() and requestFinished().
468<p> When the request is started the requestStarted() signal is
469emitted. When it is finished the requestFinished() signal is
470emitted.
471<p> <p>See also <a href="#setHost">setHost</a>(), <a href="#get">get</a>(), <a href="#head">head</a>(), <a href="#request">request</a>(), <a href="#requestStarted">requestStarted</a>(), <a href="#requestFinished">requestFinished</a>(), and <a href="#done">done</a>().
472
473<h3 class=fn>int <a name="post-2"></a>QHttp::post ( const&nbsp;<a href="qstring.html">QString</a>&nbsp;&amp;&nbsp;path, const&nbsp;<a href="qbytearray.html">QByteArray</a>&nbsp;&amp;&nbsp;data, <a href="qiodevice.html">QIODevice</a>&nbsp;*&nbsp;to = 0 )
474</h3>
475This is an overloaded member function, provided for convenience. It behaves essentially like the above function.
476<p> <em>data</em> is used as the content data of the HTTP request.
477
478<h3 class=fn><a href="qbytearray.html">QByteArray</a> <a name="readAll"></a>QHttp::readAll ()
479</h3>
480Reads all the bytes from the response content and returns them.
481<p> <p>See also <a href="#get">get</a>(), <a href="#post">post</a>(), <a href="#request">request</a>(), <a href="#readyRead">readyRead</a>(), <a href="#bytesAvailable">bytesAvailable</a>(), and <a href="#readBlock">readBlock</a>().
482
483<h3 class=fn>Q_LONG <a name="readBlock"></a>QHttp::readBlock ( char&nbsp;*&nbsp;data, Q_ULONG&nbsp;maxlen )
484</h3>
485Reads <em>maxlen</em> bytes from the response content into <em>data</em> and
486returns the number of bytes read. Returns -1 if an error occurred.
487<p> <p>See also <a href="#get">get</a>(), <a href="#post">post</a>(), <a href="#request">request</a>(), <a href="#readyRead">readyRead</a>(), <a href="#bytesAvailable">bytesAvailable</a>(), and <a href="#readAll">readAll</a>().
488
489<h3 class=fn>void <a name="readyRead"></a>QHttp::readyRead ( const&nbsp;<a href="qhttpresponseheader.html">QHttpResponseHeader</a>&nbsp;&amp;&nbsp;resp )<tt> [signal]</tt>
490</h3>
491
492<p> This signal is emitted when there is new response data to read.
493<p> If you specified a device in the request where the data should be
494written to, then this signal is <em>not</em> emitted; instead the data
495is written directly to the device.
496<p> The response header is passed in <em>resp</em>.
497<p> You can read the data with the <a href="#readAll">readAll</a>() or <a href="#readBlock">readBlock</a>() functions
498<p> This signal is useful if you want to process the data in chunks as
499soon as it becomes available. If you are only interested in the
500complete data, just connect to the <a href="#requestFinished">requestFinished</a>() signal and
501read the data then instead.
502<p> <p>See also <a href="#get">get</a>(), <a href="#post">post</a>(), <a href="#request">request</a>(), <a href="#readAll">readAll</a>(), <a href="#readBlock">readBlock</a>(), and <a href="#bytesAvailable">bytesAvailable</a>().
503
504<h3 class=fn>int <a name="request"></a>QHttp::request ( const&nbsp;<a href="qhttprequestheader.html">QHttpRequestHeader</a>&nbsp;&amp;&nbsp;header, <a href="qiodevice.html">QIODevice</a>&nbsp;*&nbsp;data = 0, <a href="qiodevice.html">QIODevice</a>&nbsp;*&nbsp;to = 0 )
505</h3>
506Sends a request to the server set by <a href="#setHost">setHost</a>() or as specified in
507the constructor. Uses the <em>header</em> as the HTTP request header.
508You are responsible for setting up a header that is appropriate
509for your request.
510<p> The incoming data comes via the <em>data</em> IO device.
511<p> If the IO device <em>to</em> is 0 the <a href="#readyRead">readyRead</a>() signal is emitted
512every time new content data is available to read.
513<p> If the IO device <em>to</em> is not 0, the content data of the response
514is written directly to the device. Make sure that the <em>to</em>
515pointer is valid for the duration of the operation (it is safe to
516delete it when the <a href="#requestFinished">requestFinished</a>() signal is emitted).
517<p> The function does not block and returns immediately. The request
518is scheduled, and its execution is performed asynchronously. The
519function returns a unique identifier which is passed by
520<a href="#requestStarted">requestStarted</a>() and requestFinished().
521<p> When the request is started the requestStarted() signal is
522emitted. When it is finished the requestFinished() signal is
523emitted.
524<p> <p>See also <a href="#setHost">setHost</a>(), <a href="#get">get</a>(), <a href="#post">post</a>(), <a href="#head">head</a>(), <a href="#requestStarted">requestStarted</a>(), <a href="#requestFinished">requestFinished</a>(), and <a href="#done">done</a>().
525
526<h3 class=fn>int <a name="request-2"></a>QHttp::request ( const&nbsp;<a href="qhttprequestheader.html">QHttpRequestHeader</a>&nbsp;&amp;&nbsp;header, const&nbsp;<a href="qbytearray.html">QByteArray</a>&nbsp;&amp;&nbsp;data, <a href="qiodevice.html">QIODevice</a>&nbsp;*&nbsp;to = 0 )
527</h3>
528This is an overloaded member function, provided for convenience. It behaves essentially like the above function.
529<p> <em>data</em> is used as the content data of the HTTP request.
530
531<h3 class=fn>void <a name="requestFinished"></a>QHttp::requestFinished ( int&nbsp;id, bool&nbsp;error )<tt> [signal]</tt>
532</h3>
533
534<p> This signal is emitted when processing the request identified by
535<em>id</em> has finished. <em>error</em> is TRUE if an error occurred during
536the processing; otherwise <em>error</em> is FALSE.
537<p> <p>See also <a href="#requestStarted">requestStarted</a>(), <a href="#done">done</a>(), <a href="#error">error</a>(), and <a href="#errorString">errorString</a>().
538
539<h3 class=fn>void <a name="requestStarted"></a>QHttp::requestStarted ( int&nbsp;id )<tt> [signal]</tt>
540</h3>
541
542<p> This signal is emitted when processing the request identified by
543<em>id</em> starts.
544<p> <p>See also <a href="#requestFinished">requestFinished</a>() and <a href="#done">done</a>().
545
546<h3 class=fn>void <a name="responseHeaderReceived"></a>QHttp::responseHeaderReceived ( const&nbsp;<a href="qhttpresponseheader.html">QHttpResponseHeader</a>&nbsp;&amp;&nbsp;resp )<tt> [signal]</tt>
547</h3>
548
549<p> This signal is emitted when the HTTP header of a server response
550is available. The header is passed in <em>resp</em>.
551<p> <p>See also <a href="#get">get</a>(), <a href="#post">post</a>(), <a href="#head">head</a>(), <a href="#request">request</a>(), and <a href="#readyRead">readyRead</a>().
552
553<h3 class=fn>int <a name="setHost"></a>QHttp::setHost ( const&nbsp;<a href="qstring.html">QString</a>&nbsp;&amp;&nbsp;hostname, Q_UINT16&nbsp;port = 80 )
554</h3>
555Sets the HTTP server that is used for requests to <em>hostname</em> on
556port <em>port</em>.
557<p> The function does not block and returns immediately. The request
558is scheduled, and its execution is performed asynchronously. The
559function returns a unique identifier which is passed by
560<a href="#requestStarted">requestStarted</a>() and <a href="#requestFinished">requestFinished</a>().
561<p> When the request is started the requestStarted() signal is
562emitted. When it is finished the requestFinished() signal is
563emitted.
564<p> <p>See also <a href="#get">get</a>(), <a href="#post">post</a>(), <a href="#head">head</a>(), <a href="#request">request</a>(), <a href="#requestStarted">requestStarted</a>(), <a href="#requestFinished">requestFinished</a>(), and <a href="#done">done</a>().
565
566<h3 class=fn><a href="qhttp.html#State-enum">State</a> <a name="state"></a>QHttp::state () const
567</h3>
568Returns the current state of the object. When the state changes,
569the <a href="#stateChanged">stateChanged</a>() signal is emitted.
570<p> <p>See also <a href="#State-enum">State</a> and <a href="#stateChanged">stateChanged</a>().
571
572<h3 class=fn>void <a name="stateChanged"></a>QHttp::stateChanged ( int&nbsp;state )<tt> [signal]</tt>
573</h3>
574
575<p> This signal is emitted when the state of the QHttp object changes.
576The argument <em>state</em> is the new state of the connection; it is
577one of the <a href="#State-enum">State</a> values.
578<p> This usually happens when a request is started, but it can also
579happen when the server closes the connection or when a call to
580<a href="#closeConnection">closeConnection</a>() succeeded.
581<p> <p>See also <a href="#get">get</a>(), <a href="#post">post</a>(), <a href="#head">head</a>(), <a href="#request">request</a>(), <a href="#closeConnection">closeConnection</a>(), <a href="#state">state</a>(), and <a href="#State-enum">State</a>.
582
583<!-- eof -->
584<hr><p>
585This file is part of the <a href="index.html">Qt toolkit</a>.
586Copyright &copy; 1995-2007
587<a href="http://www.trolltech.com/">Trolltech</a>. All Rights Reserved.<p><address><hr><div align=center>
588<table width=100% cellspacing=0 border=0><tr>
589<td>Copyright &copy; 2007
590<a href="troll.html">Trolltech</a><td align=center><a href="trademarks.html">Trademarks</a>
591<td align=right><div align=right>Qt 3.3.8</div>
592</table></div></address></body>
593</html>
Note: See TracBrowser for help on using the repository browser.