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

# QGrpcChannelOptions Class

The QGrpcChannelOptions class offers various options for fine-tuning a gRPC channel. More...

Header: | `#include <QGrpcChannelOptions>`
CMake: | `find_package(Qt6 REQUIRED COMPONENTS Grpc)` `target_link_libraries(mytarget PRIVATE Qt6::Grpc)`
Since: | Qt 6.6
In QML: | GrpcChannelOptions

- List of all members, including inherited members

QGrpcChannelOptions Comparisons

Category | Comparable Types
--- | ---
equality | QGrpcChannelOptions

## Public Functions

| QGrpcChannelOptions()
| QGrpcChannelOptions(const QGrpcChannelOptions &other)
| QGrpcChannelOptions(QGrpcChannelOptions &&other)
| ~QGrpcChannelOptions()
`(since 6.12)` QtGrpc::CompressionAlgorithms | acceptedCompressionAlgorithms() const
`(since 6.10)` QGrpcChannelOptions & | addMetadata(QByteArrayView key, QByteArrayView value)
std::optional<std::chrono::milliseconds> | deadlineTimeout() const
`(since 6.11)` std::optional<bool> | filterServerMetadata() const
`(since 6.12)` std::optional<quint64> | maximumReceiveMessageSize() const
`(until 6.13)` QHash<QByteArray, QByteArray> | metadata() &&
`(until 6.13)` const QHash<QByteArray, QByteArray> & | metadata() const &
`(since 6.10)` QMultiHash<QByteArray, QByteArray> | metadata(QtGrpc::MultiValue_t) &&
`(since 6.10)` const QMultiHash<QByteArray, QByteArray> & | metadata(QtGrpc::MultiValue_t) const &
`(since 6.12)` std::optional<QtGrpc::CompressionAlgorithm> | requestCompression() const
`(since 6.8)` QGrpcSerializationFormat | serializationFormat() const
`(since 6.12)` QGrpcChannelOptions & | setAcceptedCompressionAlgorithms(QtGrpc::CompressionAlgorithms algorithms)
QGrpcChannelOptions & | setDeadlineTimeout(std::chrono::milliseconds timeout)
`(since 6.11)` QGrpcChannelOptions & | setFilterServerMetadata(bool value)
`(since 6.12)` QGrpcChannelOptions & | setMaximumReceiveMessageSize(quint64 size)
`(until 6.13)` QGrpcChannelOptions & | setMetadata(QHash<QByteArray, QByteArray> &&metadata)
`(since 6.10)` QGrpcChannelOptions & | setMetadata(QMultiHash<QByteArray, QByteArray> &&metadata)
`(until 6.13)` QGrpcChannelOptions & | setMetadata(const QHash<QByteArray, QByteArray> &metadata)
`(since 6.10)` QGrpcChannelOptions & | setMetadata(const QMultiHash<QByteArray, QByteArray> &metadata)
`(since 6.10)` QGrpcChannelOptions & | setMetadata(std::initializer_list<std::pair<QByteArray, QByteArray>> list)
`(since 6.12)` QGrpcChannelOptions & | setRequestCompression(QtGrpc::CompressionAlgorithm algorithm)
`(since 6.8)` QGrpcChannelOptions & | setSerializationFormat(const QGrpcSerializationFormat &format)
QGrpcChannelOptions & | setSslConfiguration(const QSslConfiguration &sslConfiguration)
std::optional<QSslConfiguration> | sslConfiguration() const
`(since 6.8)` void | swap(QGrpcChannelOptions &other)
`(since 6.8)` | operator QVariant() const
QGrpcChannelOptions & | operator=(QGrpcChannelOptions &&other)
QGrpcChannelOptions & | operator=(const QGrpcChannelOptions &other)

## Static Public Members

`(since 6.12)` QtGrpc::CompressionAlgorithms | supportedCompressionAlgorithms()

## Related Non-Members

