QHttpServer Class

メンバー関数ドキュメント

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

QHttpServer のインスタンスを親parent で作成します。

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

QHttpServer を破壊する。

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

各リクエストが処理された後に呼び出されるcontext とslot を登録する。

slot はシグネチャvoid (*)(const QHttpServerRequest &, QHttpServerResponse &) を実装しなければならない。

slot は、関数ポインタ、ミュータブルでないラムダ、あるいはconst call演算子を持つ他のコピー可能な呼び出し可能なものであることもできる。その場合、context はコンテキストオブジェクトとなり、ハンドラはコンテキストオブジェクト が破棄されるまで有効である。

例

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

ハンドラを、ステータス404 Not Found のリプライを返すデフォルトのものにリセットする。

setMissingHandlerも参照のこと 。

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

このメソッドは、新しいルーティングRule をサーバーのQHttpServerRouter メンバーに追加する。Rule テンプレートパラメータはQHttpServerRouterRule から派生した任意のクラスにすることができます。 パラメータはRule に渡されます。 サーバは URL パスと HTTP メソッドに基づいて、登録されたルールと着信 HTTP リクエストをマッチさせ、 両者の最初のマッチが実行されます。

pathPattern パラメータは、送られてくるリクエストのURLのpath() と比較される。method パラメータは、受信リクエストのHTTPメソッドと比較される。slot パラメータはリクエストハンドラである。これは、context のメンバ関数ポインタ、関数ポインタ、ミュータブルでないラムダ、 またはconst呼び出し演算子を持つコピー可能な呼び出し可能である。context 、コンテキストが存在する限り、ルールは有効である。context は、QHttpServer と同じスレッド親和性を共有しなければならない。

slot は、"<arg>" プレースホルダにマッチすることでpathPattern から抽出される、任意の数の解析済み引数を引数として取り、その後にオプションのQHttpServerRequest とオプションのQHttpServerResponder が続く。これら2つのクラスはスペシャルと呼ばれる。

slot は、QHttpServerResponse または変換可能な型を返すことができます：

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

あるいは、オプションの引数QHttpServerResponder が提供された場合、レスポンスはそれを使って記述されなければならず、関数はvoid またはQFuture<void> を返さなければなりません。QFuture<void> のサポートは Qt 6.11 で追加されました。QFuture<void>を返す場合を除き、QHttpServerResponder はコピー可能ではなく、参照またはr値参照として渡すことができます。

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

さらに、QHttpServerRequest は最後の引数として、あるいは、QHttpServerResponder 引数がある場合は最後から2番目の引数として、リクエストの詳細情報を得る ために使用できる。これは、const参照(非同時コールバックの場合のみ)または値で渡すことができ、 リクエストのボディにアクセスするために使用できる：

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

pathPattern のプレースホルダー("<arg>" )は、ハンドラの引数の型に合うように自動的に変換されます。サポートされる型は整数、浮動小数点数、QString 、QByteArray 、QUrl である。QUrl クラスは、pathPattern の最後を処理する最後のパラメータとして使用することができ、これを分割することで任意の数の引数をサポートすることができる。カスタム・コンバータはQHttpServerRouter::addConverter() を使って追加できる。

登録された各タイプは、pathPattern のプレースホルダーにマッチし、変換するために使用される関連正規表現を持っています。これらの正規表現パターンは、パス全体のパーサーを構築するために組み合わされます。そして、得られたパーザーを使って、パスがパターンにマッチするかどうかが検証される。構文解析が成功した場合、変換されたパラメータで対応する関数が呼び出される。解析に失敗した場合、次に登録されたコールバックが試行される。すべてのコールバックで解析に失敗した場合、missingHandlerが呼び出される。

以下の例では、"<arg>" を置き換えるリクエストパスの値は、ラムダがint パラメータを想定しているため、int に変換されます。HTTPリクエストがルートにマッチすると、変換された値がラムダの引数page に渡される：

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

この関数は、成功すれば新しく作成されたRuleへのポインタを返し、そうでなければnullptr を返す。このポインタは、カスタムQHttpServerRouter クラスのパラメータを設定するために使用できる：

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

リクエストはデフォルトでQHttpServer のスレッド内で順次処理される。同時処理が必要な場合、リクエストハンドラはQFuture<QHttpServerResponse> を返すことができます：

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

QtConcurrent::run() のラムダは同時に実行されますが、すべてのネットワーク通信はQHttpServer が属するスレッドで実行されます。

futureを返すルートは、HTTP/2接続でのみ完全に同時実行されます。それ以前のバージョンの HTTP は、異なるレスポンスの一部をインターリーブすることをサポートしていません：レスポンスは、リクエストが来たのと同じ順番で完全に返ってこなければなりません。そのため、ルートハンドラがQFuture<void> を返したとしても、HTTP/1 接続で次に来るリクエストは、現在のリクエストが処理されるまで処理されません。しかし、異なるコネクション上のルートハンドラは同時に実行することができます。

ルートハンドラを並行実行で動作させることは、すべてのバージョンの HTTP にとって利点があります。QHttpServer が属するスレッドは、並行実行が行う作業から解放されるからです。

QHttpServerRequest なぜなら、slot に渡された変数は、未来が終了する前にスコープ外に出る可能性があるからです。

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

フューチャーを返すときにQHttpServerRequest またはQHttpServerResponder を参照キャプチャするslot は、なぜそれが禁止されるのかの説明とともにアサーションが発生します。

すべてのプラットフォームが、QHttpServerResponder を QConcurrent::run に渡されるミュータブルラムダに移動することをサポートしているわけではないので、QHttpServerResponder を std::shared_ptr に移動し、それをコピーすることで回避できます。

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

QHttpServerRouter::addRule およびaddAfterRequestHandlerも参照してください 。

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

pathPattern とQHttpServerRequest::Method::AnyKnown のルールを作成するためのQHttpServer::route のオーバーロード。すべてのリクエストは、handler に転送される。 は、関数ポインタ、ミュータブルでないラムダ、const call 演算子を持つコピー可能なその他の呼び出し可能なものである。このルールは、QHttpServer が破棄されるまで有効である。

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

pathPattern とmethod のルールを作成するためのQHttpServer::route のオーバーロード。すべてのリクエストは、handler に転送される。 は、関数ポインタ、ミュータブルでないラムダ、const call 演算子を持つコピー可能なその他の呼び出し可能なものである。このルールは、QHttpServer が破棄されるまで有効である。

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

pathPattern とメソッドQHttpServerRequest::Method::AnyKnown のルールを作成するためのQHttpServer::route のオーバーロード。すべてのリクエストはcontext とslot に転送される。

QHttpServerRouter *QHttpServer::router()

ルーターオブジェクトへのポインターを返します。

const QHttpServerRouter *QHttpServer::router() const

定数ルーターオブジェクトへのポインターを返します。

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

処理されなかったリクエストのハンドラを設定する。

すべての処理されなかったリクエストはcontext のslot に転送(forward)される。

slot は署名void (*)(const QHttpServerRequest &, QHttpServerResponder &) を実装しなければならない。slot は、関数ポインタ、ミュータブルでないラムダ、あるいはconst call演算子を持つ他のコピー可能な呼び出し可能なものであることもできる。その場合、context はコンテキストオブジェクトとなる。ハンドラはコンテキストオブジェクトが破棄されるまで有効である。

デフォルトのハンドラは、ステータス404 Not Found で応答します。

clearMissingHandlerも参照してください 。