From bd0f3345a938b35ce6a12f6150373b0955b8dd12 Mon Sep 17 00:00:00 2001 From: Timothy Pearson Date: Sun, 10 Jul 2011 15:24:15 -0500 Subject: Add Qt3 development HEAD version --- doc/html/qhttp.html | 593 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 593 insertions(+) create mode 100644 doc/html/qhttp.html (limited to 'doc/html/qhttp.html') diff --git a/doc/html/qhttp.html b/doc/html/qhttp.html new file mode 100644 index 0000000..2e848cc --- /dev/null +++ b/doc/html/qhttp.html @@ -0,0 +1,593 @@ + + + + + +QHttp Class + + + + + + + +
+ +Home + | +All Classes + | +Main Classes + | +Annotated + | +Grouped Classes + | +Functions +

QHttp Class Reference
[network module]

+ +

The QHttp class provides an implementation of the HTTP protocol. +More... +

#include <qhttp.h> +

Inherits QNetworkProtocol. +

List of all member functions. +

Public Members

+ +

Public Slots

+ +

Signals

+ +

Detailed Description

+ + +The QHttp class provides an implementation of the HTTP protocol. + +

+ +

This class provides two different interfaces: one is the +QNetworkProtocol interface that allows you to use HTTP through the +QUrlOperator abstraction. The other is a direct interface to HTTP +that allows you to have more control over the requests and that +allows you to access the response header fields. +

Don't mix the two interfaces, since the behavior is not +well-defined. +

If you want to use QHttp with the QNetworkProtocol interface, you +do not use it directly, but rather through a QUrlOperator, for +example: +

+    QUrlOperator op( "http://www.trolltech.com" );
+    op.get( "index.html" );
+
+ +

This code will only work if the QHttp class is registered; to +register the class, you must call qInitNetworkProtocols() before +using a QUrlOperator with HTTP. +

The QNetworkProtocol interface for HTTP only supports the +operations operationGet() and operationPut(), i.e. +QUrlOperator::get() and QUrlOperator::put(), if you use it with a +QUrlOperator. +

The rest of this descrption describes the direct interface to +HTTP. +

The class works asynchronously, so there are no blocking +functions. If an operation cannot be executed immediately, the +function will still return straight away and the operation will be +scheduled for later execution. The results of scheduled operations +are reported via signals. This approach depends on the event loop +being in operation. +

The operations that can be scheduled (they are called "requests" +in the rest of the documentation) are the following: setHost(), +get(), post(), head() and request(). +

All of these requests return a unique identifier that allows you +to keep track of the request that is currently executed. When the +execution of a request starts, the requestStarted() signal with +the identifier is emitted and when the request is finished, the +requestFinished() signal is emitted with the identifier and a bool +that indicates if the request finished with an error. +

