QHttpServerRouterRule Class | Qt HTTP Server | Qt 6.12.0
Description: The QHttpServerRouterRule is the base class for QHttpServerRouter rules.
Keywords: class

- Qt 6.12
- Qt HTTP Server
- C++ Classes
- QHttpServerRouterRule
- Qt 6.12.0 Reference Documentation

# 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

- List of all members, including inherited members

## 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`.