QGrpcOperationContext Class | Qt GRPC | Qt 6.11.0
Description: The QGrpcOperationContext class provides context for communication between an individual gRPC operation and a channel.

- Qt 6.11
- Qt GRPC
- C++ Classes
- QGrpcOperationContext
- Qt 6.11.0 Reference Documentation

# QGrpcOperationContext Class

The QGrpcOperationContext class provides context for communication between an individual gRPC™ operation and a channel. More...

Header: | `#include <QGrpcOperationContext>`
CMake: | `find_package(Qt6 REQUIRED COMPONENTS Grpc)` `target_link_libraries(mytarget PRIVATE Qt6::Grpc)`
Since: | Qt 6.7
Inherits: | QObject

- List of all members, including inherited members

## Public Functions

virtual | ~QGrpcOperationContext() override
const QGrpcCallOptions & | callOptions() const &
`(since 6.11)` QtGrpc::RpcDescriptor | descriptor() const
QLatin1StringView | method() const
`(since 6.11)` quint64 | operationId() const
QMetaType | responseMetaType() const
std::shared_ptr<const QAbstractProtobufSerializer> | serializer() const
`(since 6.10)` const QMultiHash<QByteArray, QByteArray> & | serverInitialMetadata() const &
`(until 6.13)` const QHash<QByteArray, QByteArray> & | serverMetadata() const &
`(since 6.10)` const QMultiHash<QByteArray, QByteArray> & | serverTrailingMetadata() const &
QLatin1StringView | service() const
void | setResponseMetaType(QMetaType metaType)
`(since 6.10)` void | setServerInitialMetadata(QMultiHash<QByteArray, QByteArray> &&metadata)
`(until 6.13)` void | setServerMetadata(QHash<QByteArray, QByteArray> &&metadata)
`(until 6.13)` void | setServerMetadata(const QHash<QByteArray, QByteArray> &metadata)
`(since 6.10)` void | setServerTrailingMetadata(QMultiHash<QByteArray, QByteArray> &&metadata)

## Signals

void | cancelRequested()
void | finished(const QGrpcStatus &status)
void | messageReceived(const QByteArray &data)
`(since 6.11)` void | serverInitialMetadataReceived(const QMultiHash<QByteArray, QByteArray> &metadata)
void | writeMessageRequested(const QByteArray &data)
void | writesDoneRequested()

## Detailed Description

QGrpcOperationContext is constructed internally when a remote procedure call (RPC) is requested, mediating interaction between the client's operation request and the channel's operation outcome.

RPCs requested on the client interface return specializations of QGrpcOperation, such as QGrpcCallReply, QGrpcServerStream, QGrpcClientStream, or QGrpcBidiStream. These classes are implicitly integrated with the underlying QGrpcOperationContext counterpart.

Note: Don't use this class directly unless implementing a custom channel.

The signals contained within this class are used to build the communication between the client-facing QGrpcOperation and the QAbstractGrpcChannel implementation. These operations are asynchronous in nature, and multiple RPCs can operate on the same channel concurrently. Channels typically treat all operations the same, and it is the channel's responsibility to correctly support and restrict the subset of features its RPC type supports.

Signals which should only be emitted by the channel's implementation are:

- finished()
- messageReceived()

Signals which will be emitted by QGrpcOperation and its specializations are:

- cancelRequested()
- writeMessageRequested()
- writesDoneRequested()

Custom implementations of QAbstractGrpcChannel must handle the client's signals, as no default signal handling is provided, and emit their own signals accordingly.

## Member Function Documentation

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

Destroys the operation-context.

### `[noexcept]` const QGrpcCallOptions &QGrpcOperationContext::callOptions() const &

Returns the call options that is utilized by this operation-context.

For channel-wide options, see QGrpcChannelOptions.

### `[signal]` void QGrpcOperationContext::cancelRequested()

This signal is emitted by QGrpcOperation when requesting cancellation of the communication.

The channel is expected to connect its cancellation logic to this signal and attempt to cancel the RPC and finish it with a Cancelled status code. Successful cancellation cannot be guaranteed. Further processing of the data received from a channel is not required and should be avoided.

See also QGrpcOperation::cancel.

### `[noexcept, since 6.11]` QtGrpc::RpcDescriptor QGrpcOperationContext::descriptor() const

Returns the QtGrpc::RpcDescriptor for this operation-context.

This function was introduced in Qt 6.11.

### `[signal]` void QGrpcOperationContext::finished(const QGrpcStatus &status)

This signal should be emitted by the channel when an RPC finishes.

It usually means that the server sent a status for the requested RPC and closed the connection. Implementations of QAbstractGrpcChannel should detect this situation and emit the signal.

After receiving this signal, no further communication should occur through this operation context. The client side may then safely delete the corresponding RPC object.

Note: This signal is implicitly connected to the QGrpcOperation counterpart.

See also QGrpcOperation::finished.

### `[signal]` void QGrpcOperationContext::messageReceived(const QByteArray &data)

This signal should be emitted by the channel when a new chunk of data is received from the server.

For client streams and unary calls, this means that the single and final response has arrived and communication is about to finish.

For server and bidirectional streams, this signal should be continuously emitted by the channel upon receiving each new messages.

Note: This signal is implicitly connected to the QGrpcOperation counterpart.

See also QGrpcServerStream::messageReceived and QGrpcBidiStream::messageReceived.

### `[noexcept]` QLatin1StringView QGrpcOperationContext::method() const

Returns the method name of the service associated with this operation-context.

