Back to Qt.io
Contact Us Blog Download Qt
本页内容

QGrpcCallOptions Class

QGrpcCallOptions 类提供了多种选项，用于对单个 RPC 进行精细调整。更多内容...

头文件： #include <QGrpcCallOptions>
CMake： find_package(Qt6 REQUIRED COMPONENTS Grpc)
target_link_libraries(mytarget PRIVATE Qt6::Grpc)
自： Qt 6.6
在 QML 中： GrpcCallOptions

QGrpcCallOptions 比较

类别可比较类型
相等性QGrpcCallOptions

公共函数

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)

详细说明

QGrpcCallOptions 允许您自定义各个远程过程调用（RPC）。生成的客户端接口提供了用于传递 QGrpcCallOptions 的访问点。这些选项将覆盖通过QGrpcChannelOptions 设置的选项。

若要配置 RPC 共用的默认选项，请使用QGrpcChannelOptions 。

QGrpcCallOptions callOpts;
// 为单个 RPC 设置元数据
callOpts.setMetadata({
    {"header" , "value1"},
    {"header" , "value2"},
});
const auto &md =callOpts.metadata(QtGrpc::MultiValue);
qDebug() << "Call Metadata: " << md;

// 为单个 RPC 设置 2 秒的超时限制
callOpts.setDeadlineTimeout(2s);
qDebug() << "Call timeout: " << callOpts.deadlineTimeout();

成员函数文档

QGrpcCallOptions::QGrpcCallOptions()

默认——构造一个空的 QGrpcCallOptions 对象。

QGrpcCallOptions::QGrpcCallOptions(const QGrpcCallOptions &other)

从other 复制并构造一个QGrpcCallOptions对象。

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

从other 构建一个新的QGrpcCallOptions对象。

注意： 被移动的对象 other 将处于部分构建状态，在此状态下，唯一有效的操作是销毁和赋值。

[noexcept] QGrpcCallOptions::~QGrpcCallOptions()

销毁QGrpcCallOptions 。

[since 6.10] QGrpcCallOptions &QGrpcCallOptions::addMetadata(QByteArrayView key, QByteArrayView value)

如果metadata 中尚未包含完全匹配的键值对，则向其中添加key 和value 。同一键可能以不同的值出现多次。

注意： 以grpc- 或qtgrpc- 为前缀的键由 gRPC™ 和QtGrpc 预留。在构建请求时，使用这些前缀的条目将被忽略。具体通道可能会施加进一步的限制；请参阅QGrpcHttp2Channel#Reserved metadata keys 。

注意： 在 RPC 开始时，调用 元数据会与任何通道级元数据合并——参见QGrpcChannelOptions::addMetadata()

此函数于 Qt 6.10 中引入。

另请参阅 metadata() 和setMetadata()。

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

返回用于计算 RPC 截止时间的超时时长。

如果该字段未设置，则返回一个空的std::optional 。

另请参阅 setDeadlineTimeout()。

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

如果结果中排除了与协议相关的服务器元数据，则返回 `true `。若要包含从服务器接收到的所有元数据，则返回 `false `。

如果未设置此字段，则返回一个空的std::optional 。

该函数在 Qt 6.11 中引入。

另请参阅 setFilterServerMetadata() 和QGrpcChannelOptions::filterServerMetadata()。

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

返回传入 gRPC 消息的最大允许大小（以字节为单位）。该限制适用于经过传输层解密和任何按消息进行的解压缩后的解码 gRPC 帧有效载荷。

如果未指定该值，则返回一个空的std::optional 。

默认情况下，该值未指定。

注意： 当未显式设置此选项时，QGrpcHttp2Channel 会使用QT_GRPC_MAXIMUM_RECEIVE_MESSAGE_SIZE 环境变量作为后备值。如果该环境变量未设置，则使用内置默认值4 MiB。参见l{环境变量后备值}。

该函数在 Qt 6.12 中引入。

另请参阅 setMaximumReceiveMessageSize() 和QGrpcChannelOptions::maximumReceiveMessageSize()。

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

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

该函数计划在 6.13 版本中被废弃。

请改用QMultiHash 重载版本。

返回元数据。如果该字段未设置，则返回空元数据。

注意： 以grpc- 或qtgrpc- 为前缀的键由 gRPC 和QtGrpc 保留。在构建请求时，使用这些前缀提供的条目将被忽略。具体的通道可能会施加进一步的限制；请参阅QGrpcHttp2Channel#Reserved metadata keys 。

另请参阅 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 &

返回元数据。如果该字段未设置，则返回空元数据。

注意： 以grpc- 或qtgrpc- 为前缀的键 被gRPC 和QtGrpc 预留。在构建请求时，使用这些前缀提供的条目将被忽略。具体频道可能会施加进一步的限制；请参阅QGrpcHttp2Channel#Reserved metadata keys 。支持每个键具有多个值。

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

这些函数在 Qt 6.10 中引入。

另请参阅 setMetadata 。

[since 6.12] std::optional<QtGrpc::CompressionAlgorithm> QGrpcCallOptions::requestCompression() const

返回用于压缩此信道或呼叫中出站消息的压缩算法。

如果该字段未设置，则返回一个空的std::optional 。

该函数在 Qt 6.12 中引入。

另请参阅 setRequestCompression() 和QGrpcChannelOptions::requestCompression()。

QGrpcCallOptions &QGrpcCallOptions::setDeadlineTimeout(std::chrono::milliseconds timeout)

设置timeout ，并返回更新后对象的引用。

超时期限设定了客户端愿意等待服务器响应的最长时限。实际超时期限通过将timeout 与RPC的开始时间相加来计算。

