QHttpServer Class

Documentación de las funciones miembro

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

Crea una instancia de QHttpServer con el padre parent.

[override virtual noexcept] QHttpServer::~QHttpServer()

Destruye un QHttpServer.

template <typename Functor> void QHttpServer::addAfterRequestHandler(const QObject *context, Functor &&slot)

Registre un context y un slot que se llamarán después de gestionar cada solicitud.

El slot tiene que implementar la firma void (*)(const QHttpServerRequest &, QHttpServerResponse &).

El slot también puede ser un puntero de función, un lambda no mutable o cualquier otro callable copiable con operador de llamada const. En ese caso, context será un objeto de contexto y el gestor será válido hasta que se destruya el 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));
}

void QHttpServer::clearMissingHandler()

Restablece el manejador al predeterminado que produce 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 un nuevo enrutamiento Rule al miembro QHttpServerRouter del servidor. El parámetro de la plantilla Rule puede ser cualquier clase derivada de QHttpServerRouterRule. Los parámetros se pasan a Rule. El servidor compara las peticiones HTTP entrantes con reglas registradas basadas en la ruta URL y el método HTTP, y se ejecuta la primera coincidencia de ambas.

El parámetro pathPattern se compara con el path() de la URL de la petición entrante. El parámetro method se compara con el método HTTP de la solicitud entrante. El parámetro slot es el gestor de peticiones. Puede ser un puntero a una función miembro de context, un puntero a una función, un lambda no mutable o cualquier invocable copiable con un operador de llamada const. Si se proporciona context, la regla seguirá siendo válida mientras exista el contexto. El context debe compartir la misma afinidad de hilo que QHttpServer.

El slot toma como argumentos cualquier número de argumentos analizados, que se extraen del pathPattern haciendo coincidir los marcadores de posición "<arg>", seguidos de un QHttpServerRequest opcional y un QHttpServerResponder opcional. Estas dos clases se denominan especiales.

El slot puede devolver un QHttpServerResponse o un tipo convertible:

QHttpServer server;
server.route("/test/", this, [] () { return ""; });

Alternativamente, si se proporciona un argumento opcional QHttpServerResponder, la respuesta debe escribirse usándolo y la función debe devolver void o QFuture<void>. El soporte de QFuture<void> se añadió en Qt 6.11. QHttpServerResponder no es copiable, y puede pasarse como referencia o referencia rvalue, excepto cuando se devuelve un QFuture<void>, en cuyo caso debe pasarse como referencia rvalue para evitar que salga de ámbito.

server.route("/test2", this,
             [] (QHttpServerResponder &&responder) {
                responder.write(QHttpServerResponder::StatusCode::Forbidden);
             });

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 petición. Puede pasarse como una referencia constante (sólo para las retrollamadas no concurrentes) o por valor, y puede utilizarse para acceder al cuerpo de la petición:

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 argumento del manejador. Los tipos soportados incluyen enteros, números de coma flotante, QString, QByteArray, y QUrl. La clase QUrl se puede utilizar como último parámetro para manejar el final de pathPattern, y dividiéndola se puede soportar un número arbitrario de argumentos. Pueden añadirse convertidores personalizados utilizando QHttpServerRouter::addConverter().

Cada tipo registrado tiene un regex asociado que se utiliza para hacer coincidir y convertir los marcadores de posición en pathPattern. Estos patrones regex se combinan para construir un analizador sintáctico para toda la ruta. El analizador sintáctico resultante se utiliza para verificar si la ruta coincide con el patrón. Si el análisis sintáctico tiene éxito, se llama a la función correspondiente con los parámetros convertidos. Si el análisis sintáctico falla, se intenta la siguiente llamada de retorno registrada. Si falla el análisis de todas las retrollamadas, se llama al missingHandler.

En el ejemplo siguiente, el valor de la ruta de solicitud que sustituye a "<arg>" se convierte en int porque la lambda espera un parámetro int. Cuando una petición HTTP coincide con la ruta, el valor convertido se pasa al argumento page de la lambda:

QHttpServer server;
server.route("/showpage/<arg>", this, [] (int page) { return getPage(page); });

Esta función devuelve, si tiene éxito, un puntero a la Regla recién creada, en caso contrario un nullptr. El puntero puede utilizarse para establecer parámetros en cualquier clase personalizada QHttpServerRouter:

auto rule = server.route<MyRule>("/test4", this, [] () {return "";});
rule->setParameter("test");

Por defecto, las peticiones se procesan secuencialmente dentro del hilo de QHttpServer. El gestor de peticiones 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 concurrentemente, pero toda la comunicación de red se ejecuta en el hilo al que pertenece QHttpServer.

Las rutas que devuelven futuros sólo se ejecutan de forma totalmente concurrente en una conexión HTTP/2. Las versiones anteriores de HTTP no permiten intercalar partes de diferentes respuestas: Las respuestas deben volver completas en el mismo orden en que llegan las peticiones. Por lo tanto, incluso si un gestor de rutas devuelve un <void> QFuture, la siguiente solicitud entrante en esa conexión HTTP/1 no se procesará hasta que se haya procesado la actual. Los manejadores de rutas en diferentes conexiones pueden ser ejecutados concurrentemente.

Hacer que un manejador de rutas realice su trabajo en una ejecución concurrente puede tener beneficios para todas las versiones de HTTP porque el hilo al que pertenece QHttpServer se verá liberado del trabajo que realiza la ejecución concurrente.

QHttpServerRequest es copiable, y debe ser capturado por valor cuando devuelve un futuro, porque las variables pasadas a slot pueden salir del ámbito antes de que el futuro termine.

server.route("/test4", QHttpServerRequest::Method::Post, this,
             [] (QHttpServerRequest request) {
                return QtConcurrent::run(pool, [request]() {
                    return QHttpServerResponse("text/plain"_ba, request.body());
                }
             });

Un slot que captura QHttpServerRequest o QHttpServerResponder por referencia al devolver un futuro provoca una aserción con una explicación de por qué está prohibido.

No todas las plataformas soportan mover QHttpServerResponder a una lambda mutable que se pasa a QConcurrent::run, así que la solución es mover QHttpServerResponder a una std::shared_ptr y copiarla.

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);
                    });
            });

Ver 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 peticiones se reenvían a handler, que puede ser un puntero de función, un lambda no mutable o cualquier otro callable copiable con operador de llamada const. La regla será válida hasta que se destruya QHttpServer.

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 peticiones se reenvían a handler, que puede ser un puntero de función, un lambda no mutable o cualquier otro callable copiable con operador de llamada const. La regla será válida hasta que se destruya QHttpServer.

template <typename Rule = QHttpServerRouterRule, typename Functor> Rule *QHttpServer::route(const QString &pathPattern, const QObject *context, Functor &&slot)

Sobrecarga de QHttpServer::route para crear una regla para pathPattern y el método QHttpServerRequest::Method::AnyKnown. Todas las peticiones se reenvían a context y slot.

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 gestor para las solicitudes no atendidas.

Todas las peticiones no gestionadas se reenviarán a context's slot.

El slot tiene que implementar la firma void (*)(const QHttpServerRequest &, QHttpServerResponder &). El slot también puede ser un puntero de función, un lambda no mutable, o cualquier otro callable copiable con operador de llamada const. En ese caso, context será un objeto de contexto. El manejador será válido hasta que el objeto de contexto sea destruido.

El manejador por defecto responde con el estado 404 Not Found.

Véase también clearMissingHandler.