- Qt 6.8
- Qt HTTP Server
- C++ Classes
- QtHttpServer (Technical Preview)
- QHttpServerRouterRule
- Qt 6.8.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
Status: | Technical Preview

- 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 expresses the connection between a request path, an HTTP request method, and the respective handler callback. The QHttpServerRouter is a collection of such rules from which the handlers are called if the path and request method match the request. The handler callback must provide the response to the request.

### Path and Patterns

Every QHttpServerRouterRule contains a path or path pattern which defines the paths for which it can provide a response through its handler. The path can contain placeholders that are forwarded to the rule's handler. The following examples of path patterns are shown with the QHttpServer::route convenience method, but can also be provided to 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 creates a rule that forwards all requests with "/user" to the provided hanlder, which in this case is a simple lambda (Note that the handler syntax would look different when using QHttpServerRouterRule directly, see below).

The path pattern can further contain a trailing "/" to create a rule that addresses a collection of paths with arguments after the trailing "/". The argument will be forwarded to the Rule as a QRegularExpressionMatch. Using the QHttpServer::route convenience method the argument is directly forwarded to the lambda:

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

This would match the request urls "/user/1", "/user/2" and so on.

The argument can be posititioned freely with the path pattern by using the "<arg>" placeholder. This keyword further allows multiple placeholder.

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

This would, for example, match the request url "/user/1/history/2". All types which are registered in QHttpServerRouter::converters() can be used in the callback and the respective placeholder.

### Request Method

Request method is simply one of QHttpServerRequest::Method. If no method is provided to any overload of the Rule construction, the rule will match any request method.

### Handler Signature

The handler is a callback with the signature

     void (*)(const QRegularExpressionMatch &, const QHttpServerRequest &, QHttpServerResponder &);

The handler callback receives any matched placeholders as its first argument. The second argument contains details about the request and the response has to be written on the last argument by the handler.

The following code example shows how new rules with the respective handler can be created and added to a 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);
             // call viewHandler
             boundViewHandler();
         });

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

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

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

Note: Regular expressions in the path pattern are not supported, but can be registered (to match a use of "<arg>" to a specific type) using QHttpServerRouter::addConverter().

## Member Function Documentation

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

Constructs a rule for pathPattern, methods and connects it to receiver and slot. The slot can also be a function pointer, non-mutable lambda, or any other copiable callable with const call operator. In that case the receiver will be a context object. The handler will be valid until the receiver object is destroyed.

The rule accepts any combinations of available HTTP methods.

See also QHttpServerRequest::Methods.

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

This is an overloaded function.

Constructs a rule for pathPattern, QHttpServerRequest::Method::AnyKnown and connects it to receiver and slot. The slot can also be a function pointer, non-mutable lambda, or any other copiable callable with const call operator. In that case the receiver will be a context object. The handler will be valid until the receiver object is destroyed.

### `[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)

Supplies the receiver and slot with arguments derived from a URL. Returns the bound function that accepts whatever remaining arguments the handler may take, supplying them to the slot after the URL-derived values. Each match of the regex applied to the URL (as a string) is converted to the type of the handler's parameter at its position, so that 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

Returns the context object of this rule. This is the receiver that has to handle the request.

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

Executes this rule for the given request.

This function is called by QHttpServerRouter when it receives a new request. If the given request matches this rule, this function handles the request by delivering a response to the given responder, then returns `true`. Otherwise, it returns `false`.

### `[protected]` bool QHttpServerRouterRule::hasValidMethods() const

Returns `true` if the methods is valid

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

Determines whether a given request matches this rule.

This virtual function is called by exec() to check if request matches this rule. If a match is found, it is stored in the object pointed to by match (which must not be `nullptr`) and this function returns `true`. Otherwise, it returns `false`.