QHttp(3qt)

📦 version 3.3.8b, in fedora 43, fedora 44

💖 QHttp 💖

ok so bestie, welcome to the QHttp(3qt) manual page. yes, 3qt, that's the manual it lives in. sit down, grab a strawberry drink 🍓, we're doing HTTP the Qt way and honestly? it's giving iconic.

✨ NAME ✨

QHttp — the implementation of the HTTP protocol, fr fr. that's the whole vibe. 💅

🌈 SYNOPSIS 🌈

#include <qhttp.h>

Inherits QNetworkProtocol. yes bestie, it's a whole inheritance situation, main character energy.

👑 Public Members

  • QHttp()
  • QHttp( QObject * parent, const char * name = 0 )
  • QHttp( const QString & hostname, Q_UINT16 port = 80, QObject * parent = 0, const char * name = 0 )
  • virtual ~QHttp()
  • enum State { Unconnected, HostLookup, Connecting, Sending, Reading, Connected, Closing }
  • enum Error { NoError, UnknownError, HostNotFound, ConnectionRefused, UnexpectedClose, InvalidResponseHeader, WrongContentLength, Aborted }
  • int setHost( const QString & hostname, Q_UINT16 port = 80 )
  • int get( const QString & path, QIODevice * to = 0 )
  • int post( const QString & path, QIODevice * data, QIODevice * to = 0 )
  • int post( const QString & path, const QByteArray & data, QIODevice * to = 0 )
  • int head( const QString & path )
  • int request( const QHttpRequestHeader & header, QIODevice * data = 0, QIODevice * to = 0 )
  • int request( const QHttpRequestHeader & header, const QByteArray & data, QIODevice * to = 0 )
  • int closeConnection()
  • Q_ULONG bytesAvailable() const
  • Q_LONG readBlock( char * data, Q_ULONG maxlen )
  • QByteArray readAll()
  • int currentId() const
  • QIODevice * currentSourceDevice() const
  • QIODevice * currentDestinationDevice() const
  • QHttpRequestHeader currentRequest() const
  • bool hasPendingRequests() const
  • void clearPendingRequests()
  • State state() const
  • Error error() const
  • QString errorString() const

🌸 Public Slots

  • void abort()

🦋 Signals

  • void stateChanged( int state )
  • void responseHeaderReceived( const QHttpResponseHeader & resp )
  • void readyRead( const QHttpResponseHeader & resp )
  • void dataSendProgress( int done, int total )
  • void dataReadProgress( int done, int total )
  • void requestStarted( int id )
  • void requestFinished( int id, bool error )
  • void done( bool error )

💜 DESCRIPTION 💜

okay so the QHttp class provides an implementation of the HTTP protocol. that's the whole point, that's the assignment, and it ate. 🔥

here's the tea: this class gives you two different interfaces. one is the QNetworkProtocol interface, which lets you do HTTP through the QUrlOperator abstraction. the other one is a direct interface to HTTP that gives you way more control over the requests and lets you actually get at the response header fields. two paths, pick one.

⚠️ do NOT mix the two interfaces, because the behavior is not well-defined. like, at all. not even a little. undefined behavior is not the vibe bestie, just don't. 💀

if you wanna use QHttp with the QNetworkProtocol interface, you don't use it directly — you go through a QUrlOperator, like so:

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

and this code only works if the QHttp class is registered. to register it you must call qInitNetworkProtocols() before you use a QUrlOperator with HTTP. no registration, no service. periodt. ✨

also, the QNetworkProtocol interface for HTTP only supports the operations operationGet() and operationPut(), i.e. QUrlOperator::get() and QUrlOperator::put(), when you use it with a QUrlOperator. that's it, that's the list.

the rest of this description is about the direct interface to HTTP. buckle up.

this class works asynchronously, so there are no blocking functions. if an operation can't be executed immediately, the function still returns straight away and the operation gets scheduled for later. the results of scheduled operations get reported via signals. this whole approach depends on the event loop actually being in operation, so like… keep your event loop running bestie. 🫶

the operations that can be scheduled — and in the rest of this documentation they're called "requests" — are these ones: setHost(), get(), post(), head() and request().

