Using QHttp

The QHttp class implements the client side of the HTTP protocol in Qt. It provides various functions to perform the most common HTTP operations, including get() and post(), and provides a means of sending arbitrary HTTP requests. If you have read the previous section about QFtp, you will find that there are many similarities between QFtp and QHttp.

The QHttp class works asynchronously. When we call a function like get() or post(), the function returns immediately, and the data transfer occurs later, when control returns to Qt's event loop. This ensures that the application's user interface remains responsive while HTTP requests are being processed.

We will review an example that shows how to download an HTML file from Trolltech's web site from a Qt application's MainWindow class. We will omit the header file because it is very similar to the one we used in the previous section (p.284), with a private slot (httpDone(bool)) and private variables (http of type QHttp and file of type QFile).

MainWindow::MainWindow(QWidget *parent, const char *name)
 : QMainWindow(parent, name)
{
 ...
 connect(&http, SIGNAL(done(bool)), this, SLOT(httpDone(bool)));
}

In the constructor, we connect the QHttp object's done(bool) signal to the MainWindow's httpDone(bool) slot.

void MainWindow::getFile()
{
 file.setName("aboutqt.html");
 if (!file.open(IO_WriteOnly)) {
 QMessageBox::warning(this, tr("HTTP Get"),
 tr("Cannot write file %1
%2.")
 .arg(file.name())
 .arg(file.errorString()));
 return;
 }

 http.setHost("doc.trolltech.com");
 http.get("/3.2/aboutqt.html", &file);
 http.closeConnection();
}

The getFile() function downloads the http://doc.trolltech.com/3.2/aboutqt.html file and saves it as aboutqt.html in the current directory.

We open the QFile for writing and schedule a sequence of three HTTP requests using our QHttp object. The second argument to get() specifies the output I/O device.

The HTTP requests are queued and executed in Qt's event loop. The completion of the commands is indicated by QHttp's done(bool) signal, which we connected to httpDone(bool) in the constructor.

void MainWindow::httpDone(bool error)
{
 if (error)
 QMessageBox::warning(this, tr("HTTP Get"),
 tr("Error while fetching file with"
 "HTTP: %1.")
 .arg(http.errorString()));
 file.close();
}

Once the HTTP requests are finished, we close the file. If an error occurred, we display the error message in a QMessageBox.

QHttp provides the following operations: setHost(), get(), post(), and head(). For example, here's how we would use post() to send a list of "name = value" pairs to a CGI script:

http.setHost("www.example.com");
http.post("/cgi/somescript.py", QCString("x=200&y=320"), &file);

For more control, we can use the request() function, which accepts an arbitrary HTTP header and data. For example:

QHttpRequestHeader header("POST", "/search.html");
header.setValue("Host", "www.trolltech.com");
header.setContentType("application/x-www-form-urlencoded");
http.setHost("www.trolltech.com");
http.request(header, QCString("qt-interest=on&search=opengl"));

QHttp emits the requestStarted(int) signal when it starts executing a request, and it emits the requestFinished(int, bool) signal when the request has finished. The int parameter is an ID number that identifies a request. If we are interested in the fate of individual requests, we can store the ID numbers when we schedule the requests. Keeping track of the ID numbers allows us to provide detailed feedback to the user.

In most applications, we only want to know whether the entire sequence of requests completed successfully or not. This is easily achieved by connecting to the done(bool) signal, which is emitted when the request queue becomes empty.

When an error occurs, the request queue is automatically cleared. But if we schedule new requests after the error has occurred using the same QHttp object, these requests will be queued and sent as usual.

Like QFtp, QHttp provides a readyRead() signal as well as the readBlock() and readAll() functions that we can use instead of specifying an I/O device. It also provides a dataTransferProgress(int, int) signal that can be connected to a QProgressBar or to a QProgressDialog's setProgress(int, int) slot.