该截止时间适用于 RPC 的整个生命周期，其中包括接收先前启动的调用所对应的最终 `QGrpcStatus `，因此对于（长期运行的）流而言可能是不需要的。

注意：设置 此字段将覆盖相应的通道选项字段——参见QGrpcChannelOptions::setDeadlineTimeout()

另请参阅 deadlineTimeout()简体中文（大陆）

[since 6.11] QGrpcCallOptions &QGrpcCallOptions::setFilterServerMetadata(bool value)

如果value 的值为true ，则由 gRPC 传输层定义的与协议相关的元数据（例如预留的grpc- 键）将被排除。如果value 的值为false ，则将包含从服务器接收的所有元数据。

注意：设置 此字段将覆盖相应的通道选项字段——参见QGrpcChannelOptions::setFilterServerMetadata()

此函数于 Qt 6.11 中引入。

另请参阅 filterServerMetadata() 和QGrpcChannelOptions::setFilterServerMetadata()。

[since 6.12] QGrpcCallOptions &QGrpcCallOptions::setMaximumReceiveMessageSize(quint64 size)

设置传入消息的size 最大值（以字节为单位），并返回更新后对象的引用。

超过此限制的消息在有效载荷被缓冲之前会被以StatusCode::ResourceExhausted 为由拒绝。该值将原样使用，因此size 的0 仅接受空消息。

注意：具体的 通道实现可能会对实际限制施加硬性上限。QGrpcHttp2Channel 传输将该值限制在gRPC-over-HTTP/2帧有效载荷（2^32 - 1 ）的最大字节数，或在32位平台上为qsizetype 的最大值减去5字节的gRPC帧头。 若配置的值大于该上限，则会被限制在此上限内。

注意：设置 此字段将覆盖相应的通道选项字段——请参阅QGrpcChannelOptions::setMaximumReceiveMessageSize 。

该函数在 Qt 6.12 中引入。

另请参阅 maximumReceiveMessageSize() 和QGrpcChannelOptions::setMaximumReceiveMessageSize()。

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

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

该函数计划在 6.13 版本中被废弃。

请改用QMultiHash 的重载版本。

该函数用于设置metadata ，并返回更新后对象的引用。

注意： 以grpc- 或qtgrpc- 为前缀的键由 gRPC 和QtGrpc 保留。在构建请求时，使用这些前缀提供的条目将被忽略。具体的通道可能会施加进一步的限制；请参阅QGrpcHttp2Channel#Reserved metadata keys 。

注意： RPC 启动时，调用 元数据会与任何通道级元数据合并——参见QGrpcChannelOptions::setMetadata(QMultiHash)。

另请参阅 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)

设置metadata ，并返回更新后对象的引用。

注意： 以grpc- 或qtgrpc- 为前缀的键 被gRPC 和QtGrpc 保留。在构建请求时，使用这些前缀提供的条目将被忽略。具体频道可能会施加进一步的限制；请参阅QGrpcHttp2Channel#Reserved metadata keys 。支持每个键具有多个值。

注意： 在 RPC 开始时，调用 元数据会与任何通道级元数据合并——参见QGrpcChannelOptions::setMetadata(QMultiHash)。

这些函数在 Qt 6.10 中引入。

另请参阅 metadata(QtGrpc::MultiValue_t)。

[since 6.12] QGrpcCallOptions &QGrpcCallOptions::setRequestCompression(QtGrpc::CompressionAlgorithm algorithm)

设置用于压缩客户端发送的消息的algorithm ，并返回更新后对象的引用。

设置后，该算法将在grpc-encoding 请求头中声明。每条消息均独立进行压缩；如果压缩无法减小有效载荷大小，则无论如何，该消息都将以未压缩形式发送，此时Compressed-Flag 将设置为0 。

注意：对 同时包含敏感数据和可能受攻击者影响的数据的消息进行压缩 ，可能会使连接暴露于 CRIME 或 BREACH 等压缩侧信道攻击。如果可能，请避免对这类消息进行压缩，或者将敏感数据和不可信数据分开放入不同的请求中。

注意：设置 此字段将覆盖相应的通道选项字段。

此功能于 Qt 6.12 中引入。

另请参阅 requestCompression() 和QGrpcChannelOptions::setRequestCompression()。

[noexcept, since 6.8] void QGrpcCallOptions::swap(QGrpcCallOptions &other)

将other 与该对象互换。此操作速度极快，且绝不会失败。

该函数自 Qt 6.8 起引入。

[since 6.8] QGrpcCallOptions::operator QVariant() const

根据该对象构建一个新的QVariant 。

该函数于 Qt 6.8 中引入。

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

将other 移动赋值给此QGrpcCallOptions ，并返回对更新后对象的引用。

注意： 被移动的源对象 other 将处于部分初始化状态，在此状态下，唯一有效的操作是销毁或赋予新值。

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

将other 赋值给此QGrpcCallOptions ，并返回对更新后对象的引用。

相关的非成员

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

如果lhs 和rhs 中的deadlineTimeout 、filterServerMetadata 、maximumReceiveMessageSize 、requestCompression 以及metadata （均为 QtGrpc::MultiValue_t）不相同，则返回true 。

该函数于 Qt 6.11 中引入。

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

将callOpts 写入指定的流debug 。

该函数于 Qt 6.8 中引入。

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

如果lhs 和rhs 中的deadlineTimeout 、filterServerMetadata 、maximumReceiveMessageSize 、requestCompression 以及metadata （均为 QtGrpc::MultiValue_t）相等，则返回true 。

该函数于 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.