### `[noexcept, since 6.11]` quint64 QGrpcOperationContext::operationId() const

Returns the unique identifier for this operation context.

Each ID is unique across all channels for the application lifetime.

This function was introduced in Qt 6.11.

### QMetaType QGrpcOperationContext::responseMetaType() const

Returns the meta type of the RPC result message.

See also setResponseMetaType().

### std::shared_ptr<const QAbstractProtobufSerializer> QGrpcOperationContext::serializer() const

Returns the serializer of this operation-context

### `[noexcept, since 6.10]` const QMultiHash<QByteArray, QByteArray> &QGrpcOperationContext::serverInitialMetadata() const &

Returns the initial metadata received from the server before any response messages.

Initial metadata is sent by the server immediately after the call is established. It may include key-value pairs that provide context for the call.

Note: QGrpcHttp2Channel transports metadata as HTTP/2 headers. Keys are case-insensitive ASCII strings. You must avoid using the internal prefixes: `:` (pseudo-header), `grpc-`, or `qtgrpc-`. Values may be either ASCII strings or binary data. For more information, see RFC 7540, Section 8.1.2.

Note: This method is used implicitly by QGrpcOperation.

This function was introduced in Qt 6.10.

See also setServerInitialMetadata(), QGrpcOperation::serverInitialMetadata(), and serverTrailingMetadata().

### `[private signal, since 6.11]` void QGrpcOperationContext::serverInitialMetadataReceived(const QMultiHash<QByteArray, QByteArray> &metadata)

This signal is emitted when the server responds with its initial metadata. Initial metadata from the server is sent to the client before the initial response of an RPC.

The received metadata is provided in metadata and is also available via serverInitialMetadata().

Note: This is a private signal. It can be used in signal connections but cannot be emitted by the user.

This function was introduced in Qt 6.11.

See also QGrpcOperation::serverInitialMetadataReceived and QGrpcBidiStream::writesDone.

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

This function is scheduled for deprecation in version 6.13.

Use serverInitialMetadata() and serverTrailingMetadata() instead.

Returns the initial metadata received from the server before any response messages.

Initial metadata is sent by the server immediately after the call is established. It may include key-value pairs that provide context for the call.

Note: QGrpcHttp2Channel transports metadata as HTTP/2 headers. Keys are case-insensitive ASCII strings. You must avoid using the internal prefixes: `:` (pseudo-header), `grpc-`, or `qtgrpc-`. Values may be either ASCII strings or binary data. For more information, see RFC 7540, Section 8.1.2.

Note: This method is used implicitly by QGrpcOperation.

See also setServerMetadata(), serverInitialMetadata(), and QGrpcOperation::serverInitialMetadata().

### `[noexcept, since 6.10]` const QMultiHash<QByteArray, QByteArray> &QGrpcOperationContext::serverTrailingMetadata() const &

Returns the trailing metadata received from the server after all response messages.

Trailing metadata is sent only by the server once all response messages have been sent and just before the RPC completes. It may include key-value pairs providing additional context about the completed call.

Note: QGrpcHttp2Channel transports metadata as HTTP/2 headers. Keys are case-insensitive ASCII strings. You must avoid using the internal prefixes: `:` (pseudo-header), `grpc-`, or `qtgrpc-`. Values may be either ASCII strings or binary data. For more information, see RFC 7540, Section 8.1.2.

Note: This method is used implicitly by QGrpcOperation.

This function was introduced in Qt 6.10.

See also QGrpcOperation::serverTrailingMetadata() and setServerTrailingMetadata().

### `[noexcept]` QLatin1StringView QGrpcOperationContext::service() const

Returns the service name associated with this operation-context.

### void QGrpcOperationContext::setResponseMetaType(QMetaType metaType)

Stores the metaType of the RPC result message.

See also responseMetaType().

### `[since 6.10]` void QGrpcOperationContext::setServerInitialMetadata(QMultiHash<QByteArray, QByteArray> &&metadata)

Sets the metadata received from the server at the start of the RPC.

This function was introduced in Qt 6.10.

See also serverInitialMetadata().

### `[until 6.13]` void QGrpcOperationContext::setServerMetadata(const QHash<QByteArray, QByteArray> &metadata)

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

This function is scheduled for deprecation in version 6.13.

Use setServerInitialMetadata() instead.

Sets the metadata received from the server at the start of the RPC.

See also setServerInitialMetadata().

### `[since 6.10]` void QGrpcOperationContext::setServerTrailingMetadata(QMultiHash<QByteArray, QByteArray> &&metadata)

Sets the trailing metadata received from the server after all response messages.

This function was introduced in Qt 6.10.

See also serverTrailingMetadata().

### `[signal]` void QGrpcOperationContext::writeMessageRequested(const QByteArray &data)

This signal is emitted by QGrpcClientStream or QGrpcBidiStream when it has serialized data ready for a channel to deliver.

The channel is expected to connect its writing logic to this signal and wrap the serialized data in channel-related headers before writing it to the wire.

See also QGrpcClientStream::writeMessage and QGrpcBidiStream::writeMessage.

### `[signal]` void QGrpcOperationContext::writesDoneRequested()

This signal is emitted by QGrpcClientStream or QGrpcBidiStream to indicate that it's done writing messages. The channel should respond to this by half-closing the stream.

Note: After receiving this signal no more write operations are permitted for the streaming RPCs. The server can still send messages, which should be forwarded with messageReceived().

See also QGrpcClientStream::writesDone and QGrpcBidiStream::writesDone.