Qt Protobuf 6.6.1

- Qt 6.6
- Qt Protobuf
- Qt 6.6.1 Reference Documentation

# Qt Protobuf

The Qt Protobuf generator plugin generates Qt-based classes from `.proto` files. You can use the classes to serialize and deserialize their associated protobuf messages.

## Overview

### What are protocol buffers?

Protocol buffers are a language-neutral, platform-neutral, and extensible mechanism for serializing structured data, which is compact and easy to use:

- A user defines the structure of data in `.proto` files.
- Proto compiler is invoked at build time on `.proto` files to generate code in various programming languages.

The provided format is suitable for network traffic or long-term data storage.

### Which problems do protocol buffers solve?

Protocol buffers provide a serialization format for packets of typed and structured data that are up to a few megabytes in size. Moreover, it can be extended with new information without invalidating existing data or requiring code to be updated. For more information, see Protocol Buffers Overview.

### What are the benefits of using Qt Protobuf?

You can use a Protocol buffers mechanism in any Qt-based project:

- No need to call a protocol buffer compiler explicitly.
- No need to integrate generated code into project tree manually.
- Convenient serialization and deserialization API.
- Integrated properties mechanism for generated protobuf messages.
- Integrated gRPC-client support (see QtGrpc module).
- Integrated QML-types support for generated protobuf messages.
- Enabled using Qt Core and Qt GUI types as a part of *.proto schema.

### Incoming features

- Enabling gRPC-server support.

## Using Qt Protobuf

Google protocol buffers provide a generator called `protoc` that supports extensions. The qtprotobufgen Tool is an extension for `protoc` and requires that you install `protoc` on your host system. For more information about the installation, see Protoc Installation.

Example of installation for Linux, using apt:

     apt install -y protobuf-compiler
     protoc --version  # Ensure compiler version is 3+

For more information about component API usage, see CMake API.

## CMake API

- CMake Commands in Qt6 Protobuf

## QML-types support

With the generator plugin, you can register protobuf messages in the QML context. To register the type, use the `QML` and `QML_URI` generation keys. See API details in qt_add_protobuf command and API usage example QML extended protobuf.

Registered protobuf messages are available in the QML context, like built-in Q_GADGET types. The registration is done via the QML module.

### Protobuf message duplicates

You should avoid declaration of protobuf message duplicates in your `*.proto` files or do it wisely. In case your application uses several identical protobuf message names declared inside different protobuf packages, they can contradict each other in auto-generated code. In example below, 2 different proto packages `qtprotobufnamespace` and `qtprotobufnamespace1.nested` use the same proto message `NestedFieldMessage`. The file `nested.proto`:

     syntax = "proto3";

     package qtprotobufnamespace;
     import "externalpackage.proto";

     message NestedFieldMessage {
         sint32 testFieldInt = 1;
     }

The file `nestedspace1.proto`:

     syntax = "proto3";

     package qtprotobufnamespace1.nested;

     message NestedFieldMessage {
         message NestedMessage {
             sint32 field = 1;
         }
         NestedMessage nested = 1;
     }

In case there is no possibility to avoid name duplicates among packages, then put duplicated messages in different QML modules and use a <Qualifier> for each QML module import, see Module (Namespace) Imports. Below the example how to add protobuf packages into different QML modules:

     # qtprotobufnamespace QML module
     qt_add_protobuf(nestedtypes_qtprotobuf_qml
         PROTO_FILES
             nested.proto
         QML
         QML_URI
             qtprotobufnamespace
         OUTPUT_DIRECTORY "${CMAKE_CURRENT_BINARY_DIR}/qt_protobuf_gen1"
     )

     ....................................

     # qtprotobufnamespace1.nested QML module
     qt_add_protobuf(nestedspace_qml
         PROTO_FILES
             nestedspace1.proto
         QML
         QML_URI
             qtprotobufnamespace1.nested
         OUTPUT_DIRECTORY "${CMAKE_CURRENT_BINARY_DIR}/qt_protobuf_gen2"
     )

The <Qualifier> usage example:

     import qtprotobufnamespace as NestedFieldMessages
     import qtprotobufnamespace1.nested as FieldMessages_Nested1

     .....................................
     .....................................
     .....................................

     property NestedFieldMessages.nestedFieldMessage fieldMsg1;
     property FieldMessages_Nested1.nestedFieldMessage fieldMsg2;

Note: The usage of duplicates will trigger a warning at compilation time.

### QML keywords handling

Pay attention to the keywords that are reserved in QML or JavaScript context, but not reserved in *.proto context. Fields with names that are reserved by QML will be silently extended by `_proto` suffix by the generator plugin. For example, `id`, `property`, and `import` are reserved keywords. They will be replaced by `id_proto`, `property_proto`, `import_proto`:

     message MessageUpperCaseReserved {
         sint32 Import = 1;
         sint32 Property = 2;
         sint32 Id = 3;
     }

Generated code output:

     Q_PROPERTY(QtProtobuf::sint32 import_proto READ import_proto ...)
     Q_PROPERTY(QtProtobuf::sint32 property_proto READ property_proto ...)
     Q_PROPERTY(QtProtobuf::sint32 id_proto READ id_proto ...)

Also, enum values cannot begin with a lower case letter. The generator plugin will capitalize the first letter in code output. See the `*.proto` example below:

     enum LowerCaseEnum {
         enumValue0 = 0;
         enumValue1 = 1;
         enumValue2 = 2;
     }

Generated code output:

     enum LowerCaseEnum {
         EnumValue0 = 0,
         EnumValue1 = 1,
         EnumValue2 = 2,
     };
     Q_ENUM(LowerCaseEnum)

Also, enum fields cannot begin with an underscore symbol. Such fields will be generated as is, but will be undefined in the QML context, unless the QML engine will allow registering them in the future. See the `*.proto` example below:

     enum UnderScoreEnum {
         _enumUnderscoreValue0 = 0;
         _EnumUnderscoreValue1 = 1;
     }

Generated output:

     enum UnderScoreEnum {
         _enumUnderscoreValue0 = 0,
         _EnumUnderscoreValue1 = 1,
     };
     Q_ENUM(UnderScoreEnum)

For more information about the QML properties syntax, check Defining Property Attributes.

## Class Documentation

C++ Classes

## Examples

- Qt Protobuf Examples