QHttpServer Class

Documentation sur les fonctions des membres

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

Crée une instance de QHttpServer dont le parent est parent.

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

Supprime un objet de type « QHttpServer ».

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

Enregistrez une méthode « context » et une méthode « slot » qui seront appelées une fois chaque requête traitée.

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

slot peut également être un pointeur de fonction, un lambda non modifiable ou tout autre objet appelable copiable doté de l'opérateur const call. Dans ce cas, context sera un objet de contexte et le gestionnaire restera valide jusqu’à la destruction de cet objet de contexte.

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

void QHttpServer::clearMissingHandler()

Rétablit le gestionnaire par défaut, qui génère 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 une nouvelle Rule de routage 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 requêtes HTTP entrantes aux règles enregistrées en fonction du chemin d'URL et de la méthode HTTP, et la première correspondance entre les deux est exécutée.

Le paramètre pathPattern est comparé à la méthode 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 correspond au gestionnaire de requête. Il peut s’agir d’un pointeur vers une fonction membre de context, d’un pointeur de fonction, d’un lambda non modifiable ou de tout objet appelable copiable doté d’un opérateur d’appel const. Si context est fourni, la règle reste valide tant que le contexte existe. Le paramètre context doit partager la même affinité de thread que QHttpServer.

La fonction slot prend en arguments un nombre quelconque d’arguments analysés, extraits de la fonction pathPattern en faisant correspondre les marqueurs de place "<arg>", suivis d’un QHttpServerRequest facultatif et d’un QHttpServerResponder facultatif. Ces deux classes sont appelées « specials ».

La fonction ` slot ` peut renvoyer un ` QHttpServerResponse ` ou un type convertible :

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

Sinon, si un argument facultatif de type ` QHttpServerResponder ` est fourni, la réponse doit être écrite en l’utilisant et la fonction doit renvoyer un ` void ` ou un ` QFuture<void>`. QFuture La prise en charge de <VOID> a été ajoutée dans Qt 6.11. L’ QHttpServerResponder n’est pas copiable et peut être passé en référence ou en référence rvalue, sauf lorsqu’il renvoie un QFuture<VOID>, auquel cas il doit être passé en référence rvalue pour éviter qu’il ne sorte de la portée.

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

De plus, ` QHttpServerRequest ` peut être utilisé comme dernier argument ou, s’il existe un argument ` QHttpServerResponder `, comme avant-dernier argument pour obtenir des informations détaillées sur la requête. Il peut être transmis sous forme de référence `const` (uniquement pour les callbacks non concurrents) ou par valeur, et permet d’accéder au corps de la requête :

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

Tout espace réservé ( "<arg>" ) dans pathPattern est automatiquement converti pour correspondre aux types d’arguments du gestionnaire. Les types pris en charge incluent les entiers, les nombres à virgule flottante, QString, QByteArray et QUrl. La classe QUrl peut être utilisée comme dernier paramètre pour gérer la fin de l’ pathPattern, et en la fractionnant, un nombre arbitraire d’arguments peut être pris en charge. Des convertisseurs personnalisés peuvent être ajoutés à l’aide de QHttpServerRouter::addConverter().

Chaque type enregistré est associé à une expression régulière utilisée pour faire correspondre et convertir les espaces réservés dans l’ pathPattern. Ces motifs d’expressions régulières sont combinés pour construire un analyseur syntaxique couvrant l’intégralité du chemin. L’analyseur ainsi obtenu est ensuite utilisé pour vérifier si le chemin correspond au motif. Si l’analyse aboutit, la fonction correspondante est appelée avec les paramètres convertis. Si l’analyse échoue, on tente d’utiliser la fonction de rappel enregistrée suivante. Si l’analyse échoue pour toutes les fonctions de rappel, la fonction `missingHandler` est appelée.

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

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

Cette fonction renvoie, en cas de succès, un pointeur vers 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");

