QHttpServerRouterRule Class

The QHttpServerRouterRule is the base class for QHttpServerRouter rules. More...

Header: #include <QHttpServerRouterRule>
CMake: find_package(Qt6 REQUIRED COMPONENTS HttpServer)
target_link_libraries(mytarget PRIVATE Qt6::HttpServer)
qmake: QT += httpserver
Since: Qt 6.4

Public Functions

QHttpServerRouterRule(const QString &pathPattern, const QHttpServerRequest::Methods methods, const QObject *receiver, Functor &&slot)
QHttpServerRouterRule(const QString &pathPattern, const QObject *receiver, Functor &&slot)
virtual ~QHttpServerRouterRule()
const QObject *contextObject() const

Static Public Members

typename ViewTraits::BindableType bindCaptured(QObject *receiver, Functor &&slot, const QRegularExpressionMatch &match)

Protected Functions

bool exec(const QHttpServerRequest &request, QHttpServerResponder &responder) const
bool hasValidMethods() const
virtual bool matches(const QHttpServerRequest &request, QRegularExpressionMatch *match) const

Detailed Description

QHttpServerRouterRule defines the relationship between a request path, an HTTP method, and the corresponding handler callback. A QHttpServerRouter is a collection of these rules, executing the appropriate handler when a request matches both the path and method. The handler is responsible for generating the response.

Paths and Patterns

Each QHttpServerRouterRule includes a path or pattern that determines which requests it can handle. Paths may contain placeholders that are passed to the handler. The examples below illustrate path patterns using the QHttpServer::route() convenience method, though they can also be set using the QHttpServerRouterRule constructor.

In the simplest case the path is a string with a leading "/":

 QHttpServer server;
 server.route("/user", [] () { return "hello user"; } );

This path pattern defines a rule that directs all requests to "/user" to the specified handler, which in this case is a simple lambda function. (Note that when using QHttpServerRouterRule directly, the handler syntax differs—see below.)

A trailing "/" in the path pattern allows the rule to match additional paths with arguments after the "/". When using the QHttpServer::route() convenience method, the argument is automatically passed to the lambda function:

 server.route("/user/", [] ( qint64 id ) { return "hello user"; } );

This would match request paths such as "/user/1", "/user/2", and so on.

Capturing Arguments in the Path

You can place arguments anywhere in the path pattern using the "<arg>" placeholders, and multiple of them are supported in the path:

 server.route("/user/<arg>/history", [] (qint64 id){ return "hello user"; } );
 server.route("/user/<arg>/history/", [] (qint64 id, qint64 page){ return "hello user"; } );

For example, this would match a request like "/user/1/history/2". Any data type registered in QHttpServerRouter::converters() can be used in both the callback function and the corresponding placeholders in the path.

Request Method

The request method corresponds to one of the values in QHttpServerRequest::Method. If no method is specified when constructing a rule, it will match requests of any known method.

Handler Signature

A handler is a callback function with the following signature:

 void (*)(const QRegularExpressionMatch &, const QHttpServerRequest &, QHttpServerResponder &);
  • The first argument receives any matched capture groups from the path.
  • The second argument contains request details.
  • The third argument is used to send the response.

Adding Rules to QHttpServerRouter

The example below demonstrates how to create and register a new rule with a handler in QHttpServerRouter:

 template<typename ViewHandler>
 void route(const char *path, const QHttpServerRequest::Methods methods, ViewHandler &&viewHandler)
 {
     auto rule = std::make_unique<QHttpServerRouterRule>(
             path, methods, [this, viewHandler = std::forward<ViewHandler>(viewHandler)]
                                             (QRegularExpressionMatch &match,
                                              const QHttpServerRequest &request,
                                              QHttpServerResponder &responder) mutable {
         auto boundViewHandler = QHttpServerRouterRule::bindCaptured<ViewHandler>(
                 this, std::move(viewHandler), match);
         boundViewHandler(); // Execute the handler
     });

     // Add rule to the router
     router.addRule<ViewHandler>(std::move(rule));
 }

 // Valid:
 route("/user/", [] (qint64 id) { } );                            // Matches "/user/1", "/user/3", etc.
 route("/user/<arg>/history", [] (qint64 id) { } );               // Matches "/user/1/history", "/user/2/history"
 route("/user/<arg>/history/", [] (qint64 id, qint64 page) { } ); // Matches "/user/1/history/1", "/user/2/history/2"