all of these requests return a unique identifier, which lets you keep track of the request currently being executed. when a request starts executing, the requestStarted() signal goes out with the identifier, and when the request is finished, the requestFinished() signal goes out with the identifier plus a bool that tells you if the request finished with an error. tracking, but make it cute. 🎀

to make an HTTP request you gotta set up suitable HTTP headers. here's how you'd request the main HTML page from the Trolltech home page (that's 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, so if you don't need special header fields, they're way easier to use. that example up there? can also be written as:

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

and for this example, the sequence of signals that gets emitted goes like this (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 up there are useful if you wanna show a progressbar and keep the user posted about how the download's going. the second argument is the total size of data. in certain cases it's not possible to know the total amount in advance — in that case the second argument is 0. (and psst, if you connect to a QProgressBar, a total of 0 gives you a busy indicator. cute.) 🌈

when the response header gets read, it's reported with the responseHeaderReceived() signal.

the readyRead() signal tells you there's data ready to be read. you can then query how much data there is with the bytesAvailable() function, and read it 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) get cleared and no signals are emitted for them. gone. ghosted. no closure, sorry. 😭

for example, if you have this sequence of requests:

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 an error. if the server response contains an error status, like a 404 response, that's reported as a normal response case. so you should always check the status code of the response header. always always. 👑

the functions currentId() and currentRequest() give you more info about the currently executing request.

the functions hasPendingRequests() and clearPendingRequests() let you query and clear the list of pending requests. so much agency. 💅

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. here's the whole roster:

  • QHttp::NoError — no error occurred. the dream. ✨
  • QHttp::HostNotFound — the host name lookup failed.
  • QHttp::ConnectionRefused — the server refused the connection. rude.
  • QHttp::UnexpectedClose — the server closed the connection unexpectedly.
  • QHttp::InvalidResponseHeader — the server sent an invalid response header.
  • QHttp::WrongContentLength — the client could not read the content correctly because an error with respect to the content length occurred.
  • QHttp::Aborted — the request was aborted with abort().
  • QHttp::UnknownError — an error other than those specified above occurred. mystery error, iykyk. 🙈

See also error().

QHttp::State

this enum is used to specify the state the client is in:

  • QHttp::Unconnected — there is no connection to the host.
  • QHttp::HostLookup — a host name lookup is in progress.
  • QHttp::Connecting — an attempt to connect to the host is in progress.
  • QHttp::Sending — the client is sending its request to the server.
  • QHttp::Reading — the client's request has been sent and the client is reading the server's response.
  • QHttp::Connected — the connection to the host is open, but the client is neither sending a request, nor waiting for a response.
  • QHttp::Closing — the connection is closing down, but is not yet closed. (the state will be Unconnected when the connection is closed.)

See also stateChanged() and state().

🧚 MEMBER FUNCTION DOCUMENTATION 🧚

QHttp::QHttp()

Constructs a QHttp object. fresh out the box, no notes. 🌸

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. clean exit, no loose ends, we love to see it. 💅

void QHttp::abort() [slot]

Aborts the current request and deletes all scheduled requests. brutal. necessary. iconic.

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

and since this slot also deletes the scheduled requests, there are no requests left, so the done() signal gets emitted too (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. note this does not affect the request that is being executed. if you wanna stop that one too, use abort().

See also hasPendingRequests() and abort().

🌸 int QHttp::closeConnection ()

Okay bestie, this one does exactly what it says on the tin: it closes the connection. Super handy when you've got a keep-alive situation going on and you're like "okay we're done here, bye 💅".

For requests you sent with get(), post() and head(), QHttp already sets the connection to be keep-alive. You can also do that yourself with the header you hand to the request() function. And heads up: QHttp only closes the connection to the HTTP server if the response header literally requires it to.

It does not block, okay? It returns immediately. The request gets scheduled and executed asynchronously, and you get back a unique identifier that shows up again via requestStarted() and requestFinished().

When the request kicks off, the requestStarted() signal goes off 🎀. When it wraps up, requestFinished() fires. Periodt.

If you want to close the connection immediately, you gotta use abort() instead — no waiting around.

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

🦋 QIODevice * QHttp::currentDestinationDevice () const

Hands you back the QIODevice pointer that's being used to store the data of the HTTP request currently in motion. But — plot twist — if there's no current request, or if the request isn't storing its data to an IO device at all, this returns 0.

Lowkey useful move: you can use this to delete the QIODevice inside the slot you connected to the requestFinished() signal.

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

⭐ int QHttp::currentId () const

Returns the identifier of the HTTP request currently being executed, or 0 if there's literally no request running (i.e. they've all finished, we're free 🫶).

See also currentRequest().

💜 QHttpRequestHeader QHttp::currentRequest () const

Gives you the request header of the HTTP request being executed right now. But if that request was one issued by setHost() or closeConnection(), it returns an invalid request header — meaning QHttpRequestHeader::isValid() returns FALSE.

See also currentId().

🌈 QIODevice * QHttp::currentSourceDevice () const

Returns the QIODevice pointer being used as the data source of the HTTP request in progress. If there's no current request, or the request doesn't use an IO device as its data source, you get 0. No vibes, no device.

Same cute trick as before: you can use this to delete the QIODevice in the slot connected to requestFinished().

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

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

Emitted whenever this object reads data from a HTTP server, so you can track how far along the download is. Iconic progress-bar energy 📊.

done = how much data has already arrived. total = the total amount of data. It's totally possible that the total can't be figured out — in that case total is 0. (And if you hook this up to a QProgressBar, the bar just shows a busy indicator when total is 0.)

Warning: done and total are not necessarily the size in bytes, because for large files these values might need to be "scaled" to avoid overflow. So don't do byte math on them, bestie 😭.

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

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

Same deal but for the other direction: emitted when this object sends data to a HTTP server, keeping you posted on the upload's progress 🚀.

done is the amount of data that's already arrived and total is the total amount of data. Again, the total might not be determinable, in which case total is 0. (Connect it to a QProgressBar and the bar shows a busy indicator when 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. Same rules as above, no exceptions 💀.

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

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

Emitted when the last pending request has finished — and yes, it's emitted after that last request's requestFinished() signal, so the order matters, iykyk. error is TRUE if an error happened during processing; otherwise it's FALSE.

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

👑 Error QHttp::error () const

Returns the last error that occurred. Chef's kiss for figuring out what actually went down when you get a requestFinished() or a done() signal with the error argument set to TRUE.

One thing to know: if you start a new request, the error status gets reset to NoError. Fresh slate, new era ✨.

🫶 QString QHttp::errorString () const

Returns a human-readable description of the last error that happened. This is the one you want when you're presenting an error message to a user after receiving a requestFinished() or a done() signal with the error argument TRUE. Don't show them a raw error code, show them the words 💖.

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

Sends a get request for path to the server set by setHost(), or to whatever you specified in the constructor.

path has to 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 single time new content data is available to read.

If to is not 0, the content data of the response gets written directly to the device. Make sure that to pointer stays valid for the whole duration of the operation — and yes, it's safe to delete it once the requestFinished() signal has been emitted.

Does not block. Returns immediately. The request is scheduled and executed asynchronously, and you get back a unique identifier that gets passed along by requestStarted() and requestFinished().

requestStarted() fires when the request starts, requestFinished() fires when it's done.

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

⭐ bool QHttp::hasPendingRequests () const

Returns TRUE if there are any requests scheduled that haven't been executed yet; otherwise FALSE.

Important lil detail: the request that's currently being executed does not count as a scheduled request. So it's not counting the one in flight, just the ones in the queue.

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 to whatever you set in the constructor.

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

Non-blocking, returns immediately, scheduled and executed asynchronously, unique identifier returned that gets passed by requestStarted() and requestFinished().

requestStarted() on start, requestFinished() on finish. Standard behavior, slay.

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 through the data IO device 📥.

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

If to is not 0, the content data of the response is written straight to the device. Keep that to pointer valid for the duration of the operation (deleting it when requestFinished() is emitted is safe, promise).

Doesn't block, returns immediately, scheduled + async, unique identifier returned and passed by requestStarted() and requestFinished().

requestStarted() when it starts, requestFinished() when it's done. That's the rhythm 💅.

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 function above.

data is used as the content data of the HTTP request. Easy peasy 🍓.

🎀 QByteArray QHttp::readAll ()

Reads all the bytes from the response content and returns them. The whole thing. Every last byte, bestie.

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]

Emitted whenever there's new response data to read. The main character signal of streaming, honestly.

Heads up though: if you specified a device in the request for the data to be written to, then this signal is not emitted — instead the data goes directly to that device.

The response header gets passed in resp.

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

This signal is genuinely useful if you wanna process the data in chunks as soon as it becomes available. But if you only care about the complete data, just connect to the requestFinished() signal and read everything then instead. Choose your fighter 💅.

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 header as the HTTP request header. And listen — you are responsible for setting up a header that's appropriate for your request. That's on you, no cap.

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 to is not 0, the content data of the response is written directly to the device. Make sure the to pointer stays valid for the duration of the operation (safe to delete it when the requestFinished() signal is emitted).

Does not block and returns immediately. The request is scheduled, executed asynchronously, and you get back a unique identifier passed by requestStarted() and requestFinished().

requestStarted() fires when it starts. requestFinished() fires when it's finished. Every time, no exceptions ✨.

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

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

Another overloaded member function, provided for convenience. Behaves essentially like the one above.

data is used as the content data of the HTTP request. That's it, that's the function 🫶.

  • void QHttp::requestFinished ( int id, bool error ) [signal] — the moment of truth, bestie 🎀. This signal pops off when the request identified by id is officially done done. And error? It's TRUE if something went sideways during processing, and FALSE if everything was giving flawless ✨.

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

  • void QHttp::requestStarted ( int id ) [signal] — emitted right when the request identified by id starts doing its thing 🦋. Like the little "and we're rolling!" moment.

See also requestFinished() and done().

  • void QHttp::responseHeaderReceived ( const QHttpResponseHeader & resp ) [signal] — okay so when the HTTP header of a server response finally shows up, this signal says hi 👋. The header itself comes through in resp. The way the server just hands it over...

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

  • int QHttp::setHost ( const QString & hostname, Q_UINT16 port = 80 ) — sets the HTTP server used for requests to hostname on port port 🌸. That default port of 80? Iconic, classic, the standard. 👑

Now listen: this function does not block and returns immediately, no waiting around, no standing in line 💅. The request gets scheduled and its execution is performed asynchronously. The function hands you back a unique identifier, and that identifier gets passed along by requestStarted() and requestFinished() — so keep it, bestie, it's your receipt 🧾.

When the request is started, the requestStarted() signal is emitted. When it's finished, the requestFinished() signal is emitted. Full arc, beginning to end, no notes.

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

  • State QHttp::state () const — returns the current state of the object 👑. And the second that state changes? The stateChanged() signal gets emitted. Glow-up notification, basically. ✨

See also State and stateChanged().

  • void QHttp::stateChanged ( int state ) [signal] — emitted when the state of the QHttp object changes 🦋. The argument state is the new state of the connection, and it's one of the State values.

This usually goes down when a request is started, but it can also happen when the server closes the connection, or when a call to closeConnection() succeeded. So many plot twists, honestly 💀.

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

🌈 SEE ALSO 🌈

Copyright 1992-2007 Trolltech ASA, http://www.trolltech.com. See the license file included in the distribution for a complete license statement. Read the license, bestie, it's literally right there 💜

💅 AUTHOR 💅

Generated automatically from the source code. (yes, a robot wrote it, and it ate, fr fr 🤖✨)

🫶 BUGS 🫶

If you find a bug in Qt, please report it as described in http://doc.trolltech.com/bughowto.html. Good bug reports help us to help you. Thank you. 🥺 Being a good bug reporter is highkey main character energy.

The definitive Qt documentation is provided in HTML format; it is located at $QTDIR/doc/html and can be read using Qt Assistant or with a web browser 🌐. This man page is provided as a convenience for those users who prefer man pages, although this format is not officially supported by Trolltech.

So real talk: this man page is a little treat for the man-page girlies, not the official word. If something matters, go read the HTML. 💖

If you find errors in this manual page, please report them to qt-bugs@trolltech.com 📧. Please include the name of the manual page (qhttp.3qt) and the Qt version (3.3.8). Like, both of those, okay? Don't make them guess 🙈.

And that's a wrap on the QHttp(3qt) page, bestie 💜 — this gem came from Trolltech AS and is dated 2 February 2007. Three whole parts and we got through every single option, signal, and state together. Slay, fr fr. Now go make some requests. ✨🌸🎀

📦 where this page comes from