PySide6.QtHttpServer.QHttpServerRouterRule

class QHttpServerRouterRule

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

Synopsis

Methods

Virtual methods

Note

This documentation may contain snippets that were automatically translated from C++ to Python. We always welcome contributions to the snippet translation. If you see an issue with the translation, you can also let us know by creating a ticket on https:/bugreports.qt.io/projects/PYSIDE

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 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 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 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 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 addConverter() to match "<arg>" to a specific type.

contextObject()
Return type:

QObject

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

exec(request, responder)
Parameters:
Return type:

bool

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.

hasValidMethods()
Return type:

bool

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

matches(request, match)
Parameters:
Return type:

bool

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.