Note: This is a low-level API. For higher-level alternatives, see QHttpServer.

Note: Regular expressions are not supported in path patterns, but you can use QHttpServerRouter::addConverter() to match "<arg>" to a specific type.

Member Function Documentation

template <typename Functor> QHttpServerRouterRule::QHttpServerRouterRule(const QString &pathPattern, const QHttpServerRequest::Methods methods, const QObject *receiver, Functor &&slot)

Creates a routing rule for pathPattern and methods, connecting it to the specified receiver and slot.

  • The slot can be a function pointer, non-mutable lambda, or any other copyable callable with const call operator.
  • If slot is callable, receiver acts as its context object.
  • The handler remains valid until the receiver is destroyed.

The rule can handle any combination of available HTTP methods.

See also QHttpServerRequest::Methods.

template <typename Functor> QHttpServerRouterRule::QHttpServerRouterRule(const QString &pathPattern, const QObject *receiver, Functor &&slot)

This overload constructs a routing rule for pathPattern and associates it with receiver and slot.

  • It defaults to QHttpServerRequest::Method::AnyKnown, meaning it will match any recognized HTTP method.
  • The slot can be a function pointer, non-mutable lambda, or any other copyable callable with const call operator.
  • If slot is callable, receiver acts as its context object.
  • The handler remains valid until the receiver is destroyed.

This is an overloaded function.

[virtual noexcept] QHttpServerRouterRule::~QHttpServerRouterRule()

Destroys a QHttpServerRouterRule.

[static] template <typename Functor, typename ViewTraits = QHttpServerRouterViewTraits<Functor>> typename ViewTraits::BindableType QHttpServerRouterRule::bindCaptured(QObject *receiver, Functor &&slot, const QRegularExpressionMatch &match)

Binds the given receiver and slot with arguments extracted from the URL. The function returns a bound callable that takes any remaining arguments required by the handler, supplying them to slot after the URL-derived values.

Each captured value from the URL (as a string) is converted to the corresponding parameter type in the handler based on its position, ensuring it can be passed as match.

 QHttpServerRouter router;

 auto pageView = [] (const QString &page, const quint32 num) {
     qDebug("page: %s, num: %d", qPrintable(page), num);
 };
 using ViewHandler = decltype(pageView);

 auto rule = std::make_unique<QHttpServerRouterRule>(
     "/<arg>/<arg>/log",
     [&router, &pageView] (QRegularExpressionMatch &match,
                           const QHttpServerRequest &request,
                           QHttpServerResponder &&responder) {
     // Bind and call viewHandler with match's captured string and quint32:
     QHttpServerRouterRule::bindCaptured(pageView, match)();
 });

 router.addRule<ViewHandler>(std::move(rule));

const QObject *QHttpServerRouterRule::contextObject() const

Retrieves the context object associated with this rule. This object serves as the receiver responsible for handling the request.

[protected] bool QHttpServerRouterRule::exec(const QHttpServerRequest &request, QHttpServerResponder &responder) const

Executes the rule. Processes the given request by checking if it matches this rule.

  • This function is called by QHttpServerRouter when a new request is received.
  • If the request matches the rule, it handles the request by sending a response through the provided responder and returns true.
  • If there is no match, it returns false.

[protected] bool QHttpServerRouterRule::hasValidMethods() const

Validates the Request Method. Returns true if the specified HTTP method is valid.

[virtual protected] bool QHttpServerRouterRule::matches(const QHttpServerRequest &request, QRegularExpressionMatch *match) const

Determines whether the provided request meets the conditions of this rule.

  • This virtual function is called by exec() to evaluate the request.
  • If the request matches, the details are stored in match (which must not be nullptr), and the function returns true.
  • Otherwise, it returns false.