Запускаем Protobuf на С++ в VS

Protobuf достаточно распространённый протокол сериализации структурированных данных, однако для многих не секрет, что запуск чего-либо на плюсах бывает сопряжено с испытаниями, если ты новичок. Поэтому, я решил написать небольшой туториал, который будет содержать максимально безболезненный путь всего необходимого для работы с Protobuf, а так же, предоставить необходимый минимум, который позволит понять как формируются посылки и как работать с самими сообщениями.

Краткое описание

Сообщения в protobuf представляет из себя закодированную последовательность бит из ключей и значений. Ключи определяются с помощью номера определённого в файле .proto и кода типа переменной. Файл .proto определяет поля каждого сообщения. Сам файл .proto преобразуется в классы, для работы с сериализацией и десериализацией данных.

Подготовка к работе с protobuf

Простой ликбез прошли, теперь можно задаться вопросом, а что нам понадобится для того, чтобы самим поковырять protobuf. А всё просто, нам понадобится:

• CMake

• VS 2019

• Проект Protobuf

Сборка проекта Protobuf с github

Прежде всего скачаем Protobuf с github. В разделе Release находим файл вида protobuf-cpp-version.zip. На момент начала написания статьи использовалась версия 3.19.0, но процесса сборки это не меняет.

Когда мы скачали архив, его необходимо подготовить для сборки в vs, на мой взгляд - это самый простой способ сборки проекта, во всяком случае для тех, у кого лапки. Кому интересно изучить информацию про установку и сборку protobuf подробнее, то можно почитать файл readme в директории protobuf/cmake/README.md, в статье же будет представлена выжимка необходимого минимума.

Для команд написаных ниже, необходимо использовать командную строку от VS. В моём случае она называлась x86_x64 Cross Tools Command Promt for VS 2019. Если использовать стандартную командную строку, то возможны лишние манипуляции.

В открытой командной строке необходимо перейти в директорию с нашим распакованным protobuf.

В данном случае C:\Path\to\ - адрес до нашего распакованного архива. Для тех, кто не помнит как обратиться быстро в самое начало директории локального диска или же перейти в другой, тогда в командную строку надо прописать что-то вроде:

 C:\Program Files (x86)\Microsoft Visual Studio\2019\Community>E:
 E:\>

Теперь, повторяем команды из readme. Если вы только установили СMake, стоит обратить внимание на то, что вы указали в path путь к вашему cmake, проверить это можно с помощью простой команды:

E:\AllWs\vs\protoExample\proto_settings> cmake --version
cmake version 3.17.0-rc1

Когда мы убедились, что всё хорошо, приступаем к подготовке нашего проекта.

 C:\Path\to\protobuf\cmake>mkdir build & cd build
 C:\Path\to\protobuf\cmake\build>
 C:\Path\to\protobuf\cmake\build>mkdir solution & cd solution
 C:\Path\to\protobuf\cmake\build\solution>cmake -G "Visual Studio 16 2019" ^
 -DCMAKE_INSTALL_PREFIX=../../../../install ^
 ../..

Часть команд мы пропустили для простоты и сразу перепрыгнули к созданию проекта в VS19. После чего мы можем у себя обнаружить в папке solution множество файлов, и нам необходимо открыть файл *.sln. Открыв его мы можем увидеть:

Собираем INSTALL. Теперь переходим в папку, в которой у нас был распакован архив с Protobuf, там у нас должна появиться папка install, и там нас интересуют следующие папки:

• bin

• include

• lib

Сборка под release и debug сгенерирует разные файлы lib:

• libprotobuf.lib

• libprotobufd.lib

Подготовка VS под запуск примеров с protobuf

Для описания данных protobuf используется файл с расширением *.proto. Однако, файл с таким расширением нельзя просто так взять и впихнуть в проект, для этого необходимо этот файл преобразовать с помощью полученого на предыдущем этапе файла, расположенного в папке bin, с названием protoc.exe. Для удобства создадим папку, в которую мы скинем protoc.exe. Туда же добавим:

