- Qt 6.6
- Qt HTTP Server
- C++ Classes
- QtHttpServer (Technical Preview)
- QHttpServerRouter
- Qt 6.6.0 Reference Documentation

# QHttpServerRouter Class

Provides functions to bind a URL to a `ViewHandler`. More...

Header: | #include <QHttpServerRouter>
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

| QHttpServerRouter()
| ~QHttpServerRouter()
bool | addConverter(QAnyStringView regexp)
void | addConverter(QMetaType metaType, QAnyStringView regexp)
bool | addRule(std::unique_ptr<QHttpServerRouterRule> rule)
typename ViewTraits::BindableType | bindCaptured(ViewHandler &&handler, const QRegularExpressionMatch &match) const
void | clearConverters()
const QHash<QMetaType, QString> & | converters() const
bool | handleRequest(const QHttpServerRequest &request, QHttpServerResponder &responder) const
void | removeConverter(QMetaType metaType)

## Detailed Description

You can register `ViewHandler` as a callback for requests to a specific URL. Variable parts in the route can be specified by the arguments in ViewHandler.

Note: This is a low-level routing API for an HTTP server.

See the following example:

     auto pageView = [] (const quint64 page) {
         qDebug() << "page" << page;
     };
     using ViewHandler = decltype(pageView);

     QHttpServerRouter router;

     // register callback pageView on request "/page/<number>"
     // for example: "/page/10", "/page/15"
     router.addRoute<ViewHandler>(
         new QHttpServerRouterRule("/page/", [=] (QRegularExpressionMatch &match,
                                                  const QHttpServerRequest &,
                                                  QHttpServerResponder &&) {
         auto boundView = router.bindCaptured(pageView, match);

         // it calls pageView
         boundView();
     }));

## Member Function Documentation

### QHttpServerRouter::QHttpServerRouter()

Creates a QHttpServerRouter object with default converters.

See also converters().

### `[noexcept]` QHttpServerRouter::~QHttpServerRouter()

Destroys a QHttpServerRouter.

### template <typename Type> bool QHttpServerRouter::addConverter(QAnyStringView regexp)

Adds a new converter for type Type matching regular expression regexp, and returns `true` if this was successful, otherwise returns `false`.

Automatically try to register an implicit converter from QString to Type. If there is already a converter of type Type, that converter's regexp is replaced with regexp.

     struct CustomArg {
         int data = 10;

         CustomArg() {} ;
         CustomArg(const QString &urlArg) : data(urlArg.toInt()) {}
     };
     Q_DECLARE_METATYPE(CustomArg);

     QHttpServerRouter router;
     router.addConverter<CustomArg>(u"[+-]?\\d+"));

     auto pageView = [] (const CustomArg &customArg) {
         qDebug("data: %d", customArg.data);
     };
     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:
         router.bindCaptured(pageView, match)();
     });

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

### void QHttpServerRouter::addConverter(QMetaType metaType, QAnyStringView regexp)

Adds a new converter for type metaType matching regular expression regexp.

If there is already a converter of type metaType, that converter's regexp is replaced with regexp.

### template <typename ViewHandler, typename ViewTraits> bool QHttpServerRouter::addRule(std::unique_ptr<QHttpServerRouterRule> rule)

Adds a new rule and returns `true` if this was successful.

Inside addRule, we determine ViewHandler arguments and generate a list of their QMetaType::Type ids. Then we parse the URL and replace each `<arg>` with a regexp for its type from the list.

     QHttpServerRouter router;

     using ViewHandler = decltype([] (const QString &page, const quint32 num) { });

     auto rule = std::make_unique<QHttpServerRouterRule>(
         "/<arg>/<arg>/log",
         [] (QRegularExpressionMatch &match,
             const QHttpServerRequest &request,
             QHttpServerResponder &&responder) {
     });

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

### template <typename ViewHandler, typename ViewTraits> typename ViewTraits::BindableType QHttpServerRouter::bindCaptured(ViewHandler &&handler, const QRegularExpressionMatch &match) const

Supplies the handler with arguments derived from a URL. Returns the bound function that accepts whatever remaining arguments the handler may take, supplying them to the handler 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:
         router.bindCaptured(pageView, match)();
     });

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

### void QHttpServerRouter::clearConverters()

Removes all converters.

Note: clearConverters() does not set up default converters.

See also converters().

### const QHash<QMetaType, QString> &QHttpServerRouter::converters() const

Returns a map of converter type and regexp.

The following converters are available by default:

Constant | Description
--- | ---
`QMetaType::Int` |
`QMetaType::Long` |
`QMetaType::LongLong` |
`QMetaType::Short` |
`QMetaType::UInt` |
`QMetaType::ULong` |
`QMetaType::ULongLong` |
`QMetaType::UShort` |
`QMetaType::Double` |
`QMetaType::Float` |
`QMetaType::QString` |
`QMetaType::QByteArray` |
`QMetaType::QUrl` |
`QMetaType::Void` | An empty converter.

### bool QHttpServerRouter::handleRequest(const QHttpServerRequest &request, QHttpServerResponder &responder) const

Handles each new request for the HTTP server using responder.

Iterates through the list of rules to find the first that matches, then executes this rule, returning `true`. Returns `false` if no rule matches the request.

### void QHttpServerRouter::removeConverter(QMetaType metaType)

Removes the converter for type metaType.