`(since 6.11)` bool | operator!=(const QGrpcChannelOptions &lhs, const QGrpcChannelOptions &rhs)
`(since 6.8)` QDebug | operator<<(QDebug debug, const QGrpcChannelOptions &chOpts)
`(since 6.11)` bool | operator==(const QGrpcChannelOptions &lhs, const QGrpcChannelOptions &rhs)

## Detailed Description

QGrpcChannelOptions lets you customize a gRPC™ channel. Some options apply to all remote procedure calls (RPCs) that operate on the associated channel, which is used to communicate with services.

Override options for specific RPCs with QGrpcCallOptions.

     QGrpcChannelOptions channelOpts;
     // Apply common metadata to every RPC
     channelOpts.setMetadata({
         { "header" , "value1" },
         { "header" , "value2" },
     });
     const auto &md = channelOpts.metadata(QtGrpc::MultiValue);
     qDebug() << "Channel Metadata: " << md;

     // Apply a 2-second deadline to every RPC
     channelOpts.setDeadlineTimeout(2s);
     qDebug() << "Channel timeout: " << channelOpts.deadlineTimeout();

     // Configure SSL/TLS configuration
     channelOpts.setSslConfiguration(QSslConfiguration());

Note: It is up to the channel's implementation to determine the specifics of these options.

## Member Function Documentation

### QGrpcChannelOptions::QGrpcChannelOptions()

Default-constructs an empty QGrpcChannelOptions.

### QGrpcChannelOptions::QGrpcChannelOptions(const QGrpcChannelOptions &other)

Copy-constructs a QGrpcChannelOptions from other.

### `[constexpr noexcept default]` QGrpcChannelOptions::QGrpcChannelOptions(QGrpcChannelOptions &&other)

Move-constructs a new QGrpcChannelOptions from other.

Note: The moved-from object other is placed in a partially-formed state, in which the only valid operations are destruction and assignment of a new value.

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

Destroys the QGrpcChannelOptions.

### `[since 6.12]` QtGrpc::CompressionAlgorithms QGrpcChannelOptions::acceptedCompressionAlgorithms() const

Returns the compression algorithms that this channel is willing to accept from the server. The set always contains Identity because the gRPC specification mandates that uncompressed messages are accepted.

The value is used to build the `grpc-accept-encoding` request header. If the server responds with a compression algorithm that is not in this set, the call is finished with a Unimplemented status code.

By default, this is supportedCompressionAlgorithms(): every algorithm the current Qt build can negotiate is advertised.

This function was introduced in Qt 6.12.

See also setAcceptedCompressionAlgorithms() and supportedCompressionAlgorithms().

### `[since 6.10]` QGrpcChannelOptions &QGrpcChannelOptions::addMetadata(QByteArrayView key, QByteArrayView value)

Adds key and value to the metadata if the exact pair is not already contained. The same key may appear multiple times with different values.

Note: Keys with the `grpc-` or `qtgrpc-` prefix are reserved by gRPC and QtGrpc. Provided entries using them are ignored when the request is built. Concrete channels may impose further restrictions; see QGrpcHttp2Channel#Reserved metadata keys.

Note: This metadata is included in every RPC made through the channel. Channel metadata is merged with any call-specific metadata when the RPC starts — see QGrpcCallOptions::addMetadata()

This function was introduced in Qt 6.10.

See also metadata() and setMetadata().

### `[noexcept]` std::optional<std::chrono::milliseconds> QGrpcChannelOptions::deadlineTimeout() const

Returns the timeout duration that is used to calculate the deadline for the channel.

If this field is unset, returns an empty `std::optional`.

See also setDeadlineTimeout().

### `[noexcept, since 6.11]` std::optional<bool> QGrpcChannelOptions::filterServerMetadata() const

Returns `true` if protocol-related server metadata is excluded from the result. Returns `false` to include all metadata received from the server.

If this field is unset, returns an empty `std::optional`.

This function was introduced in Qt 6.11.

See also setFilterServerMetadata() and QGrpcCallOptions::filterServerMetadata().

### `[since 6.12]` std::optional<quint64> QGrpcChannelOptions::maximumReceiveMessageSize() const

