QAbstractHttpServer Class
API to subclass to implement an HTTP server. More...
Header: | #include <QAbstractHttpServer> |
CMake: | find_package(Qt6 REQUIRED COMPONENTS HttpServer) target_link_libraries(mytarget PRIVATE Qt6::HttpServer) |
qmake: | QT += httpserver |
Since: | Qt 6.4 |
Inherits: | QObject |
Inherited By: | |
Status: | Technical Preview |
Public Functions
QAbstractHttpServer(QObject *parent = nullptr) | |
bool | bind(QLocalServer *server) |
bool | bind(QTcpServer *server) |
bool | hasPendingWebSocketConnections() const |
(since 6.8) QHttp2Configuration | http2Configuration() const |
quint16 | listen(const QHostAddress &address = QHostAddress::Any, quint16 port = 0) |
QList<QLocalServer *> | localServers() const |
std::unique_ptr<QWebSocket> | nextPendingWebSocketConnection() |
void | registerWebSocketUpgradeVerifier(Functor &&func) |
QList<quint16> | serverPorts() const |
QList<QTcpServer *> | servers() const |
(since 6.8) void | setHttp2Configuration(const QHttp2Configuration &configuration) |
void | sslSetup(const QSslConfiguration &sslConfiguration) |
void | sslSetup(const QSslCertificate &certificate, const QSslKey &privateKey, QSsl::SslProtocol protocol = QSsl::SecureProtocols) |
Signals
void | newWebSocketConnection() |
Protected Functions
virtual bool | handleRequest(const QHttpServerRequest &request, QHttpServerResponder &responder) = 0 |
virtual void | missingHandler(const QHttpServerRequest &request, QHttpServerResponder &&responder) = 0 |
Detailed Description
Subclass this class and override handleRequest() and missingHandler() to create an HTTP server. Use listen() or bind() to start listening to incoming connections.
Member Function Documentation
[explicit]
QAbstractHttpServer::QAbstractHttpServer(QObject *parent = nullptr)
Creates an instance of QAbstractHttpServer with the parent parent.
bool QAbstractHttpServer::bind(QLocalServer *server)
Bind the HTTP server to given QLocalServer server over which the transmission happens. It is possible to call this function multiple times with different instances of server to handle multiple connections.
After calling this function, every _new_ connection will be handled and forwarded by the HTTP server.
It is the user's responsibility to call QLocalServer::listen() on the server before calling this function. If server is not listening, nothing will happen and false
will be returned.
If the server is nullptr false is returned.
If successful the server will be parented to this HTTP server and true
is returned.
See also QLocalServer and QLocalServer::listen().
bool QAbstractHttpServer::bind(QTcpServer *server)
Bind the HTTP server to given TCP server over which the transmission happens. It is possible to call this function multiple times with different instances of TCP server to handle multiple connections and ports, for example both SSL and non-encrypted connections.
After calling this function, every _new_ connection will be handled and forwarded by the HTTP server.
It is the user's responsibility to call QTcpServer::listen() on the server before calling this function. If server is not listening, nothing will happen and false
will be returned.
If the server is nullptr false is returned.
If successful the server will be parented to this HTTP server and true
is returned.
See also QTcpServer and QTcpServer::listen().
[pure virtual protected]
bool QAbstractHttpServer::handleRequest(const QHttpServerRequest &request, QHttpServerResponder &responder)
Overload this function to handle each incoming request, by examining the request and sending the appropriate response back to responder. Return true
if the request was handled successfully. If this method returns false
, missingHandler() will be called afterwards.
This function must move out of responder before returning true
.
bool QAbstractHttpServer::hasPendingWebSocketConnections() const
Returns true
if the server has pending WebSocket connections; otherwise returns false
.
See also newWebSocketConnection(), nextPendingWebSocketConnection(), and registerWebSocketUpgradeVerifier().
[since 6.8]
QHttp2Configuration QAbstractHttpServer::http2Configuration() const
Returns server's HTTP/2 configuration parameters.
This function was introduced in Qt 6.8.
See also setHttp2Configuration().
quint16 QAbstractHttpServer::listen(const QHostAddress &address = QHostAddress::Any, quint16 port = 0)
Tries to bind a QTcpServer
to address and port.
Returns the server port upon success, 0 otherwise.
QList<QLocalServer *> QAbstractHttpServer::localServers() const
Returns list of child TCP servers of this HTTP server.
See also serverPorts().
[pure virtual protected]
void QAbstractHttpServer::missingHandler(const QHttpServerRequest &request, QHttpServerResponder &&responder)
This function is called whenever handleRequest() returns false
, or if there is a WebSocket upgrade attempt and either there are no connections to newWebSocketConnection() or there are no matching WebSocket verifiers. The request and responder parameters are the same as handleRequest() was called with.
See also handleRequest() and registerWebSocketUpgradeVerifier().
[signal]
void QAbstractHttpServer::newWebSocketConnection()
This signal is emitted every time a new WebSocket connection is available.
See also hasPendingWebSocketConnections(), nextPendingWebSocketConnection(), and registerWebSocketUpgradeVerifier().
std::unique_ptr<QWebSocket> QAbstractHttpServer::nextPendingWebSocketConnection()
Returns the next pending connection as a connected QWebSocket object. nullptr
is returned if this function is called when there are no pending connections.
Note: The returned QWebSocket object cannot be used from another thread.
See also newWebSocketConnection(), hasPendingWebSocketConnections(), and registerWebSocketUpgradeVerifier().
template <typename Functor, QAbstractHttpServer::if_compatible_callable<Functor> = true> void QAbstractHttpServer::registerWebSocketUpgradeVerifier(Functor &&func)
Register a callback function func that verifies incoming WebSocket upgrades. Upgrade attempts succeed if at least one of the registered callback functions returns Accept
and a handler returning Deny
has not been executed before it. If no handlers are registered or all return PassToNext
, missingHandler() is called. The callback functions are executed in the order they are registered. The callbacks cannot call registerWebSocketUpgradeVerifier().
Note: The WebSocket upgrades fail if no callbacks has been registered.
Note: This overload participates in overload resolution only if the callback function takes a const
QHttpServerRequest & as an argument and returns a QHttpServerWebSocketUpgradeResponse.
server.registerWebSocketUpgradeVerifier( [](const QHttpServerRequest &request) { if (request.url().path() == "/allowed"_L1) return QHttpServerWebSocketUpgradeResponse::accept(); else return QHttpServerWebSocketUpgradeResponse::passToNext(); });
See also QHttpServerRequest, QHttpServerWebSocketUpgradeResponse, hasPendingWebSocketConnections(), nextPendingWebSocketConnection(), newWebSocketConnection(), and missingHandler().
QList<quint16> QAbstractHttpServer::serverPorts() const
Returns the list of ports this instance of QAbstractHttpServer is listening to.
This function has the same guarantee as QObject::children, the latest server added is the last entry in the vector.
See also servers().
QList<QTcpServer *> QAbstractHttpServer::servers() const
Returns list of child TCP servers of this HTTP server.
See also serverPorts().
[since 6.8]
void QAbstractHttpServer::setHttp2Configuration(const QHttp2Configuration &configuration)
Sets server's HTTP/2 configuration parameters.
The next HTTP/2 connection will use the given configuration.
This function was introduced in Qt 6.8.
See also http2Configuration().
void QAbstractHttpServer::sslSetup(const QSslConfiguration &sslConfiguration)
Turns the server into an HTTPS server.
The next listen() call will use the given sslConfiguration.
void QAbstractHttpServer::sslSetup(const QSslCertificate &certificate, const QSslKey &privateKey, QSsl::SslProtocol protocol = QSsl::SecureProtocols)
Turns the server into an HTTPS server.
The next listen() call will use the given certificate, privateKey, and protocol.
© 2024 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.