Back to Doc.qt.io
Contact Us Blog Download Qt
On this page

QGrpcCallOptions Class

The QGrpcCallOptions class offers various options for fine-tuning individual RPCs. More...

Header: #include <QGrpcCallOptions>
CMake: find_package(Qt6 REQUIRED COMPONENTS Grpc)
target_link_libraries(mytarget PRIVATE Qt6::Grpc)
Since: Qt 6.6
In QML: GrpcCallOptions

QGrpcCallOptions Comparisons

CategoryComparable Types
equalityQGrpcCallOptions

Public Functions

QGrpcCallOptions()
QGrpcCallOptions(const QGrpcCallOptions &other)
QGrpcCallOptions(QGrpcCallOptions &&other)
~QGrpcCallOptions()
(since 6.10) QGrpcCallOptions &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
QGrpcCallOptions &setDeadlineTimeout(std::chrono::milliseconds timeout)
(since 6.11) QGrpcCallOptions &setFilterServerMetadata(bool value)
(since 6.12) QGrpcCallOptions &setMaximumReceiveMessageSize(quint64 size)
(until 6.13) QGrpcCallOptions &setMetadata(QHash<QByteArray, QByteArray> &&metadata)
(since 6.10) QGrpcCallOptions &setMetadata(QMultiHash<QByteArray, QByteArray> &&metadata)
(until 6.13) QGrpcCallOptions &setMetadata(const QHash<QByteArray, QByteArray> &metadata)
(since 6.10) QGrpcCallOptions &setMetadata(const QMultiHash<QByteArray, QByteArray> &metadata)
(since 6.10) QGrpcCallOptions &setMetadata(std::initializer_list<std::pair<QByteArray, QByteArray>> metadata)
(since 6.12) QGrpcCallOptions &setRequestCompression(QtGrpc::CompressionAlgorithm algorithm)
(since 6.8) void swap(QGrpcCallOptions &other)
(since 6.8) operator QVariant() const
QGrpcCallOptions &operator=(QGrpcCallOptions &&other)
QGrpcCallOptions &operator=(const QGrpcCallOptions &other)
(since 6.11) bool operator!=(const QGrpcCallOptions &lhs, const QGrpcCallOptions &rhs)
(since 6.8) QDebug operator<<(QDebug debug, const QGrpcCallOptions &callOpts)
(since 6.11) bool operator==(const QGrpcCallOptions &lhs, const QGrpcCallOptions &rhs)

Detailed Description

QGrpcCallOptions lets you customize individual remote procedure calls (RPCs). The generated client interface provides access points to pass the QGrpcCallOptions. These options supersede the ones set via QGrpcChannelOptions.

To configure the default options shared by RPCs, use QGrpcChannelOptions.

QGrpcCallOptions callOpts;
// Set the metadata for an individial RPC
callOpts.setMetadata({
    { "header" , "value1" },
    { "header" , "value2" },
});
const auto &md = callOpts.metadata(QtGrpc::MultiValue);
qDebug() << "Call Metadata: " << md;

// Set a 2-second deadline for an individial RPC
callOpts.setDeadlineTimeout(2s);
qDebug() << "Call timeout: " << callOpts.deadlineTimeout();

Member Function Documentation

QGrpcCallOptions::QGrpcCallOptions()

Default-constructs an empty QGrpcCallOptions.

QGrpcCallOptions::QGrpcCallOptions(const QGrpcCallOptions &other)

Copy-constructs a QGrpcCallOptions from other.

[constexpr noexcept default] QGrpcCallOptions::QGrpcCallOptions(QGrpcCallOptions &&other)

Move-constructs a new QGrpcCallOptions 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] QGrpcCallOptions::~QGrpcCallOptions()

Destroys the QGrpcCallOptions.

[since 6.10] QGrpcCallOptions &QGrpcCallOptions::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: Call metadata is merged with any channel-level metadata when the RPC starts — see QGrpcChannelOptions::addMetadata()

This function was introduced in Qt 6.10.

See also metadata() and setMetadata().

[noexcept] std::optional<std::chrono::milliseconds> QGrpcCallOptions::deadlineTimeout() const

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

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