Par défaut, les requêtes sont traitées de manière séquentielle dans le thread de l’ QHttpServer. Le gestionnaire de requêtes peut renvoyer ` QFuture<QHttpServerResponse> ` si un traitement concurrent est souhaité :

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

Le lambda de QtConcurrent::run() est exécuté en parallèle, mais toutes les communications réseau s’effectuent dans le thread auquel appartient l’ QHttpServer.

Les routes renvoyant des futures ne sont exécutées de manière entièrement concurrente que sur une connexion HTTP/2. Les versions antérieures de HTTP ne prennent pas en charge l’entrelacement de parties de différentes réponses : les réponses doivent être renvoyées dans leur intégralité, dans le même ordre que celui dans lequel les requêtes sont reçues. Ainsi, même si un gestionnaire de route renvoie un ` QFuture<void>`, la requête suivante sur cette connexion HTTP/1 ne sera pas traitée tant que le traitement de la requête en cours n’est pas terminé. Les gestionnaires de route sur des connexions différentes peuvent toutefois être exécutés en parallèle.

Le fait de faire fonctionner un gestionnaire de route en exécution concurrente peut présenter des avantages pour toutes les versions de HTTP, car le thread auquel appartient ` QHttpServer ` sera déchargé du travail effectué par l’exécution concurrente.

QHttpServerRequest est copiable et doit être capturé par valeur lors du retour d’un futur, car les variables passées à ` slot ` peuvent sortir de leur portée avant que le futur ne soit terminé.

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

Un ` slot ` qui capture ` QHttpServerRequest ` ou ` QHttpServerResponder ` par référence lors du retour d’un `future` provoque une assertion expliquant pourquoi cela est interdit.

Toutes les plateformes ne prennent pas en charge le déplacement de ` QHttpServerResponder ` vers un lambda mutable transmis à `QConcurrent::run` ; la solution consiste donc à déplacer ` QHttpServerResponder ` vers un `std::shared_ptr` et à copier ce dernier.

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

Voir également QHttpServerRouter::addRule et addAfterRequestHandler.

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

Surcharge de la fonction ` QHttpServer::route ` pour créer une règle pour les adresses pathPattern et QHttpServerRequest::Method::AnyKnown. Toutes les requêtes sont redirigées vers ` handler`, qui peut être un pointeur de fonction, un lambda non modifiable ou tout autre objet appelable copiable disposant de l'opérateur `const call`. La règle restera valide jusqu'à la destruction de l'QHttpServer.

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

Surcharge de la fonction ` QHttpServer::route ` pour créer une règle pour pathPattern et method. Toutes les requêtes sont redirigées vers handler, qui peut être un pointeur de fonction, un lambda non modifiable ou tout autre objet appelable copiable disposant de l'opérateur `const call`. La règle restera valide jusqu'à la destruction de l'QHttpServer.

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

Surcharge de la méthode QHttpServer::route pour créer une règle pour pathPattern et la méthode QHttpServerRequest::Method::AnyKnown. Toutes les requêtes sont redirigées vers context et slot.

QHttpServerRouter *QHttpServer::router()

Renvoie un pointeur vers l'objet routeur.

const QHttpServerRouter *QHttpServer::router() const

Renvoie un pointeur vers l'objet routeur constant.

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

Définir un gestionnaire pour les requêtes non traitées.

Toutes les requêtes non gérées seront redirigées vers la méthode slot de l'context.

L'slot doit implémenter la signature void (*)(const QHttpServerRequest &, QHttpServerResponder &). L'slot peut également être un pointeur de fonction, un lambda non modifiable ou tout autre appelable copiable disposant d'un opérateur d'appel const. Dans ce cas, l'context sera un objet de contexte. Le gestionnaire restera valide jusqu'à la destruction de l'objet de contexte.

Le gestionnaire par défaut renvoie un statut 404 Not Found.

Voir également clearMissingHandler.