QAbstractHttpServer Class

The QAbstractHttpServer class is the base of HTTP servers: it accepts connections and parses requests. More…

List of all members, including inherited members

Public Functions

Signals

Protected Functions

Detailed Description

A QAbstractHttpServer serves the connections of the QTcpServer and QLocalServer objects bound to it with bind(). It reads HTTP/1.0 and HTTP/1.1 requests, with persistent connections and pipelining, and calls handleRequest() for each complete request. Subclasses decide how to answer; QHttpServer answers with routes.

class Hello : public QAbstractHttpServer {
protected:
    bool handleRequest(const QHttpServerRequest &request, QHttpServerResponder &responder) override {
        if (request.url().path() != "/")
            return false;
        responder.write("Hello\n", "text/plain");
        return true;
    }
    void missingHandler(const QHttpServerRequest &, QHttpServerResponder &responder) override {
        responder.write(QHttpServerResponder::StatusCode::NotFound);
    }
};

Bind a QSslServer to serve HTTPS: its connections reach the server once the TLS handshake is done, and the URLs of their requests have the scheme https.

The server refuses requests it cannot parse with 400 Bad Request and closes the connection. It also refuses a request line over 8 KiB (414), header fields over 64 KiB or more than 100 of them (431), and a body over 64 MiB (413). A request with both Transfer-Encoding and Content-Length is refused, since a proxy in front of the server could frame it differently.

Requests with an Upgrade: websocket header can become WebSocket connections on the same port; see addWebSocketUpgradeVerifier().

See also QHttpServer and Using Nt HTTP Server.

Differences from Qt

Member Function Documentation

[explicit] QAbstractHttpServer::QAbstractHttpServer(QObject *parent = nullptr)

Constructs an HTTP server with the given parent. It serves nothing until a server is bound to it with bind().

[override] QAbstractHttpServer::~QAbstractHttpServer()

Destroys the HTTP server and closes its connections. Bound servers that are its children are destroyed too.

template <typename Handler>void QAbstractHttpServer::addWebSocketUpgradeVerifier(const QObject *context, Handler &&func)

Adds func, which decides whether a request to upgrade to WebSocket is accepted. It takes const QHttpServerRequest & and returns a QHttpServerWebSocketUpgradeResponse. If func is a member function, it is called on context; the verifier is dropped when context is destroyed.

Each request with an Upgrade: websocket header goes to the verifiers in the order they were added, until one accepts or denies it. A request that no verifier accepts is refused with 403 Forbidden, so a server without verifiers accepts no WebSockets. An accepted request becomes a QWebSocket, and newWebSocketConnection() is emitted.

See also nextPendingWebSocketConnection().

bool QAbstractHttpServer::bind(QTcpServer *server)

Serves the connections that server accepts from now on, and returns true. The server must already be listening; if it is not, or if it is null, nothing happens and false is returned.

A server without a parent becomes a child of this object. Several servers can be bound, for example one for HTTP and one for HTTPS.

auto *tcpServer = new QTcpServer;
if (!tcpServer->listen(QHostAddress::LocalHost, port) || !server.bind(tcpServer)) {
    std::fprintf(stderr, "cannot listen on port %u: %s\n", port, qPrintable(tcpServer->errorString()));
    delete tcpServer;
    return 1;
}
std::printf("listening on http://127.0.0.1:%u/\n", tcpServer->serverPort());

See also servers() and serverPorts().

bool QAbstractHttpServer::bind(QLocalServer *server)

This is an overloaded function.

Serves the connections that the local socket server server accepts from now on, and returns true. The server must already be listening; if it is not, or if it is null, nothing happens and false is returned.

[virtual, protected] bool QAbstractHttpServer::handleRequest(const QHttpServerRequest &request, QHttpServerResponder &responder)

Handles request and answers it through responder. Returns true if the request was handled, or false to have missingHandler() called for it.

The responder may be moved out to answer the request later; the connection waits for that answer before it reads the next request.

See also missingHandler().

bool QAbstractHttpServer::hasPendingWebSocketConnections() const

Returns true if accepted WebSocket connections are waiting for nextPendingWebSocketConnection(); otherwise returns false.

QList<QLocalServer *> QAbstractHttpServer::localServers() const

Returns the local socket servers bound to this server that still exist.

See also bind() and servers().

[virtual, protected] void QAbstractHttpServer::missingHandler(const QHttpServerRequest &request, QHttpServerResponder &responder)

Answers request, which handleRequest() did not handle, through responder. A typical implementation sends 404 Not Found.

See also handleRequest().

[signal] void QAbstractHttpServer::newWebSocketConnection()

This signal is emitted when a request to upgrade to WebSocket was accepted. Take the socket with nextPendingWebSocketConnection().

See also addWebSocketUpgradeVerifier().

std::unique_ptr<QWebSocket> QAbstractHttpServer::nextPendingWebSocketConnection()

Returns the next accepted WebSocket connection, or nullptr if there is none. The caller owns the socket, which has no parent.

See also newWebSocketConnection() and addWebSocketUpgradeVerifier().

QList<quint16> QAbstractHttpServer::serverPorts() const

Returns the ports of the bound TCP servers that are listening.

See also bind() and servers().

QList<QTcpServer *> QAbstractHttpServer::servers() const

Returns the TCP servers bound to this server that still exist.

See also bind() and localServers().