See also setDeadlineTimeout().

[noexcept, since 6.11] std::optional<bool> QGrpcCallOptions::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 QGrpcChannelOptions::filterServerMetadata().

[since 6.12] std::optional<quint64> QGrpcCallOptions::maximumReceiveMessageSize() const

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

This function returns only the value explicitly configured on this object:

  • std::nullopt if no value was set
  • 0 if the QtGrpc-imposed limit is disabled
  • otherwise, the configured maximum message size

If no value is configured, the effective limit is resolved when an RPC starts using the following precedence:

  1. call options
  2. channel options
  3. the QT_GRPC_MAXIMUM_RECEIVE_MESSAGE_SIZE environment variable
  4. the built-in 4 MiB default specified by gRPC

This function was introduced in Qt 6.12.

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

[until 6.13] QHash<QByteArray, QByteArray> QGrpcCallOptions::metadata() &&

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

This function is scheduled for deprecation in version 6.13.

Use the QMultiHash overload 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 setMetadata().

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

[noexcept, since 6.10] const QMultiHash<QByteArray, QByteArray> &QGrpcCallOptions::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.

[noexcept, since 6.12] std::optional<QtGrpc::CompressionAlgorithm> QGrpcCallOptions::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 QGrpcChannelOptions::requestCompression().

QGrpcCallOptions &QGrpcCallOptions::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 overrides the corresponding channel options field — see QGrpcChannelOptions::setDeadlineTimeout()

See also deadlineTimeout().

[since 6.11] QGrpcCallOptions &QGrpcCallOptions::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 overrides the corresponding channel options field — see QGrpcChannelOptions::setFilterServerMetadata()

This function was introduced in Qt 6.11.

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

[since 6.12] QGrpcCallOptions &QGrpcCallOptions::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.

A value of 0 disables the QtGrpc-imposed limit. If no value is configured, a default limit of 4 MiB applies, matching the gRPC specification.

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 overrides the corresponding channel options field.

This function was introduced in Qt 6.12.

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

[until 6.13] QGrpcCallOptions &QGrpcCallOptions::setMetadata(QHash<QByteArray, QByteArray> &&metadata)

[until 6.13] QGrpcCallOptions &QGrpcCallOptions::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: Call metadata is merged with any channel-level metadata when the RPC starts — see QGrpcChannelOptions::setMetadata(QMultiHash).

See also metadata().

[since 6.10] QGrpcCallOptions &QGrpcCallOptions::setMetadata(QMultiHash<QByteArray, QByteArray> &&metadata)

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

[since 6.10] QGrpcCallOptions &QGrpcCallOptions::setMetadata(std::initializer_list<std::pair<QByteArray, QByteArray>> metadata)

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: Call metadata is merged with any channel-level metadata when the RPC starts — see QGrpcChannelOptions::setMetadata(QMultiHash).

These functions were introduced in Qt 6.10.

See also metadata(QtGrpc::MultiValue_t).

[since 6.12] QGrpcCallOptions &QGrpcCallOptions::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 overrides the corresponding channel options field.

This function was introduced in Qt 6.12.

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

[noexcept, since 6.8] void QGrpcCallOptions::swap(QGrpcCallOptions &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] QGrpcCallOptions::operator QVariant() const

Constructs a new QVariant from this object.

This function was introduced in Qt 6.8.

[noexcept] QGrpcCallOptions &QGrpcCallOptions::operator=(QGrpcCallOptions &&other)

Move-assigns other to this QGrpcCallOptions 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.

QGrpcCallOptions &QGrpcCallOptions::operator=(const QGrpcCallOptions &other)

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

Related Non-Members

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

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

This function was introduced in Qt 6.11.

[since 6.8] QDebug operator<<(QDebug debug, const QGrpcCallOptions &callOpts)

Writes callOpts to the specified stream debug.

This function was introduced in Qt 6.8.

[noexcept, since 6.11] bool operator==(const QGrpcCallOptions &lhs, const QGrpcCallOptions &rhs)

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

This function was introduced in Qt 6.11.

© 2026 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.