Returns the maximum allowed size in bytes of an incoming gRPC message. The limit applies to the decoded gRPC frame payload, after transport-level decryption and any per-message decompression.

If the value is not specified, returns an empty `std::optional`.

By default, the value is not specified.

Note: QGrpcHttp2Channel uses the `QT_GRPC_MAXIMUM_RECEIVE_MESSAGE_SIZE` environment variable as a fallback when this option is not set explicitly. If the environment variable is not set, the built-in default value of `4` MiB is used. See l{Environment variable fallbacks}.

This function was introduced in Qt 6.12.

See also setMaximumReceiveMessageSize() and QGrpcCallOptions::maximumReceiveMessageSize().

### `[until 6.13]` QHash<QByteArray, QByteArray> QGrpcChannelOptions::metadata() &&

### `[noexcept, until 6.13]` const QHash<QByteArray, QByteArray> &QGrpcChannelOptions::metadata() const &

This function is scheduled for deprecation in version 6.13.

Use metadata(QtGrpc::MultiValue) instead.

Returns the metadata. If this field is unset, returns empty metadata.

Note: Keys with the `grpc-` or `qtgrpc-` prefix are reserved by gRPC and QtGrpc. Provided entries using them are ignored when the request is built. Concrete channels may impose further restrictions; see QGrpcHttp2Channel#Reserved metadata keys.

See also metadata(QtGrpc::MultiValue_t) and setMetadata().

### `[since 6.10]` QMultiHash<QByteArray, QByteArray> QGrpcChannelOptions::metadata(QtGrpc::MultiValue_t) &&

### `[noexcept, since 6.10]` const QMultiHash<QByteArray, QByteArray> &QGrpcChannelOptions::metadata(QtGrpc::MultiValue_t) const &

Returns the metadata. If this field is unset, returns empty metadata.

Note: Keys with the `grpc-` or `qtgrpc-` prefix are reserved by gRPC and QtGrpc. Provided entries using them are ignored when the request is built. Concrete channels may impose further restrictions; see QGrpcHttp2Channel#Reserved metadata keys. Multiple values per key are supported.

     const auto &md = opts.metadata(QtGrpc::MultiValue);

These functions were introduced in Qt 6.10.

See also setMetadata.

### `[since 6.12]` std::optional<QtGrpc::CompressionAlgorithm> QGrpcChannelOptions::requestCompression() const

Returns the compression algorithm used to compress outbound messages on this channel or call.

If this field is unset, returns an empty `std::optional`.

This function was introduced in Qt 6.12.

See also setRequestCompression() and QGrpcCallOptions::requestCompression().

### `[since 6.8]` QGrpcSerializationFormat QGrpcChannelOptions::serializationFormat() const

Returns the serialization format used by the channel.

If this field is unset, returns a Default constructed serialization format.

This function was introduced in Qt 6.8.

See also setSerializationFormat().

### `[since 6.12]` QGrpcChannelOptions &QGrpcChannelOptions::setAcceptedCompressionAlgorithms(QtGrpc::CompressionAlgorithms algorithms)

Sets the accepted compression algorithms and returns a reference to the updated object.

Identity is always added implicitly, because the gRPC specification requires clients to accept uncompressed messages.

If `{QtGrpc::CompressionAlgorithm::Identity}` is the only accepted algorithm, compressed responses are refused. Adding additional flags allows the server to respond using those compression algorithms.

Only algorithms supported by this Qt build and included in algorithms are advertised to the server as accepted response compression methods. Flags that are not present in supportedCompressionAlgorithms() are silently discarded.

This function was introduced in Qt 6.12.

See also acceptedCompressionAlgorithms() and supportedCompressionAlgorithms().

### QGrpcChannelOptions &QGrpcChannelOptions::setDeadlineTimeout(std::chrono::milliseconds timeout)

Sets the timeout and returns a reference to the updated object.

A deadline sets the limit for how long a client is willing to wait for a response from a server. The actual deadline is computed by adding the timeout to the start time of the RPC.

