QHttpServer Class

QHttpServer est une API simplifiée pour QAbstractHttpServer et QHttpServerRouter. Plus...

En-tête : #include <QHttpServer>
CMake : find_package(Qt6 REQUIRED COMPONENTS HttpServer)
target_link_libraries(mytarget PRIVATE Qt6::HttpServer)
qmake : QT += httpserver
Depuis : Qt 6.4
Hérite : QAbstractHttpServer

Fonctions publiques

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)

Description détaillée

QHttpServer est utilisé pour créer un serveur HTTP simple en enregistrant une série de gestionnaires de requêtes.

La fonction route peut être utilisée pour ajouter commodément des règles au serveur QHttpServerRouter. Pour enregistrer un gestionnaire qui est appelé après chaque demande afin de poursuivre le traitement de la réponse, utilisez addAfterRequestHandler, mais ce mécanisme ne fonctionne que pour les routes renvoyant QHttpServerResponse ou QFuture<QHttpServerResponse>. Pour enregistrer un gestionnaire pour toutes les demandes non traitées, utilisez setMissingHandler.

Exemple minimal :

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

Documentation des fonctions membres

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

Crée une instance de QHttpServer avec le parent parent.

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

Détruit un QHttpServer.

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

Enregistrez un context et un slot qui seront appelés après le traitement de chaque demande.

Le slot doit implémenter la signature void (*)(const QHttpServerRequest &, QHttpServerResponse &).

Le slot peut également être un pointeur de fonction, un lambda non modifiable ou tout autre objet copiable avec l'opérateur const call. Dans ce cas, context sera un objet contextuel et le gestionnaire sera valide jusqu'à ce que l'objet contextuel soit détruit.

Exemple :