syntax = "proto2";

package tutorial;

message Person {
  optional string name = 1;
  optional int32 id = 2;
  optional string email = 3;

  enum PhoneType {
    MOBILE = 0;
    HOME = 1;
    WORK = 2;
  }

  message PhoneNumber {
    optional string number = 1;
    optional PhoneType type = 2 [default = HOME];
  }

  repeated PhoneNumber phones = 4;
}

message AddressBook {
  repeated Person people = 1;
}

Теперь для преобразования файла addressbook.proto запускаем команду

protoc_path\protoc.exe --cpp_out=. addressbook.proto

Кому лень, можно создать просто файл формата *.bat, в который поместим следующий код:

@set file_name=addressbook
@set mypath=%cd%
@if exist %file_name%.proto ( 
	%mypath%\protoc.exe --cpp_out=. %file_name%.proto
	@echo %file_name%.pb.cc and %file_name%.pb.h created)
@pause

В этой директории у нас появятся addressbook.pb.cc и addressbook.pb.h.

Подготовительный этап у нас закончен. У нас теперь есть всё, чтобы запустить примеры, предложенные на официальном сайте. Поэтому, мы по старинке создаём проект в VS, в main файл добавляем код. Я немножко изменил проект, чтобы можно было проще запускать предложенные примеры по очереди.

#include <iostream>
#include <fstream>
#include <string>
#include "addressbook.pb.h"
using namespace std;
#define READ_EXAMPLE 1
#define WRITE_EXAMPLE 2
#define TYPE_EXAMPLE WRITE_EXAMPLE

// This function fills in a Person message based on user input.
void PromptForAddress(tutorial::Person* person) {
    cout << "Enter person ID number: ";
    int id;
    cin >> id;
    person->set_id(id);
    cin.ignore(256, '\n');

    cout << "Enter name: ";
    getline(cin, *person->mutable_name());

    cout << "Enter email address (blank for none): ";
    string email;
    getline(cin, email);
    if (!email.empty()) {
        person->set_email(email);
    }

    while (true) {
        cout << "Enter a phone number (or leave blank to finish): ";
        string number;
        getline(cin, number);
        if (number.empty()) {
            break;
        }

        tutorial::Person::PhoneNumber* phone_number = person->add_phones();
        phone_number->set_number(number);

        cout << "Is this a mobile, home, or work phone? ";
        string type;
        getline(cin, type);
        if (type == "mobile") {
            phone_number->set_type(tutorial::Person::MOBILE);
        }
        else if (type == "home") {
            phone_number->set_type(tutorial::Person::HOME);
        }
        else if (type == "work") {
            phone_number->set_type(tutorial::Person::WORK);
        }
        else {
            cout << "Unknown phone type.  Using default." << endl;
        }
    }

}

// Iterates though all people in the AddressBook and prints info about them.
void ListPeople(const tutorial::AddressBook& address_book) {
    for (int i = 0; i < address_book.people_size(); i++) {
        const tutorial::Person& person = address_book.people(i);

        cout << "Person ID: " << person.id() << endl;
        cout << "  Name: " << person.name() << endl;
        if (person.has_email()) {
            cout << "  E-mail address: " << person.email() << endl;
        }

        for (int j = 0; j < person.phones_size(); j++) {
            const tutorial::Person::PhoneNumber& phone_number = person.phones(j);

            switch (phone_number.type()) {
            case tutorial::Person::MOBILE:
                cout << "  Mobile phone #: ";
                break;
            case tutorial::Person::HOME:
                cout << "  Home phone #: ";
                break;
            case tutorial::Person::WORK:
                cout << "  Work phone #: ";
                break;
            }
            cout << phone_number.number() << endl;
        }
    }
}