The deadline applies to the entire lifetime of an RPC, which includes receiving the final QGrpcStatus for a previously started call and can thus be unwanted for (long-lived) streams.

Note: Setting this field applies to all RPCs that operate on the channel, except those overriden by QGrpcCallOptions::setDeadlineTimeout()

See also deadlineTimeout().

### `[since 6.11]` QGrpcChannelOptions &QGrpcChannelOptions::setFilterServerMetadata(bool value)

If value is `true`, protocol-related metadata defined by the gRPC transport (such as reserved `grpc-` keys) will be excluded. If value is `false`, all metadata received from the server will be included.

Note: Setting this field applies to all RPCs that operate on the channel, except those overriden by QGrpcCallOptions::filterServerMetadata

This function was introduced in Qt 6.11.

See also filterServerMetadata() and QGrpcCallOptions::setFilterServerMetadata().

### `[since 6.12]` QGrpcChannelOptions &QGrpcChannelOptions::setMaximumReceiveMessageSize(quint64 size)

Sets the maximum incoming message size in bytes and returns a reference to the updated object.

Messages exceeding this limit are rejected with StatusCode::ResourceExhausted before their payload is buffered. The value is used verbatim, so a size of `0` accepts only empty messages.

Note: Concrete channel implementations may impose a hard upper bound on the effective limit. The QGrpcHttp2Channel transport caps the value at the maximum gRPC-over-HTTP/2 frame payload (`2^32 - 1`) bytes, or `qsizetype`'s maximum minus the 5-byte gRPC frame header on 32-bit platforms. A larger configured value is clamped to that cap.

Note: Setting this field applies to all RPCs that operate on the channel, except those overriden by QGrpcCallOptions::setMaximumReceiveMessageSize()

This function was introduced in Qt 6.12.

See also maximumReceiveMessageSize() and QGrpcCallOptions::setMaximumReceiveMessageSize().

### `[until 6.13]` QGrpcChannelOptions &QGrpcChannelOptions::setMetadata(QHash<QByteArray, QByteArray> &&metadata)

### `[until 6.13]` QGrpcChannelOptions &QGrpcChannelOptions::setMetadata(const QHash<QByteArray, QByteArray> &metadata)

This function is scheduled for deprecation in version 6.13.

Use the QMultiHash overload instead.

Sets the metadata and returns a reference to the updated object.

Note: Keys with the `grpc-` or `qtgrpc-` prefix are reserved by gRPC and QtGrpc. Provided entries using them are ignored when the request is built. Concrete channels may impose further restrictions; see QGrpcHttp2Channel#Reserved metadata keys.

Note: This metadata is included in every RPC made through the channel. Channel metadata is merged with any call-specific metadata when the RPC starts — see QGrpcCallOptions::setMetadata(QMultiHash)

See also metadata().

### `[since 6.10]` QGrpcChannelOptions &QGrpcChannelOptions::setMetadata(QMultiHash<QByteArray, QByteArray> &&metadata)

### `[since 6.10]` QGrpcChannelOptions &QGrpcChannelOptions::setMetadata(const QMultiHash<QByteArray, QByteArray> &metadata)

### `[since 6.10]` QGrpcChannelOptions &QGrpcChannelOptions::setMetadata(std::initializer_list<std::pair<QByteArray, QByteArray>> list)

Sets the metadata and returns a reference to the updated object.

Note: Keys with the `grpc-` or `qtgrpc-` prefix are reserved by gRPC and QtGrpc. Provided entries using them are ignored when the request is built. Concrete channels may impose further restrictions; see QGrpcHttp2Channel#Reserved metadata keys. Multiple values per key are supported.

Note: This metadata is included in every RPC made through the channel. Channel metadata is merged with any call-specific metadata when the RPC starts — see QGrpcCallOptions::setMetadata(QMultiHash)

These functions were introduced in Qt 6.10.

See also metadata(QtGrpc::MultiValue_t).

### `[since 6.12]` QGrpcChannelOptions &QGrpcChannelOptions::setRequestCompression(QtGrpc::CompressionAlgorithm algorithm)

