qiurui
/
qtgrpc
mirror of https://github.com/qt/qtgrpc.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

docs: Add common http2-metadata description and distribute it 

Our documentation of what the QGrpcHttp2Channel should accept as
metadata was incomplete. Add the missing bits and give readers a link to
the original information, which is coming from RFC 7540.

Task-number: QTBUG-139558
Pick-to: 6.10 6.9 6.8
Change-Id: Ie170fd1f5300597b31dd49d47d5e01c469bf6ec3
Reviewed-by: Alexey Edelev <alexey.edelev@qt.io>
This commit is contained in:
Dennis Oberst 2025-09-03 16:42:34 +02:00
parent 56999b3605
commit 6f589e1d5c
3 changed files with 19 additions and 7 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

9
src/grpc/doc/src/qtgrpc-shared.qdocinc
View File

@ -26,3 +26,12 @@
\l{QGrpcOperation::} {finished} signal is emitted. After receiving this
signal, the handler can be safely reassigned or destroyed.
//! [rpc-lifetime-note]
//! [http2-metadata-note]
\note QGrpcHttp2Channel transports metadata as HTTP/2 headers. \b{Keys} are
case-insensitive ASCII strings. You must avoid using the internal prefixes:
\c{:} (pseudo-header), \c{grpc-}, or \c{qtgrpc-}. \b{Values} may be either
ASCII strings or binary data. For more information, see
\l{https://www.rfc-editor.org/rfc/rfc7540.html#section-8.1.2}{RFC 7540,
Section 8.1.2}.
//! [http2-metadata-note]

7
src/grpc/qgrpccommonoptions.cpp
View File

@ -23,6 +23,8 @@ QtGrpcPrivate::toHash(const QMultiHash<QByteArray, QByteArray> &multiHash)
//! [metadata]
Returns the metadata. If this field is unset, returns empty
metadata.
\include qtgrpc-shared.qdocinc http2-metadata-note
//! [metadata]
*/
const QHash<QByteArray, QByteArray> &QGrpcCommonOptions::metadata() const & noexcept
@ -46,8 +48,7 @@ QHash<QByteArray, QByteArray> QGrpcCommonOptions::metadata() &&
//! [set-metadata]
Sets the \a metadata and returns a reference to the updated object.
When using QGrpcHttp2Channel, the metadata is converted to HTTP/2 headers
and added to the gRPC request.
\include qtgrpc-shared.qdocinc http2-metadata-note
//! [set-metadata]
*/
void QGrpcCommonOptions::setMetadata(const QHash<QByteArray, QByteArray> &md)
@ -142,6 +143,8 @@ void QGrpcCommonOptions::setMetadata(QMultiHash<QByteArray, QByteArray> &&md)
Adds \a key and \a value to the \l metadata if the exact pair is not already contained.
The same key may appear multiple times with different values.
\include qtgrpc-shared.qdocinc http2-metadata-note
\sa {metadata(QtGrpc::MultiValue_t)}{metadata()} {setMetadata(const
QMultiHash<QByteArray, QByteArray>&)}{setMetadata()}
//! [add-metadata]

10
src/grpc/qgrpcoperation.cpp
View File

@ -183,13 +183,12 @@ const QHash<QByteArray, QByteArray> &QGrpcOperation::metadata() const & noexcept
established. It may include key-value pairs that provide context for the
call.
\note For \l {QGrpcHttp2Channel} {HTTP/2 channels}, this is delivered
via response headers.
\include qtgrpc-shared.qdocinc http2-metadata-note
//! [serverInitialMetadata]
The metadata may contain multiple entries under the same key.
\sa serverTrailingMetadata()
\sa serverInitialMetadataReceived() serverTrailingMetadata()
*/
const QMultiHash<QByteArray, QByteArray> &QGrpcOperation::serverInitialMetadata() const & noexcept
{
@ -208,11 +207,12 @@ const QMultiHash<QByteArray, QByteArray> &QGrpcOperation::serverInitialMetadata(
have been sent and just before the RPC completes. It may include key-value
pairs providing additional context about the completed call.
\note For \l {QGrpcHttp2Channel} {HTTP/2 channels}, this is delivered
via response trailers.
\include qtgrpc-shared.qdocinc http2-metadata-note
//! [serverTrailingMetadata]
The metadata may contain multiple entries under the same key.
\sa serverInitialMetadata()
*/
const QMultiHash<QByteArray, QByteArray> &QGrpcOperation::serverTrailingMetadata() const & noexcept
{