QGrpcHttp2Channel Class | Qt GRPC | Qt 6.12.0
Description: The QGrpcHttp2Channel class provides a HTTP/2 transport layer for gRPC communication.
Keywords: class

- Qt 6.12
- Qt GRPC
- C++ Classes
- QGrpcHttp2Channel
- Qt 6.12.0 Reference Documentation

# QGrpcHttp2Channel Class

The QGrpcHttp2Channel class provides a HTTP/2 transport layer for gRPC™ communication. More...

Header: | `#include <QGrpcHttp2Channel>`
CMake: | `find_package(Qt6 REQUIRED COMPONENTS Grpc)` `target_link_libraries(mytarget PRIVATE Qt6::Grpc)`
Since: | Qt 6.5
In QML: | GrpcHttp2Channel
Inherits: | QAbstractGrpcChannel

- List of all members, including inherited members

## Public Functions

| QGrpcHttp2Channel(const QUrl &hostUri)
| QGrpcHttp2Channel(const QUrl &hostUri, const QGrpcChannelOptions &options)
virtual | ~QGrpcHttp2Channel() override
QUrl | hostUri() const

## Detailed Description

The QGrpcHttp2Channel class implements QAbstractGrpcChannel, enabling gRPC™ communication carried over HTTP/2 framing.

HTTP/2 introduces several advantages over its predecessor, HTTP/1.1, making QGrpcHttp2Channel well-suited for high-performance, real-time applications that require efficient communication, without sacrificing security or reliability, by using multiplexed TCP connections.

The channel can be customized with SSL support, a custom serializationFormat, or other options by constructing it with a QGrpcChannelOptions containing the required customizations.

Note: QGrpcChannelOptions::filterServerMetadata is enabled by default.

#### Transportation scheme

The QGrpcHttp2Channel implementation prefers different transportation methods based on the provided `hostUri`, scheme and options. The following criteria applies:

Scheme | Description | Default Port | Requirements | Example
--- | --- | --- | --- | ---
`http` | Unencrypted HTTP/2 over TCP | 80 | None | `http://localhost`
`https` | TLS-encrypted HTTP/2 over TCP | 443 | QSslSocket support AND (scheme OR sslConfiguration) | `https://localhost`
`unix` | Unix domain socket in filesystem path | ✗ | QLocalSocket support AND scheme | `unix:///tmp/grpc.socket`
`unix-abstract` | Unix domain socket in abstract namespace | ✗ | QLocalSocket support AND AbstractNamespace support AND scheme | `unix-abstract:app_grpc_channel`

#### Content-Type

The content-type in gRPC over HTTP/2 determines the message serialization format. It must start with `application/grpc` and can include a suffix. The format follows this scheme:

     "content-type": "application/grpc" [("+proto" / "+json" / {custom})]

For example:

- `application/grpc+proto` specifies Protobuf encoding.
- `application/grpc+json` specifies JSON encoding.

The serialization format can be configured either by specifying the `content-type` inside the metadata or by setting the serializationFormat directly. By default, the `application/grpc` content-type is used.

To configure QGrpcHttp2Channel with the JSON serialization format using `content-type` metadata:

     auto jsonChannel = std::make_shared<QGrpcHttp2Channel>(
         QUrl("http://localhost:50051"_L1),
         QGrpcChannelOptions().setMetadata({
             { "content-type"_ba, "application/grpc+json"_ba },
         })
     );

For a custom serializer and `content-type`, you can directly set the serialization format:

     class DummySerializer : public QAbstractProtobufSerializer
     {
         ...
     };
     QGrpcSerializationFormat dummyFormat("dummy", std::make_shared<DummySerializer>());

     auto dummyChannel = std::make_shared<QGrpcHttp2Channel>(
         QUrl("http://localhost:50051"_L1),
         QGrpcChannelOptions().setSerializationFormat(dummyFormat)
     );

This uses `DummySerializer` for encoding and decoding messages with the `dummy` suffix. For HTTP/2 transportation this results in the `application/grpc+dummy` content-type.

Note: Custom serializers require server support for the specified format.

#### Reserved metadata keys

Metadata is transmitted as HTTP/2 headers: keys are case-insensitive ASCII strings, values may be ASCII strings or binary data. The following keys are reserved by HTTP/2 or the gRPC protocol and are dropped from user metadata when the request is built:

- HTTP/2 pseudo-headers (any key starting with `:`).
- Any key with the `grpc-` or `qtgrpc-` prefix.
- `te`, `content-type`, `user-agent`.

A user-provided `content-type` is still consulted at channel construction for serializer auto-detection (see Content-Type); it is not, however, forwarded as a Custom-Metadata entry.

For more information on HTTP/2 headers, see RFC 7540, Section 8.1.2.

See also QAbstractGrpcChannel, QGrpcChannelOptions, and QGrpcSerializationFormat.

## Member Function Documentation

### `[explicit]` QGrpcHttp2Channel::QGrpcHttp2Channel(const QUrl &hostUri)

Constructs QGrpcHttp2Channel with hostUri. Please see the Transportation scheme section for more information.

### `[explicit]` QGrpcHttp2Channel::QGrpcHttp2Channel(const QUrl &hostUri, const QGrpcChannelOptions &options)

Constructs QGrpcHttp2Channel with hostUri and options. Please see the Transportation scheme section for more information.

### `[override virtual noexcept]` QGrpcHttp2Channel::~QGrpcHttp2Channel()

Destroys the QGrpcHttp2Channel object.

### QUrl QGrpcHttp2Channel::hostUri() const

Returns the host URI for this channel.

The URI is normalized according to the Transportation scheme: the scheme may be adjusted and a default port may be filled in. Passing the returned URI back to QGrpcHttp2Channel will select the same transport configuration.