Sets the compression algorithm used to compress messages sent by the client and returns a reference to the updated object.

When set, the algorithm is announced in the `grpc-encoding` request header. Each message is compressed independently; if compression does not reduce the payload size, the message is sent uncompressed with the `Compressed-Flag` set to `0` regardless.

Note: Compressing messages that contain both sensitive data and data that could potentially be influenced by an attacker may expose the connection to compression side-channel attacks such as CRIME or BREACH. If possible, avoid compressing such messages, or separate sensitive and untrusted data into different requests.

Note: Setting this field applies to all RPCs that operate on the channel, except those overriden by QGrpcCallOptions::setRequestCompression()

This function was introduced in Qt 6.12.

See also requestCompression() and QGrpcCallOptions::setRequestCompression().

### `[since 6.8]` QGrpcChannelOptions &QGrpcChannelOptions::setSerializationFormat(const QGrpcSerializationFormat &format)

Sets the serialization format for the channel and returns a reference to the updated object.

This function was introduced in Qt 6.8.

See also serializationFormat().

### QGrpcChannelOptions &QGrpcChannelOptions::setSslConfiguration(const QSslConfiguration &sslConfiguration)

Sets the sslConfiguration for the channel and returns a reference to the updated object.

See also sslConfiguration().

### std::optional<QSslConfiguration> QGrpcChannelOptions::sslConfiguration() const

Returns the SSL configuration for the channel.

If this field is unset, returns an empty `std::optional`.

See also setSslConfiguration().

### `[static noexcept, since 6.12]` QtGrpc::CompressionAlgorithms QGrpcChannelOptions::supportedCompressionAlgorithms()

Returns the compression algorithms that the current Qt build can negotiate. Identity is always present because the gRPC specification mandates uncompressed messages. Deflate and Gzip are always supported.

This function was introduced in Qt 6.12.

See also acceptedCompressionAlgorithms() and setAcceptedCompressionAlgorithms().

### `[noexcept, since 6.8]` void QGrpcChannelOptions::swap(QGrpcChannelOptions &other)

Swaps other with this object. This operation is very fast and never fails.

This function was introduced in Qt 6.8.

### `[since 6.8]` QGrpcChannelOptions::operator QVariant() const

Constructs a new QVariant from this object.

This function was introduced in Qt 6.8.

### `[noexcept]` QGrpcChannelOptions &QGrpcChannelOptions::operator=(QGrpcChannelOptions &&other)

Move-assigns other to this QGrpcChannelOptions and returns a reference to the updated object.

Note: The moved-from object other is placed in a partially-formed state, in which the only valid operations are destruction and assignment of a new value.

### QGrpcChannelOptions &QGrpcChannelOptions::operator=(const QGrpcChannelOptions &other)

Assigns other to this QGrpcChannelOptions and returns a reference to the updated object.

## Related Non-Members

### `[noexcept, since 6.11]` bool operator!=(const QGrpcChannelOptions &lhs, const QGrpcChannelOptions &rhs)

Returns `true` if the acceptedCompressionAlgorithms, deadlineTimeout, filterServerMetadata, maximumReceiveMessageSize, metadata(QtGrpc::MultiValue_t), requestCompression, serializationFormat and sslConfiguration in lhs and rhs are not equal.

This function was introduced in Qt 6.11.

### `[since 6.8]` QDebug operator<<(QDebug debug, const QGrpcChannelOptions &chOpts)

Writes chOpts to the specified stream debug.

This function was introduced in Qt 6.8.

### `[noexcept, since 6.11]` bool operator==(const QGrpcChannelOptions &lhs, const QGrpcChannelOptions &rhs)

Returns `true` if the acceptedCompressionAlgorithms, deadlineTimeout, filterServerMetadata, maximumReceiveMessageSize, metadata(QtGrpc::MultiValue_t), requestCompression, serializationFormat and sslConfiguration in lhs and rhs are equal.

This function was introduced in Qt 6.11.