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 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 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 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 converters() can be used in the callback and the respective placeholder.

Request Method

Request method is simply one of 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 addConverter() .

contextObject()
Return type:

QObject

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

exec(request, responder)
Parameters:
Return type:

bool

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.

hasValidMethods()
Return type:

bool

Returns true if the methods is valid

matches(request, match)
Parameters:
Return type:

bool

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 None) and this function returns true. Otherwise, it returns false.