// Copyright (C) 2022 The Qt Company Ltd.
// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
/*!
    \page qtgrpc-index.html
    \title Qt GRPC
    \keyword Qt GRPC
    \ingroup frameworks-technologies
    \brief Provides support for communicating with gRPC services.

    Qt GRPC is the client-side implementation that, together with the \l {Qt
    Protobuf} module, allows the definition of messages and services in \c .proto
    files, which then use the provided code generators to generate client code
    that allows the access for fields and gRPC services in the Qt framework. The
    code generated by Qt GRPC enables the client-side to communicate with a
    gRPC server (regardless of whether the server uses Qt) by sending calls or
    streaming messages.

    \section1 Overview

    gRPC is a cross-platform high performance Remote
    Procedure Call (RPC) framework, that generates client/server
    bindings for a lot of languages. Usually, you use it to connect
    services in a microservices-style architecture or to connect
    mobile applications and browsers to backend services.
    The gRPC clients and servers can run and talk to each other in
    various environments, and you can write in any of gRPC’s
    supported languages. For more details see
    \l {https://grpc.io/docs/what-is-grpc/introduction/} {gRPC Introduction}

    \section1 Using the Module

    \section2 Module prerequisites:

    \list
        \li \c protoc, the Google protocol buffers compiler, must be installed
            to generate code from \c .proto specification files.
            See \l {https://grpc.io/docs/protoc-installation/}
            {Protoc Installation}.
        \li If you also install the gRPC libraries, you'll be able to use
            native gRPC channels.
            See \l {https://grpc.io/docs/languages/cpp/quickstart/}
            {gRPC for C++} for details.
        \li \l {OpenSSL Toolkit} may be needed.
    \endlist
    \note Check the \l {Example of installation for Windows using vcpkg}
    to see how to install \c gRPC and \c Protobuf and to run Qt GRPC examples.

    To start working with the Qt GRPC functionality you should define
    required services and messages in a \c .proto file.
    See the \c {helloworld.proto} example:
    \badcode
    // The service definition.
    service Salutation {
      // Sends a greeting
      rpc SendHello (HelloRequest) returns (HelloReply) {}
    }

    // The request message containing the user's name.
    message HelloRequest {
      string name = 1;
    }

    // The response message containing the greetings
    message HelloReply {
      string message = 1;
    }
    \endcode

    To add a \c .proto file to a Qt-based project and generate the
    required source code, you should use the \c protoc compiler
    with the \c qtgrpcgen and \c qtprotobufgen Qt plugins.
    \list
        \li The \l {The qtprotobufgen Tool} {Qt Protobuf plugin}
            generates classes that you can use to serialize
            and deserialize their associated protobuf messages.
        \li The \l {The qtgrpcgen Tool} {Qt GRPC plugin} generates
            gRPC client classes from the proto file.
    \endlist

    This processing of \c proto files into source code can be automated
    in CMake using the following commands provided by Qt:
    \list
        \li \l {qt_add_protobuf}
        \li \l {qt_add_grpc}
    \endlist

    As a result, the full example of a CMake project file,
    that uses Qt GRPC functionality shall be:

    \include qt-add-grpc-example.qdocinc 0

    \section2 QML API

    \include {module-use.qdocinc} {using the qml api} {QtGrpc}

    \section2 C++ API

    \include {module-use.qdocinc} {using the c++ api}

    \section3 Building with CMake

    \include {module-use.qdocinc} {building with cmake} {Grpc}


    \section1 Articles and Guides
    \list
        \li \l{CMake Commands in Qt6 GRPC}
        \li \l{Client Methods of the Qt GRPC Service}
    \endlist

    \section1 References
    \list
        \li \l{Qt GRPC QML Types}{Qt GRPC Quick}
        \li \l{Qt GRPC C++ Classes}{C++ Classes}
    \endlist

    \section1 Licenses and Trademarks
    Qt GRPC is available under commercial licenses from \l{The Qt Company}.
    In addition, it is available under the
    \l {GNU General Public License, version 3}.
    See \l{Qt Licensing} for further details.

    gRPC\reg is a registered trademark of The Linux Foundation.
    Please see \l https://grpc.io/ for more information.

    \section1 Examples
    \list
        \li \l {Qt GRPC Examples}
    \endlist

    \section1 Licenses and Attributions

    The Qt GRPC module is available under commercial licenses from \l{The Qt Company}.
    In addition, it is available under free software licenses:
    The \l{GNU General Public License, version 3}.
    See \l{Qt Licensing} for further details.

    Furthermore, Qt GRPC in Qt \QtVersion may contain third party
    modules under the following permissive licenses:

    \generatelist{groupsbymodule attributions-qtgrpc-examples}
*/