// Main function:  Reads the entire address book from a file,
//   adds one person based on user input, then writes it back out to the same
//   file.
int main(int argc, char* argv[]) {
    // Verify that the version of the library that we linked against is
    // compatible with the version of the headers we compiled against.
    GOOGLE_PROTOBUF_VERIFY_VERSION;

    if (argc != 2) {
        cerr << "Usage:  " << argv[0] << " ADDRESS_BOOK_FILE" << endl;
        return -1;
    }

    tutorial::AddressBook address_book;

#if(TYPE_EXAMPLE == WRITE_EXAMPLE)
    {
        // Read the existing address book.
        fstream input(argv[1], ios::in | ios::binary);
        if (!input) {
            cout << argv[1] << ": File not found.  Creating a new file." << endl;
        }
        else if (!address_book.ParseFromIstream(&input)) {
            cerr << "Failed to parse address book." << endl;
            return -1;
        }
    }

    // Add an address.
    PromptForAddress(address_book.add_people());
    PromptForAddress(address_book.add_people());

    {
        // Write the new address book back to disk.
        fstream output(argv[1], ios::out | ios::trunc | ios::binary);
        if (!address_book.SerializeToOstream(&output)) {
            cerr << "Failed to write address book." << endl;
            return -1;
        }
    }

#elif(TYPE_EXAMPLE == READ_EXAMPLE)

    {
        // Read the existing address book.
        fstream input(argv[1], ios::in | ios::binary);
        if (!address_book.ParseFromIstream(&input)) {
            cerr << "Failed to parse address book." << endl;
            return -1;
        }
    }

    ListPeople(address_book);

#endif
    // Optional:  Delete all global objects allocated by libprotobuf.
    google::protobuf::ShutdownProtobufLibrary();

    return 0;
}

Затем в проект добавляем наши сгенерированные файлы с помощью protoc.exe. Можно это сделать с помощью горячих клавиш Alt+Shift+A. Добавив наши файлы мы можем обнаружить, что чего-то нам для работы нашего примера не хватает, тут мы обращаемся к нашим сгенерированными папкам inclune и lib. В папке lib нас интересует libprotobuf.lib (для сборки Release) или libprotobufd.lib (для сборки debug), добавляем в наш проект.

После чего мы должны добавить в наш проект файлы из include. Просто кидаем в наш проект папку include, и указываем в "Свойства конфигурации → С/С++ → Общие → Дополнительные каталоги включаемых файлов" путь до папки include.

В примере функция main принимает аргументы, в примере это название файла, в который мы будем писать и из которого будем читать, чтобы можно было запускать из среды, мы добавим в свойства проекта название файла. Заходим в "Свойства конфигурации → Отладка" в поле "Аргументы команды" вписываем название файла, я обозвал его как "addressbook.bin".

Теперь осталось самое последнее, указать как собирать подключенную библиотеку. Заходим в "Свойства конфигурации → Создание кода" в поле "Библиотека времени выполнения" выбираем "Многопоточная/МТ". На этом подготовка окончена, можно запускать примеры.

Разбор примера

Вот, наконец-то, подготовительная часть закончилась и можно приступать к разбору примера.

Сгенерированные методы после конвертации файла *.proto

В предыдущем разделе, когда мы генерировали классы сообщений protobuf, мы не вдавались в результат их преобразования. Поэтому я хотел бы немного затронуть эту тему. Для примера возьмём поле optional int32 id = 2; Если мы зайдём в сгенерированный заголовочник, то увидим:

// optional int32 id = 2;
inline bool Person::_internal_has_id() const;
inline bool Person::has_id() const;
inline void Person::clear_id();
inline int32_t Person::_internal_id() const;
inline int32_t Person::id() const;
inline void Person::_internal_set_id(int32_t value);
inline void Person::set_id(int32_t value);

Определение этих методов я скрыл, за ненадобностью, но если убрать из расчёта приватные методы, их имена начинаются с нижнего подчёркивания, то остаётся не так много методов. Из названия публичных методов понятно какие методы за что отвечают.

