QGrpcOperation Class | Qt GRPC | Qt 6.12.0
Description: The QGrpcOperation class provides common operations to handle the gRPC communication from the client side.
Keywords: class

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

# QGrpcOperation Class

The QGrpcOperation class provides common operations to handle the gRPC™ communication from the client side. More...

Header: | `#include <QGrpcOperation>`
CMake: | `find_package(Qt6 REQUIRED COMPONENTS Grpc)` `target_link_libraries(mytarget PRIVATE Qt6::Grpc)`
Since: | Qt 6.5
Inherits: | QObject
Inherited By: | QGrpcBidiStream, QGrpcCallReply, QGrpcClientStream, and QGrpcServerStream

- List of all members, including inherited members

## Public Functions

virtual | ~QGrpcOperation() override
bool | isFinished() const
`(until 6.13)` const QHash<QByteArray, QByteArray> & | metadata() const &
QLatin1StringView | method() const
std::optional<T> | read() const
`(since 6.8)` bool | read(QProtobufMessage *message) const
QMetaType | responseMetaType() const
`(since 6.10)` const QMultiHash<QByteArray, QByteArray> & | serverInitialMetadata() const &
`(since 6.10)` const QMultiHash<QByteArray, QByteArray> & | serverTrailingMetadata() const &

## Public Slots

void | cancel()

## Signals

void | finished(const QGrpcStatus &status)
`(since 6.11)` void | serverInitialMetadataReceived(const QMultiHash<QByteArray, QByteArray> &metadata)

## Detailed Description

QGrpcOperation serves as the base class for the four gRPC™ method types: QGrpcCallReply (unary calls), QGrpcServerStream (server streaming), QGrpcClientStream (client streaming), and QGrpcBidiStream (bidirectional streaming). It provides a common interface for interacting with these remote procedure calls (RPCs).

Each QGrpcOperation corresponds to a specific RPC requested through the generated client interface.

For a high-level overview, refer to the Qt GRPC Client Guide.

## Member Function Documentation

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

Destroys the QGrpcOperation.

### `[slot]` void QGrpcOperation::cancel()

Tries to cancel the RPC immediately. Successful cancellation cannot be guaranteed. Emits the finished signal with a Cancelled status code.

See also QGrpcOperationContext::cancelRequested.

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

This signal is emitted when a previously started RPC has finished. The status provides additional information about the outcome of the RPC.

After this signal is received, no further write or read operations should be performed on the operation object. At this point, it is safe to reuse or destroy the RPC object.

Note: This signal is emitted only once, and in most cases, you will want to disconnect right after receiving it to avoid issues, such as lambda captures not being destroyed after receiving the signal. An easy way to achieve this is by using the SingleShotConnection connection type. See Single Shot RPCs for further details.

### `[noexcept]` bool QGrpcOperation::isFinished() const

Returns true if this operation has finished, meaning that no more operations can happen on the corresponding RPC, otherwise returns false.

### `[noexcept, until 6.13]` const QHash<QByteArray, QByteArray> &QGrpcOperation::metadata() 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: 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 serverInitialMetadata() and serverTrailingMetadata().

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

Returns the method name associated with this RPC operation.

### template <typename T> requires QtProtobuf::if_protobuf_message<T> std::optional<T> QGrpcOperation::read() const

Reads a message from a raw byte array stored within this operation object.

Returns an optional deserialized message. On failure, `std::nullopt` is returned.

Note: This function only participates in overload resolution if `T` is a subclass of QProtobufMessage.

See also read(QProtobufMessage *).

### `[since 6.8]` bool QGrpcOperation::read(QProtobufMessage *message) const

Reads a message from a raw byte array stored within this operation object.

The function writes the deserialized value to the message pointer.

If the deserialization is successful, this function returns `true`. Otherwise, it returns `false`.

This function was introduced in Qt 6.8.

See also read().

### QMetaType QGrpcOperation::responseMetaType() const

Returns the meta type of the RPC response message.

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

The metadata may contain multiple entries under the same key.

This function was introduced in Qt 6.10.

See also serverInitialMetadataReceived() and serverTrailingMetadata().

### `[signal, since 6.11]` void QGrpcOperation::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: 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.

This function was introduced in Qt 6.11.

See also serverInitialMetadata().

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

The metadata may contain multiple entries under the same key.

This function was introduced in Qt 6.10.

See also serverInitialMetadata().