QHttpServer Class
QHttpServer es una API simplificada para QAbstractHttpServer y QHttpServerRouter. Más información...
| Encabezado: | #include <QHttpServer> |
| CMake: | find_package(Qt6 REQUIRED COMPONENTS HttpServer) target_link_libraries(mytarget PRIVATE Qt6::HttpServer) |
| qmake: | QT += httpserver |
| Desde: | Qt 6.4 |
| Heredado de: | QAbstractHttpServer |
Funciones públicas
| QHttpServer(QObject *parent = nullptr) | |
| virtual | ~QHttpServer() override |
| void | addAfterRequestHandler(const QObject *context, Functor &&slot) |
| void | clearMissingHandler() |
| Rule * | route(const QString &pathPattern, QHttpServerRequest::Methods method, const QObject *context, Functor &&slot) |
| Rule * | route(const QString &pathPattern, Functor &&handler) |
| Rule * | route(const QString &pathPattern, QHttpServerRequest::Methods method, Functor &&handler) |
| Rule * | route(const QString &pathPattern, const QObject *context, Functor &&slot) |
| QHttpServerRouter * | router() |
| const QHttpServerRouter * | router() const |
| void | setMissingHandler(const QObject *context, Functor &&slot) |
Descripción detallada
QHttpServer se utiliza para crear un servidor HTTP sencillo mediante el registro de una serie de controladores de solicitudes.
La función ` route ` permite añadir fácilmente reglas al archivo ` QHttpServerRouter` del servidor. Para registrar un controlador que se active tras cada solicitud con el fin de procesar posteriormente la respuesta, utilice ` addAfterRequestHandler`, aunque este mecanismo solo funciona para rutas que devuelvan ` QHttpServerResponse ` o ` QFuture` <QHttpServerResponse>. Para registrar un controlador para todas las solicitudes no gestionadas, utilice ` setMissingHandler`.
Ejemplo mínimo:
QHttpServer server;
server.route("/", [] () {
return "hello world";
});
auto tcpserver = new QTcpServer();
if (!tcpserver->listen()|| !server.bind(tcpserver)) {
delete tcpserver;
return-1;
}
qDebug() << "Listening on port" << tcpserver->serverPort();Documentación sobre funciones de miembro
[explicit] QHttpServer::QHttpServer(QObject *parent = nullptr)
Crea una instancia de QHttpServer con el servidor principal parent.
[override virtual noexcept] QHttpServer::~QHttpServer()
Destruye un « QHttpServer ».
template <typename Functor> void QHttpServer::addAfterRequestHandler(const QObject *context, Functor &&slot)
Registra un context y un slot para que se ejecuten una vez gestionada cada solicitud.
La función ` slot ` debe implementar la firma ` void (*)(const QHttpServerRequest &, QHttpServerResponse &)`.
slot también puede ser un puntero a función, una lambda no mutable o cualquier otro objeto invocable copiable con el operador const call. En ese caso, context será un objeto de contexto y el controlador será válido hasta que se destruya dicho objeto de contexto.
Ejemplo:
server.addAfterRequestHandler(&server, [] (const QHttpServerRequest &req, QHttpServerResponse &resp) {
auto h = resp.headers();
h.append(QHttpHeaders::WellKnownHeader::Cookie, "PollyWants=Cracker");
resp.setHeaders(std::move(h));
}Nota: Estos controladores solo se invocarán para las solicitudes procesadas por controladores de ruta que devuelvan QHttpServerResponse o QFuture<QHttpServerResponse>.
void QHttpServer::clearMissingHandler()
Restablece el controlador al predeterminado, que genera respuestas con el estado « 404 Not Found ».
Véase también setMissingHandler.
template <typename Rule = QHttpServerRouterRule, typename Functor> Rule *QHttpServer::route(const QString &pathPattern, QHttpServerRequest::Methods method, const QObject *context, Functor &&slot)
Este método añade una nueva regla de enrutamiento Rule al miembro QHttpServerRouter del servidor. El parámetro de plantilla Rule puede ser cualquier clase derivada de QHttpServerRouterRule. Los parámetros se pasan a Rule. El servidor compara las peticiones HTTP entrantes con las reglas registradas en función de la ruta de la URL y el método HTTP, y se ejecuta la primera coincidencia de ambos.
El parámetro ` pathPattern ` se compara con el ` path()` de la URL de la solicitud entrante. El parámetro ` method ` se compara con el método HTTP de la solicitud entrante. El parámetro slot es el gestor de la solicitud. Puede ser un puntero a una función miembro de context, un puntero a una función, una lambda no mutable o cualquier objeto invocable copiable con un operador de llamada const. Si se proporciona context, la regla sigue siendo válida mientras exista el contexto. El context debe compartir la misma afinidad de hilo que QHttpServer.
La función « slot » toma como argumentos cualquier número de argumentos analizados, que se extraen de la función « pathPattern » mediante la coincidencia de los marcadores de posición « "<arg>" », seguidos de un « QHttpServerRequest » opcional y un « QHttpServerResponder » opcional. Estas dos clases se denominan «specials».
La función « slot » puede devolver un « QHttpServerResponse » o un tipo convertible:
QHttpServer server;
server.route("/test/", this, [] () { return ""; });Nota: Esta función, route(), no debe invocarse desde slot, por lo que ningún gestor de rutas puede registrar otros gestores de rutas.
Alternativamente, si se proporciona un argumento opcional de ` QHttpServerResponder `, la respuesta debe escribirse utilizando dicho argumento y la función debe devolver ` void ` o ` QFuture<void>`. QFuture La compatibilidad con <VOID> se añadió en Qt 6.11. El ` QHttpServerResponder ` no es copiable y puede pasarse como referencia o como referencia de valor, excepto cuando se devuelve un ` QFuture` <VOID>, en cuyo caso debe pasarse como referencia de valor para evitar que salga del ámbito.
server.route("/test2", this,
[] (QHttpServerResponder &&responder) {
responder.write(QHttpServerResponder::StatusCode::Forbidden);
});Nota: Si una solicitud ha sido procesada por un slot que acepta QHttpServerResponder como argumento, no se llamará a ninguno de los manejadores posteriores a la solicitud (véase addAfterRequestHandler).
Además, QHttpServerRequest puede utilizarse como último argumento o, si hay un argumento QHttpServerResponder, como penúltimo argumento para obtener información detallada de la solicitud. Puede pasarse como referencia const (solo para callbacks no concurrentes) o por valor, y puede utilizarse para acceder al cuerpo de la solicitud:
server.route("/test3", QHttpServerRequest::Method::Post, this,
[] (QHttpServerRequest request, QHttpServerResponder &&responder) {
responder.write(request.body(), "text/plain"_ba);
});Cualquier marcador de posición ( "<arg>" ) en pathPattern se convierte automáticamente para que coincida con los tipos de argumentos del controlador. Los tipos admitidos incluyen enteros, números de coma flotante, QString, QByteArray y QUrl. La clase QUrl puede utilizarse como último parámetro para gestionar el final de pathPattern, y al dividirlo se puede admitir un número arbitrario de argumentos. Se pueden añadir convertidores personalizados utilizando QHttpServerRouter::addConverter().
Cada tipo registrado tiene asociada una expresión regular que se utiliza para buscar coincidencias y convertir los marcadores de posición en pathPattern. Estos patrones de expresiones regulares se combinan para construir un analizador para toda la ruta. A continuación, el analizador resultante se utiliza para verificar si la ruta coincide con el patrón. Si el análisis tiene éxito, se llama a la función correspondiente con los parámetros convertidos. Si el análisis falla, se intenta la siguiente función de devolución de llamada registrada. Si el análisis falla para todas las funciones de devolución de llamada, se llama a `missingHandler`.
En el ejemplo siguiente, el valor de la ruta de la solicitud que sustituye a "<arg>" se convierte en un int, ya que la función lambda espera un parámetro de tipo int. Cuando una solicitud HTTP coincide con la ruta, el valor convertido se pasa al argumento page de la función lambda:
QHttpServer server;
server.route("/showpage/<arg>", this, [] (int page) { return getPage(page); });Esta función devuelve, si se ejecuta correctamente, un puntero a la regla recién creada; en caso contrario, devuelve un ` nullptr`. El puntero se puede utilizar para establecer parámetros en cualquier clase personalizada de ` QHttpServerRouter `:
auto rule = server.route<MyRule>("/test4", this, [] () {return "";});
rule->setParameter("test");Por defecto, las solicitudes se procesan de forma secuencial dentro del hilo de la ` QHttpServer`. El gestor de solicitudes puede devolver ` QFuture<QHttpServerResponse> ` si se desea un procesamiento concurrente:
server.route("/feature/<arg>", [] (int ms) {
return QtConcurrent::run(pool, [ms] () {
QThread::msleep(ms);
return QHttpServerResponse("the future is coming");
});
});La lambda de QtConcurrent::run() se ejecuta de forma concurrente, pero toda la comunicación de red se lleva a cabo en el hilo al que pertenece QHttpServer.
Las rutas que devuelven futuros solo se ejecutan de forma totalmente concurrente en una conexión HTTP/2. Las versiones anteriores de HTTP no admiten el entrelazado de partes de diferentes respuestas: las respuestas deben devolverse completas y en el mismo orden en que llegan las solicitudes. Por lo tanto, incluso si un controlador de ruta devuelve un ` QFuture<void>`, la siguiente solicitud entrante en esa conexión HTTP/1 no se procesará hasta que haya finalizado el procesamiento de la actual. No obstante, los controladores de ruta en diferentes conexiones pueden ejecutarse de forma concurrente.
Hacer que un controlador de ruta realice su trabajo en una ejecución concurrente puede aportar ventajas para todas las versiones de HTTP, ya que el hilo al que pertenece QHttpServer quedará liberado del trabajo que realiza la ejecución concurrente.
QHttpServerRequest es copiable y debe capturarse por valor al devolver un «future», ya que las variables pasadas a ` slot ` pueden salir del ámbito antes de que finalice el «future».
server.route("/test4", QHttpServerRequest::Method::Post, this,
[] (QHttpServerRequest request) {
return QtConcurrent::run(pool, [request]() {
return QHttpServerResponse("text/plain"_ba, request.body());
}
});Un ` slot ` que capture ` QHttpServerRequest ` o ` QHttpServerResponder ` por referencia al devolver un «future» provoca una aserción con una explicación de por qué está prohibido.
No todas las plataformas admiten mover ` QHttpServerResponder ` a una lambda mutable que se pase a `QConcurrent::run`, por lo que la solución alternativa es mover ` QHttpServerResponder ` a un `std::shared_ptr` y copiarlo.
server.route("/concurrent-multipart-back/<arg>",
[](QString message, QHttpServerResponder &&responder) {
return QtConcurrent::run(pool,
[=, r = std::make_shared<QHttpServerResponder>(std::move(responder))] {
QByteArray ba = message.toUtf8();
r->writeBeginChunked("text/plain"_ba);
for (ushort i = 1; i < 8; ++i) {
r->writeChunk(ba);
}
r->writeEndChunked(ba);
});
});Véase también QHttpServerRouter::addRule y addAfterRequestHandler.
template <typename Rule = QHttpServerRouterRule, typename Functor> Rule *QHttpServer::route(const QString &pathPattern, Functor &&handler)
Sobrecarga de ` QHttpServer::route ` para crear una regla para ` pathPattern ` y ` QHttpServerRequest::Method::AnyKnown`. Todas las solicitudes se reenvían a ` handler`, que puede ser un puntero a función, una lambda no mutable o cualquier otro objeto invocable copiable con el operador de llamada `const`. La regla será válida hasta que se destruya ` QHttpServer `.
Se trata de una función sobrecargada.
template <typename Rule = QHttpServerRouterRule, typename Functor> Rule *QHttpServer::route(const QString &pathPattern, QHttpServerRequest::Methods method, Functor &&handler)
Sobrecarga de ` QHttpServer::route ` para crear una regla para ` pathPattern ` y ` method`. Todas las solicitudes se reenvían a ` handler`, que puede ser un puntero a función, una lambda no mutable o cualquier otro objeto invocable copiable con el operador `const call`. La regla será válida hasta que se destruya ` QHttpServer `.
Se trata de una función sobrecargada.
template <typename Rule = QHttpServerRouterRule, typename Functor> Rule *QHttpServer::route(const QString &pathPattern, const QObject *context, Functor &&slot)
Se ha sobrecargado la función QHttpServer::route para crear una regla para pathPattern y el método QHttpServerRequest::Method::AnyKnown. Todas las solicitudes se redirigen a context y slot.
Se trata de una función sobrecargada.
QHttpServerRouter *QHttpServer::router()
Devuelve un puntero al objeto enrutador.
const QHttpServerRouter *QHttpServer::router() const
Devuelve un puntero al objeto enrutador constante.
template <typename Functor> void QHttpServer::setMissingHandler(const QObject *context, Functor &&slot)
Establece un controlador para las solicitudes no gestionadas.
Todas las solicitudes no gestionadas se reenviarán a la función « slot » de « context ».
El ` slot ` debe implementar la firma ` void (*)(const QHttpServerRequest &, QHttpServerResponder &)`. El ` slot ` también puede ser un puntero a función, una lambda no mutable o cualquier otro objeto invocable copiable con el operador `const call`. En ese caso, el ` context ` será un objeto de contexto. El controlador será válido hasta que se destruya el objeto de contexto.
El controlador predeterminado responde con el estado 404 Not Found.
Véase también clearMissingHandler.
© 2026 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.