Для переменных с другим модификатором, например repeated, появляется дополнительный метод формата add_variableName(), который отвечает за добавление новых переменных этого типа, метод оканчивающийся на _size, для определения размера и обращение по индексу. Кроме этого, по всем элементам можно пробежаться с помощью конструкции range based for, например так:

    tutorial::Person person;
    person.add_phones()->set_number("numb1");
    person.add_phones()->set_number("numb2");
    for (auto& phone : pers.phones())
    {
        std::cout << phone.number() << std::endl;
    }

Обратите внимание, класс Person создаётся через пространство имён tutorial. Как мы помним, в файле *.proto мы указали package tutorial. Это не было необходимо, однако, мы тогда в глобальное пространство имён вынесем достаточно много внутренних функций.

С переменными типа string можно работать не только через метод set, а также через *mutable методы. Вот пример работы с таким методом:

        tutorial::Person person;
        person.set_name("name");
        *person.mutable_name() += " surname ";
        std::cout << person.name();

Классы с сообщениями наследуются публично от класса Message. В нём определено много различных методов для сериализации, которые имеют имена начинающиеся с Serialize, а для десериализации достаточно использовать метод, начинающийся с Parse, например для сериализации в строку и десериализации из строки можно выполнить следующий код:

    tutorial::AddressBook addr_book1;
    addr_book1.add_people()->set_email("555-555-555");
    std::string Serialized = addr_book1.SerializeAsString();
    
    tutorial::AddressBook addr_book2;
    addr_book2.ParseFromString(Serialized);

Разбор бинарного представления сериализированных данных

Для начала запустим проект с конфигурацией с записью и попробуем разобраться в том, что происходит

#define TYPE_EXAMPLE WRITE_EXAMPLE

Пример для записи я немного редактировал двумя вызовами добавления элементов в базу.

Запускаем программу и вводим данные с консоли.

Enter person ID number: 170
Enter name: name1
Enter email address (blank for none): mail1
Enter a phone number (or leave blank to finish): 1234567
Is this a mobile, home, or work phone? mobile
Enter a phone number (or leave blank to finish):
Enter person ID number: 85
Enter name: name2
Enter email address (blank for none): mail2
Enter a phone number (or leave blank to finish): 7654321
Is this a mobile, home, or work phone? mobile
Enter a phone number (or leave blank to finish):

Теперь посмотрим, что же мы увидим в созданном файле.

Какая-то абракадабра в декодированном тексте, зато в hex формате всё очень даже понятно, во всяком случае для десериализатора. Теперь давайте разберёмся с тем, как вообще наши данные должны расшифровываться.

Для более простой расшифровки данных я выбрал 170 и 85 в качестве id, поскольку эти величины легче найти в бинарном файле, да и int32 проще всего зашифрованы. В hex эти числа представлены как AA и 55. В protobuf данные хранятся по принципу ключ - значение. Ключ определяется по формуле:

field_number - номер у переменной в описании структуры данных в файле *.proto. wire_type определяется по этой табличке

Воспользовавшись формулой выше определим, какой ключ должен быть перед переменной id key = 2 << 3 | 0 = 0x0010

Это же число мы и видим в декодированом файле.

Давайте сейчас попробуем определить ключ для переменной типа string, это будет поле name. Ключ для этой переменной будет 1 << 3 | 2 = 0x0A. Замечаем, что перед переменными name1 и name2 (0x04 и 0x24 байт) стоит не 0x0A а 0x05. Это основная особенность подобных типов, они могут быть любой длины, вот 0x05 и отвечает за количество байт на эту переменную. Для таких типов идёт сначала ключ, потом количество байт.

Запускаем пример на чтение.

#define TYPE_EXAMPLE READ_EXAMPLE

И теперь мы увидим данные, которые мы записали в файл.

Ну вот и всё. Надеюсь эта статья поможет кому-то начать осваивать protobuf с с++.

Спасибо за внимание.