To make an HTTP request you must set up suitable HTTP headers. The +following example demonstrates, how to request the main HTML page +from the Trolltech home page (i.e. the URL +http://www.trolltech.com/index.html): +

+    QHttpRequestHeader header( "GET", "/index.html" );
+    header.setValue( "Host", "www.trolltech.com" );
+    http->setHost( "www.trolltech.com" );
+    http->request( header );
+
+ +

For the common HTTP requests GET, POST and HEAD, QHttp +provides the convenience functions get(), post() and head(). They +already use a reasonable header and if you don't have to set +special header fields, they are easier to use. The above example +can also be written as: +

+    http->setHost( "www.trolltech.com" ); // id == 1
+    http->get( "/index.html" );           // id == 2
+
+ +

For this example the following sequence of signals is emitted +(with small variations, depending on network traffic, etc.): +

+    requestStarted( 1 )
+    requestFinished( 1, FALSE )
+
+    requestStarted( 2 )
+    stateChanged( Connecting )
+    stateChanged( Sending )
+    dataSendProgress( 77, 77 )
+    stateChanged( Reading )
+    responseHeaderReceived( responseheader )
+    dataReadProgress( 5388, 0 )
+    readyRead( responseheader )
+    dataReadProgress( 18300, 0 )
+    readyRead( responseheader )
+    stateChanged( Connected )
+    requestFinished( 2, FALSE )
+
+    done( FALSE )
+
+    stateChanged( Closing )
+    stateChanged( Unconnected )
+
+ +

The dataSendProgress() and dataReadProgress() signals in the above +example are useful if you want to show a progressbar to inform the user about the progress of the +download. The second argument is the total size of data. In +certain cases it is not possible to know the total amount in +advance, in which case the second argument is 0. (If you connect +to a QProgressBar a total of 0 results in a busy indicator.) +

When the response header is read, it is reported with the +responseHeaderReceived() signal. +

The readyRead() signal tells you that there is data ready to be +read. The amount of data can then be queried with the +bytesAvailable() function and it can be read with the readBlock() +or readAll() functions. +

If an error occurs during the execution of one of the commands in +a sequence of commands, all the pending commands (i.e. scheduled, +but not yet executed commands) are cleared and no signals are +emitted for them. +

For example, if you have the following sequence of reqeusts +

+    http->setHost( "www.foo.bar" );       // id == 1
+    http->get( "/index.html" );           // id == 2
+    http->post( "register.html", data );  // id == 3
+
+ +

and the get() request fails because the host lookup fails, then +the post() request is never executed and the signals would look +like this: +

+    requestStarted( 1 )
+    requestFinished( 1, FALSE )
+
+    requestStarted( 2 )
+    stateChanged( HostLookup )
+    requestFinished( 2, TRUE )
+
+    done( TRUE )
+
+    stateChanged( Unconnected )
+
+ +

You can then get details about the error with the error() and +errorString() functions. Note that only unexpected behaviour, like +network failure is considered as an error. If the server response +contains an error status, like a 404 response, this is reported as +a normal response case. So you should always check the status code of the +response header. +

The functions currentId() and currentRequest() provide more +information about the currently executing request. +

The functions hasPendingRequests() and clearPendingRequests() +allow you to query and clear the list of pending requests. +

See also Qt Network Documentation, QNetworkProtocol, QUrlOperator, QFtp, and Input/Output and Networking. + +

Member Type Documentation

+

QHttp::Error

+

This enum identifies the error that occurred. +

See also error(). + +

QHttp::State

+ +

This enum is used to specify the state the client is in: +

See also stateChanged() and state(). + +

Member Function Documentation

+

QHttp::QHttp () +

+Constructs a QHttp object. + +

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

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

QHttp::QHttp ( const QString & hostname, Q_UINT16 port = 80, QObject * parent = 0, const char * name = 0 ) +

+Constructs a QHttp object. Subsequent requests are done by +connecting to the server hostname on port port. The +parameters parent and name are passed on to the QObject +constructor. +

See also setHost(). + +

QHttp::~QHttp () [virtual] +

+Destroys the QHttp object. If there is an open connection, it is +closed. + +

void QHttp::abort () [slot] +

+Aborts the current request and deletes all scheduled requests. +

For the current request, the requestFinished() signal with the error argument TRUE is emitted. For all other requests that are +affected by the abort(), no signals are emitted. +

Since this slot also deletes the scheduled requests, there are no +requests left and the done() signal is emitted (with the error +argument TRUE). +

See also clearPendingRequests(). + +

Q_ULONG QHttp::bytesAvailable () const +

+Returns the number of bytes that can be read from the response +content at the moment. +

See also get(), post(), request(), readyRead(), readBlock(), and readAll(). + +

void QHttp::clearPendingRequests () +

+Deletes all pending requests from the list of scheduled requests. +This does not affect the request that is being executed. If +you want to stop this this as well, use abort(). +

See also hasPendingRequests() and abort(). + +

int QHttp::closeConnection () +

+Closes the connection; this is useful if you have a keep-alive +connection and want to close it. +

For the requests issued with get(), post() and head(), QHttp sets +the connection to be keep-alive. You can also do this using the +header you pass to the request() function. QHttp only closes the +connection to the HTTP server if the response header requires it +to do so. +

The function does not block and returns immediately. The request +is scheduled, and its execution is performed asynchronously. The +function returns a unique identifier which is passed by +requestStarted() and requestFinished(). +

When the request is started the requestStarted() signal is +emitted. When it is finished the requestFinished() signal is +emitted. +

If you want to close the connection immediately, you have to use +abort() instead. +

See also stateChanged(), abort(), requestStarted(), requestFinished(), and done(). + +

QIODevice * QHttp::currentDestinationDevice () const +

+Returns the QIODevice pointer that is used as to store the data of the HTTP +request being executed. If there is no current request or if the request +does not store the data to an IO device, this function returns 0. +

This function can be used to delete the QIODevice in the slot connected to +the requestFinished() signal. +

See also get(), post(), and request(). + +

int QHttp::currentId () const +

+Returns the identifier of the HTTP request being executed or 0 if +there is no request being executed (i.e. they've all finished). +

See also currentRequest(). + +

QHttpRequestHeader QHttp::currentRequest () const +

+Returns the request header of the HTTP request being executed. If +the request is one issued by setHost() or closeConnection(), it +returns an invalid request header, i.e. +QHttpRequestHeader::isValid() returns FALSE. +

See also currentId(). + +

QIODevice * QHttp::currentSourceDevice () const +

+Returns the QIODevice pointer that is used as the data source of the HTTP +request being executed. If there is no current request or if the request +does not use an IO device as the data source, this function returns 0. +

This function can be used to delete the QIODevice in the slot connected to +the requestFinished() signal. +

See also currentDestinationDevice(), post(), and request(). + +

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

+ +

This signal is emitted when this object reads data from a HTTP +server to indicate the current progress of the download. +

done is the amount of data that has already arrived and total is the total amount of data. It is possible that the total +amount of data that should be transferred cannot be determined, in +which case total is 0.(If you connect to a QProgressBar, the +progress bar shows a busy indicator if the total is 0). +

Warning: done and total are not necessarily the size in +bytes, since for large files these values might need to be +"scaled" to avoid overflow. +

See also dataSendProgress(), get(), post(), request(), and QProgressBar::progress. + +

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

+ +

This signal is emitted when this object sends data to a HTTP +server to inform it about the progress of the upload. +

done is the amount of data that has already arrived and total is the total amount of data. It is possible that the total +amount of data that should be transferred cannot be determined, in +which case total is 0.(If you connect to a QProgressBar, the +progress bar shows a busy indicator if the total is 0). +

Warning: done and total are not necessarily the size in +bytes, since for large files these values might need to be +"scaled" to avoid overflow. +

See also dataReadProgress(), post(), request(), and QProgressBar::progress. + +

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

+ +

This signal is emitted when the last pending request has finished; +(it is emitted after the last request's requestFinished() signal). +error is TRUE if an error occurred during the processing; +otherwise error is FALSE. +

See also requestFinished(), error(), and errorString(). + +

Error QHttp::error () const +

+Returns the last error that occurred. This is useful to find out +what happened when receiving a requestFinished() or a done() +signal with the error argument TRUE. +

If you start a new request, the error status is reset to NoError. + +

QString QHttp::errorString () const +

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

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

+Sends a get request for path to the server set by setHost() or +as specified in the constructor. +

path must be an absolute path like /index.html or an +absolute URI like http://www.trolltech.com/index.html. +

If the IO device to is 0 the readyRead() signal is emitted +every time new content data is available to read. +

If the IO device to is not 0, the content data of the response +is written directly to the device. Make sure that the to +pointer is valid for the duration of the operation (it is safe to +delete it when the requestFinished() signal is emitted). +

The function does not block and returns immediately. The request +is scheduled, and its execution is performed asynchronously. The +function returns a unique identifier which is passed by +requestStarted() and requestFinished(). +

When the request is started the requestStarted() signal is +emitted. When it is finished the requestFinished() signal is +emitted. +

See also setHost(), post(), head(), request(), requestStarted(), requestFinished(), and done(). + +

bool QHttp::hasPendingRequests () const +

+Returns TRUE if there are any requests scheduled that have not yet +been executed; otherwise returns FALSE. +

The request that is being executed is not considered as a +scheduled request. +

See also clearPendingRequests(), currentId(), and currentRequest(). + +

int QHttp::head ( const QString & path ) +

+Sends a header request for path to the server set by setHost() +or as specified in the constructor. +

path must be an absolute path like /index.html or an +absolute URI like http://www.trolltech.com/index.html. +

The function does not block and returns immediately. The request +is scheduled, and its execution is performed asynchronously. The +function returns a unique identifier which is passed by +requestStarted() and requestFinished(). +

When the request is started the requestStarted() signal is +emitted. When it is finished the requestFinished() signal is +emitted. +

See also setHost(), get(), post(), request(), requestStarted(), requestFinished(), and done(). + +

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

+Sends a post request for path to the server set by setHost() or +as specified in the constructor. +

path must be an absolute path like /index.html or an +absolute URI like http://www.trolltech.com/index.html. +

The incoming data comes via the data IO device. +

If the IO device to is 0 the readyRead() signal is emitted +every time new content data is available to read. +

If the IO device to is not 0, the content data of the response +is written directly to the device. Make sure that the to +pointer is valid for the duration of the operation (it is safe to +delete it when the requestFinished() signal is emitted). +

The function does not block and returns immediately. The request +is scheduled, and its execution is performed asynchronously. The +function returns a unique identifier which is passed by +requestStarted() and requestFinished(). +

When the request is started the requestStarted() signal is +emitted. When it is finished the requestFinished() signal is +emitted. +

See also setHost(), get(), head(), request(), requestStarted(), requestFinished(), and done(). + +

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

+This is an overloaded member function, provided for convenience. It behaves essentially like the above function. +

data is used as the content data of the HTTP request. + +

QByteArray QHttp::readAll () +

+Reads all the bytes from the response content and returns them. +

See also get(), post(), request(), readyRead(), bytesAvailable(), and readBlock(). + +

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

+Reads maxlen bytes from the response content into data and +returns the number of bytes read. Returns -1 if an error occurred. +

See also get(), post(), request(), readyRead(), bytesAvailable(), and readAll(). + +

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

+ +

This signal is emitted when there is new response data to read. +

If you specified a device in the request where the data should be +written to, then this signal is not emitted; instead the data +is written directly to the device. +

The response header is passed in resp. +

You can read the data with the readAll() or readBlock() functions +

This signal is useful if you want to process the data in chunks as +soon as it becomes available. If you are only interested in the +complete data, just connect to the requestFinished() signal and +read the data then instead. +

See also get(), post(), request(), readAll(), readBlock(), and bytesAvailable(). + +

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

+Sends a request to the server set by setHost() or as specified in +the constructor. Uses the header as the HTTP request header. +You are responsible for setting up a header that is appropriate +for your request. +

The incoming data comes via the data IO device. +

If the IO device to is 0 the readyRead() signal is emitted +every time new content data is available to read. +

If the IO device to is not 0, the content data of the response +is written directly to the device. Make sure that the to +pointer is valid for the duration of the operation (it is safe to +delete it when the requestFinished() signal is emitted). +

The function does not block and returns immediately. The request +is scheduled, and its execution is performed asynchronously. The +function returns a unique identifier which is passed by +requestStarted() and requestFinished(). +

When the request is started the requestStarted() signal is +emitted. When it is finished the requestFinished() signal is +emitted. +

See also setHost(), get(), post(), head(), requestStarted(), requestFinished(), and done(). + +

int QHttp::request ( const QHttpRequestHeader & header, const QByteArray & data, QIODevice * to = 0 ) +

+This is an overloaded member function, provided for convenience. It behaves essentially like the above function. +

data is used as the content data of the HTTP request. + +

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

+ +

This signal is emitted when processing the request identified by +id has finished. error is TRUE if an error occurred during +the processing; otherwise error is FALSE. +

See also requestStarted(), done(), error(), and errorString(). + +

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

+ +

This signal is emitted when processing the request identified by +id starts. +

See also requestFinished() and done(). + +

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

+ +

This signal is emitted when the HTTP header of a server response +is available. The header is passed in resp. +

See also get(), post(), head(), request(), and readyRead(). + +

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

+Sets the HTTP server that is used for requests to hostname on +port port. +

The function does not block and returns immediately. The request +is scheduled, and its execution is performed asynchronously. The +function returns a unique identifier which is passed by +requestStarted() and requestFinished(). +

When the request is started the requestStarted() signal is +emitted. When it is finished the requestFinished() signal is +emitted. +

See also get(), post(), head(), request(), requestStarted(), requestFinished(), and done(). + +

State QHttp::state () const +

+Returns the current state of the object. When the state changes, +the stateChanged() signal is emitted. +

See also State and stateChanged(). + +

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

+ +

This signal is emitted when the state of the QHttp object changes. +The argument state is the new state of the connection; it is +one of the State values. +

This usually happens when a request is started, but it can also +happen when the server closes the connection or when a call to +closeConnection() succeeded. +

See also get(), post(), head(), request(), closeConnection(), state(), and State. + + +

+This file is part of the Qt toolkit. +Copyright © 1995-2007 +Trolltech. All Rights Reserved.

+ +
Copyright © 2007 +TrolltechTrademarks +
Qt 3.3.8
+
+ -- cgit v1.2.1