server.addAfterRequestHandler(&server, [] (const QHttpServerRequest &req, QHttpServerResponse &resp) {
    auto h = resp.headers();
    h.append(QHttpHeaders::WellKnownHeader::Cookie, "PollyWants=Cracker");
    resp.setHeaders(std::move(h));
}

Remarque : ces gestionnaires ne seront appelés que pour les demandes traitées par des gestionnaires de routes qui renvoient soit QHttpServerResponse, soit QFuture<QHttpServerResponse>, et qui ne prennent donc pas d'argument QHttpServerResponder.

void QHttpServer::clearMissingHandler()

Réinitialise le gestionnaire à celui par défaut qui produit des réponses avec le statut 404 Not Found.

Voir aussi setMissingHandler.

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

Cette méthode ajoute un nouveau routage Rule au membre QHttpServerRouter du serveur. Le paramètre de modèle Rule peut être n'importe quelle classe dérivée de QHttpServerRouterRule. Les paramètres sont transmis à Rule. Le serveur compare les demandes HTTP entrantes avec les règles enregistrées basées sur le chemin d'accès à l'URL et la méthode HTTP, et la première correspondance des deux est exécutée.

Le paramètre pathPattern est comparé à path() de l'URL de la requête entrante. Le paramètre method est comparé à la méthode HTTP de la requête entrante. Le paramètre slot est le gestionnaire de la demande. Il peut s'agir d'un pointeur de fonction membre de context, d'un pointeur de fonction, d'un lambda non modifiable ou de tout élément copiable avec un opérateur d'appel const. Si context est fourni, la règle reste valable tant que le contexte existe. Le context doit partager la même affinité thread que le QHttpServer.

slot prend comme arguments un nombre quelconque d'arguments analysés, qui sont extraits de pathPattern en faisant correspondre les espaces réservés de "<arg>", suivis d'un QHttpServerRequest et d'un QHttpServerResponder facultatifs. Ces deux classes sont appelées "specials".

Le slot peut renvoyer un QHttpServerResponse ou un type convertible :

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

Alternativement, si un argument optionnel QHttpServerResponder& est fourni, la réponse doit être écrite en l'utilisant et la fonction doit renvoyer void.

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

L'objet QHttpServerRequest peut être utilisé pour accéder au corps de la requête :

server.route("/test3", QHttpServerRequest::Method::Post, this,
             [] (const QHttpServerRequest &request, QHttpServerResponder &responder) {
                 responder.write(request.body(), "text/plain"_ba);
             });

Tout caractère générique ( "<arg>" ) dans pathPattern est automatiquement converti pour correspondre aux types d'arguments du gestionnaire. Les types pris en charge sont les suivants : entiers, nombres à virgule flottante, QString, QByteArray et QUrl. La classe QUrl peut être utilisée comme dernier paramètre pour gérer la fin de pathPattern, et en la divisant, un nombre arbitraire d'arguments peut être pris en charge. Des convertisseurs personnalisés peuvent être ajoutés en utilisant QHttpServerRouter::addConverter().

Chaque type enregistré est associé à une expression rationnelle qui est utilisée pour faire correspondre et convertir les caractères génériques dans pathPattern. Ces expressions rationnelles sont combinées pour construire un analyseur syntaxique pour l'ensemble du chemin. L'analyseur résultant est ensuite utilisé pour vérifier si le chemin correspond au motif. Si l'analyse réussit, la fonction correspondante est appelée avec les paramètres convertis. En cas d'échec de l'analyse, le rappel enregistré suivant est tenté. Si l'analyse échoue pour tous les rappels, le gestionnaire manquant (missingHandler) est appelé.

Dans l'exemple ci-dessous, la valeur du chemin de requête remplaçant "<arg>" est convertie en int car le lambda attend un paramètre int. Lorsqu'une requête HTTP correspond à l'itinéraire, la valeur convertie est transmise à l'argument page de la lambda :

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

Cette fonction renvoie, en cas de succès, un pointeur sur la règle nouvellement créée, sinon un nullptr. Le pointeur peut être utilisé pour définir des paramètres sur n'importe quelle classe QHttpServerRouter personnalisée :

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

Remarque : cette fonction, route(), ne doit pas être appelée à partir de slot, de sorte qu'aucun gestionnaire de routes ne puisse enregistrer d'autres gestionnaires de routes.

Note : Si une demande a été traitée par un slot acceptant QHttpServerResponder& comme argument, aucun des gestionnaires de demandes suivants (voir addAfterRequestHandler) ne sera appelé.

Par défaut, les demandes sont traitées de manière séquentielle dans le fil d'exécution de QHttpServer. Le gestionnaire de requêtes peut renvoyer QFuture<QHttpServerResponse> si un traitement simultané est souhaité :

server.route("/feature/<arg>", [] (int ms) {
    return QtConcurrent::run([ms] () {
        QThread::msleep(ms);
        return QHttpServerResponse("the future is coming");
    });
});

La lambda de QtConcurrent::run() est exécutée simultanément, mais toutes les communications réseau sont exécutées séquentiellement dans le thread auquel appartient QHttpServer une fois que QFuture a terminé. Sachez que tout objet QHttpServerRequest est transmis par référence au callback. Extrayez tout le contenu nécessaire avant que QtConcurrent::run() ne soit appelé.

L'argument spécial QHttpServerResponder& n'est disponible que pour les routes renvoyant void. Lors de l'utilisation d'un objet répondeur, la réponse est renvoyée en l'utilisant.

Voir aussi QHttpServerRouter::addRule et addAfterRequestHandler.

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

Surcharge de QHttpServer::route pour créer une règle pour pathPattern et QHttpServerRequest::Method::AnyKnown. Toutes les demandes sont transmises à handler, qui peut être un pointeur de fonction, un lambda non modifiable ou tout autre objet copiable avec l'opérateur const call. La règle sera valide jusqu'à ce que QHttpServer soit détruit.

Il s'agit d'une fonction surchargée.

template <typename Rule = QHttpServerRouterRule, typename Functor> Rule *QHttpServer::route(const QString &pathPattern, QHttpServerRequest::Methods method, Functor &&handler)

Surcharge de QHttpServer::route pour créer une règle pour pathPattern et method. Toutes les demandes sont transmises à handler, qui peut être un pointeur de fonction, un lambda non modifiable ou tout autre objet copiable avec l'opérateur const call. La règle sera valide jusqu'à ce que QHttpServer soit détruit.

Il s'agit d'une fonction surchargée.

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

Surcharge de QHttpServer::route pour créer une règle pour pathPattern et la méthode QHttpServerRequest::Method::AnyKnown. Toutes les demandes sont transmises à context et slot.

Il s'agit d'une fonction surchargée.

QHttpServerRouter *QHttpServer::router()

Renvoie un pointeur sur l'objet routeur.

const QHttpServerRouter *QHttpServer::router() const

Renvoie un pointeur sur l'objet routeur constant.

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

Définir un gestionnaire pour les demandes non traitées.

Toutes les demandes non gérées seront transmises à l'adresse context's slot.

Le slot doit implémenter la signature void (*)(const QHttpServerRequest &, QHttpServerResponder &). L'adresse slot peut également être un pointeur de fonction, un lambda non modifiable ou tout autre objet copiable avec l'opérateur const call. Dans ce cas, context sera un objet contextuel. Le gestionnaire sera valide jusqu'à ce que l'objet contextuel soit détruit.

Le gestionnaire par défaut répond avec le statut 404 Not Found.

Voir aussi clearMissingHandler.

© 2025 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.