mirror of https://github.com/qt/qtgrpc.git
QAbstractGrpcChannel: rework documentation
Task-number: QTBUG-125406 Pick-to: 6.9 6.8 Change-Id: I9cd36a674582f51e7319ec82ace238074df14352 Reviewed-by: Alexey Edelev <alexey.edelev@qt.io>
This commit is contained in:
Dennis Oberst
parent
1800de75c3
commit
f56e2039bc
|
|
@ -17,81 +17,65 @@ QT_BEGIN_NAMESPACE
|
|||
/*!
|
||||
\class QAbstractGrpcChannel
|
||||
\inmodule QtGrpc
|
||||
\brief The QAbstractGrpcChannel class is an interface that represents common
|
||||
\gRPC channel functionality.
|
||||
\brief The QAbstractGrpcChannel class provides an interface for
|
||||
implementing the transport layer of \gRPC operations.
|
||||
|
||||
Implement this interface to create your own custom channel for \gRPC
|
||||
transportation. We provide the QGrpcHttp2Channel, which is a fully featured
|
||||
implementation of the QAbstractGrpcChannel for HTTP/2 communication.
|
||||
Implement this interface to create a custom channel for \gRPC
|
||||
transportation. The QGrpcHttp2Channel class is provided as a fully featured
|
||||
implementation of QAbstractGrpcChannel for HTTP/2 communication.
|
||||
|
||||
\sa QGrpcChannelOptions, QGrpcHttp2Channel
|
||||
*/
|
||||
|
||||
/*!
|
||||
\fn virtual std::shared_ptr<QAbstractProtobufSerializer> QAbstractGrpcChannel::serializer() const = 0
|
||||
|
||||
This pure virtual function shall return a shared pointer
|
||||
to QAbstractProtobufSerializer.
|
||||
|
||||
This function is called to obtain the QAbstractProtobufSerializer used
|
||||
to perform serialization and deserialization of the message.
|
||||
This pure virtual function retrieves the QAbstractProtobufSerializer used
|
||||
for the serialization and deserialization of messages.
|
||||
*/
|
||||
|
||||
/*!
|
||||
\fn virtual void QAbstractGrpcChannel::call(std::shared_ptr<QGrpcOperationContext> operationContext) = 0
|
||||
\since 6.7
|
||||
|
||||
This pure virtual function is called by public QAbstractGrpcChannel::call
|
||||
method when making unary \gRPC call. The \a operationContext is the
|
||||
pointer to a channel side \l QGrpcOperationContext primitive that is
|
||||
connected with \l QGrpcCallReply primitive, that is used in
|
||||
\l QGrpcClientBase implementations.
|
||||
//! [abstract-rpc-desc]
|
||||
This pure virtual function is called when a user starts a new RPC through
|
||||
the generated client interface. The \a operationContext should be used to
|
||||
communicate with the corresponding RPC handler, which is a derived type of
|
||||
the QGrpcOperation object.
|
||||
|
||||
The function should implement the channel-side logic of unary call. The
|
||||
implementation must be asynchronous and must not block the thread where
|
||||
the function was called.
|
||||
This function should start the corresponding RPC on the channel side. The
|
||||
implementation must be asynchronous and must not block the calling thread.
|
||||
|
||||
\note It is the channel's responsibility to support and restrict the subset
|
||||
of features that its RPC type allows.
|
||||
//! [abstract-rpc-desc]
|
||||
*/
|
||||
|
||||
/*!
|
||||
\fn virtual void QAbstractGrpcChannel::serverStream(std::shared_ptr<QGrpcOperationContext> operationContext) = 0
|
||||
\since 6.7
|
||||
|
||||
This pure virtual function that the starts of the server-side stream. The
|
||||
\a operationContext is the pointer to a channel side
|
||||
\l QGrpcOperationContext primitive that is connected with \l QGrpcServerStream
|
||||
primitive, that is used in \l QGrpcClientBase implementations.
|
||||
|
||||
The function should implement the channel-side logic of server-side stream.
|
||||
The implementation must be asynchronous and must not block the thread where
|
||||
the function was called.
|
||||
\include qabstractgrpcchannel.cpp abstract-rpc-desc
|
||||
*/
|
||||
|
||||
/*!
|
||||
\fn virtual void QAbstractGrpcChannel::clientStream(std::shared_ptr<QGrpcOperationContext> operationContext) = 0
|
||||
\since 6.7
|
||||
|
||||
This pure virtual function that the starts of the client-side stream. The
|
||||
\a operationContext is the pointer to a channel side
|
||||
\l QGrpcOperationContext primitive that is connected with
|
||||
\l QGrpcClientStream primitive, that is used in \l QGrpcClientBase.
|
||||
|
||||
The function should implement the channel-side logic of client-side stream.
|
||||
The implementation must be asynchronous and must not block the thread where
|
||||
the function was called.
|
||||
\include qabstractgrpcchannel.cpp abstract-rpc-desc
|
||||
*/
|
||||
|
||||
/*!
|
||||
\fn virtual void QAbstractGrpcChannel::bidiStream(std::shared_ptr<QGrpcOperationContext> operationContext) = 0
|
||||
\since 6.7
|
||||
|
||||
This pure virtual function that the starts of the bidirectional stream. The
|
||||
\a operationContext is the pointer to a channel side
|
||||
\l QGrpcOperationContext primitive that is connected with
|
||||
\l QGrpcBidiStream primitive, that is used in \l QGrpcClientBase.
|
||||
|
||||
The function should implement the channel-side logic of bidirectional
|
||||
stream. The implementation must be asynchronous and must not block the
|
||||
thread where the function was called.
|
||||
\include qabstractgrpcchannel.cpp abstract-rpc-desc
|
||||
*/
|
||||
|
||||
/*!
|
||||
Default-constructs the QAbstractGrpcChannel.
|
||||
*/
|
||||
QAbstractGrpcChannel::QAbstractGrpcChannel()
|
||||
: d_ptr(std::make_unique<QAbstractGrpcChannelPrivate>(QGrpcChannelOptions{}))
|
||||
{
|
||||
|
|
@ -99,21 +83,32 @@ QAbstractGrpcChannel::QAbstractGrpcChannel()
|
|||
|
||||
/*!
|
||||
\since 6.8
|
||||
Constructs QAbstractGrpcChannel using the private message implementation
|
||||
from the derived class.
|
||||
\internal
|
||||
|
||||
Constructs the QAbstractGrpcChannel using the Private implementation to
|
||||
reuse the d_ptr.
|
||||
*/
|
||||
QAbstractGrpcChannel::QAbstractGrpcChannel(QAbstractGrpcChannelPrivate &dd) : d_ptr(&dd)
|
||||
{
|
||||
}
|
||||
|
||||
/*!
|
||||
Constructs the QAbstractGrpcChannel using the specified \a options.
|
||||
*/
|
||||
QAbstractGrpcChannel::QAbstractGrpcChannel(const QGrpcChannelOptions &options)
|
||||
: d_ptr(std::make_unique<QAbstractGrpcChannelPrivate>(options))
|
||||
{
|
||||
}
|
||||
|
||||
/*!
|
||||
Destroys the QAbstractGrpcChannel.
|
||||
*/
|
||||
QAbstractGrpcChannel::~QAbstractGrpcChannel() = default;
|
||||
|
||||
/*!
|
||||
Returns QGrpcChannelOptions used by the channel.
|
||||
Returns the options utilized by the channel.
|
||||
|
||||
\sa setChannelOptions
|
||||
*/
|
||||
const QGrpcChannelOptions &QAbstractGrpcChannel::channelOptions() const & noexcept
|
||||
{
|
||||
|
|
@ -147,12 +142,13 @@ void QAbstractGrpcChannel::setChannelOptions(QGrpcChannelOptions &&options)
|
|||
|
||||
/*!
|
||||
\internal
|
||||
Function constructs \l QGrpcCallReply and \l QGrpcOperationContext
|
||||
primitives and makes the required for unary \gRPC call connections
|
||||
between them.
|
||||
|
||||
The function should not be called directly, but only by
|
||||
\l QGrpcClientBase implementations.
|
||||
//! [private-rpc-desc]
|
||||
This function is called when a user initiates a new RPC through the
|
||||
generated client interface via QGrpcClientBase. It creates the
|
||||
QGrpcOperationContext and the corresponding RPC handler, establishing the
|
||||
required connections between the two.
|
||||
//! [private-rpc-desc]
|
||||
*/
|
||||
std::unique_ptr<QGrpcCallReply> QAbstractGrpcChannel::call(QLatin1StringView method,
|
||||
QLatin1StringView service,
|
||||
|
|
@ -179,12 +175,7 @@ std::unique_ptr<QGrpcCallReply> QAbstractGrpcChannel::call(QLatin1StringView met
|
|||
|
||||
/*!
|
||||
\internal
|
||||
Function constructs \l QGrpcServerStream and \l QGrpcOperationContext
|
||||
primitives and makes the required for server-side \gRPC stream connections
|
||||
between them.
|
||||
|
||||
The function should not be called directly, but only by
|
||||
\l QGrpcClientBase implementations.
|
||||
\include qabstractgrpcchannel.cpp private-rpc-desc
|
||||
*/
|
||||
std::unique_ptr<QGrpcServerStream>
|
||||
QAbstractGrpcChannel::serverStream(QLatin1StringView method, QLatin1StringView service,
|
||||
|
|
@ -210,12 +201,7 @@ QAbstractGrpcChannel::serverStream(QLatin1StringView method, QLatin1StringView s
|
|||
|
||||
/*!
|
||||
\internal
|
||||
Function constructs \l QGrpcClientStream and \l QGrpcOperationContext
|
||||
primitives and makes the required for client-side \gRPC stream connections
|
||||
between them.
|
||||
|
||||
The function should not be called directly, but only by
|
||||
\l QGrpcClientBase.
|
||||
\include qabstractgrpcchannel.cpp private-rpc-desc
|
||||
*/
|
||||
std::unique_ptr<QGrpcClientStream>
|
||||
QAbstractGrpcChannel::clientStream(QLatin1StringView method, QLatin1StringView service,
|
||||
|
|
@ -233,12 +219,7 @@ QAbstractGrpcChannel::clientStream(QLatin1StringView method, QLatin1StringView s
|
|||
|
||||
/*!
|
||||
\internal
|
||||
Function constructs \l QGrpcBidiStream and \l QGrpcOperationContext
|
||||
primitives and makes the required for bidirectional \gRPC stream connections
|
||||
between them.
|
||||
|
||||
The function should not be called directly, but only by
|
||||
\l QGrpcClientBase.
|
||||
\include qabstractgrpcchannel.cpp private-rpc-desc
|
||||
*/
|
||||
std::unique_ptr<QGrpcBidiStream> QAbstractGrpcChannel::bidiStream(QLatin1StringView method,
|
||||
QLatin1StringView service,
|
||||
|
|
|
|||
Loading…
Reference in New Issue