NanoPB: Як обробляти вкладені повідомлення в C

Див. також: Версія для C++: Як обробляти вкладені повідомлення в C++

NanoPB — це оптимізована за розміром коду реалізація Protocol Buffers для вбудованих систем. Ця публікація показує, як обробляти вкладені повідомлення в C за допомогою NanoPB.

Визначення Proto

Спочатку створіть файл .proto з вкладеними повідомленнями:

nested.proto

syntax = "proto3";

package example;

message Address {
  string street = 1;
  string city = 2;
  string country = 3;
}

message Person {
  string name = 1;
  uint32 age = 2;
  Address address = 3;
}

Генерація коду NanoPB

Згенеруйте код NanoPB з файлом .options для вказівки розмірів строкових буферів:

Створіть nested.options:

nested.options

example.Address.street max_size:64
example.Address.city max_size:32
example.Address.country max_size:32
example.Person.name max_size:64

Потім згенеруйте:

generate_nanopb_nested.sh

protoc --nanopb_out=. nested.proto

Це згенерує nested.pb.h та nested.pb.c.

Приклад на C

Ось повний приклад на C для обробки вкладених повідомлень:

nested_example.c

#include <stdio.h>
#include <stdint.h>
#include <string.h>
#include "nested.pb.h"
#include "pb_encode.h"
#include "pb_decode.h"

int main() {
    // Буфер для закодованого повідомлення
    uint8_t buffer[256];
    size_t message_length;
    
    // --- КОДУВАННЯ ---
    example_Person person = example_Person_init_zero;
    
    // Встановити значення вкладеного повідомлення
    strncpy(person.name, "John Doe", sizeof(person.name) - 1);
    person.has_address = true;
    strncpy(person.address.street, "123 Main St", sizeof(person.address.street) - 1);
    strncpy(person.address.city, "Springfield", sizeof(person.address.city) - 1);
    strncpy(person.address.country, "USA", sizeof(person.address.country) - 1);
    
    // Створити потік для кодування
    pb_ostream_t ostream = pb_ostream_from_buffer(buffer, sizeof(buffer));
    
    // Закодувати повідомлення
    if (!pb_encode(&ostream, example_Person_fields, &person)) {
        printf("Помилка кодування: %s\n", PB_GET_ERROR(&ostream));
        return 1;
    }
    
    message_length = ostream.bytes_written;
    printf("Закодовано %zu байтів\n", message_length);
    
    // Вивести шістнадцятковий дамп закодованих даних
    printf("Закодовані дані: ");
    for (size_t i = 0; i < message_length; i++) {
        printf("%02x ", buffer[i]);
    }
    printf("\n");
    
    // --- ДЕКОДУВАННЯ ---
    example_Person decoded = example_Person_init_zero;
    
    // Створити потік для декодування
    pb_istream_t istream = pb_istream_from_buffer(buffer, message_length);
    
    // Декодувати повідомлення
    if (!pb_decode(&istream, example_Person_fields, &decoded)) {
        printf("Помилка декодування: %s\n", PB_GET_ERROR(&istream));
        return 1;
    }
    
    // Вивести декодовані значення
    printf("Декодовані значення:\n");
    printf("  ім'я: %s\n", decoded.name);
    printf("  вік: %u\n", (unsigned int)decoded.age);
    printf("  адреса:\n");
    printf("    вулиця: %s\n", decoded.address.street);
    printf("    місто: %s\n", decoded.address.city);
    printf("    країна: %s\n", decoded.address.country);
    
    return 0;
}

Команда компіляції

Скомпілюйте приклад з nanopb. NanoPB зазвичай використовується шляхом безпосереднього включення вихідних файлів у ваш проєкт:

compile_nested_example.sh

gcc -o nested_example nested_example.c nested.pb.c pb_common.c pb_encode.c pb_decode.c -I.

Примітка: Вихідні файли NanoPB (pb_common.c, pb_encode.c, pb_decode.c) потрібно компілювати безпосередньо з вашим проєктом. Їх можна отримати з репозиторію NanoPB на GitHub.

Скрипт тестування на Python

Щоб перевірити кодування, можна використати бібліотеку protobuf для Python:

test_nested.py

import nested_pb2

# Прочитати бінарні дані
with open('encoded.bin', 'rb') as f:
    data = f.read()

# Декодувати
msg = nested_pb2.Person()
msg.ParseFromString(data)

print("Python декодовані значення:")
print(f"  ім'я: {msg.name}")
print(f"  вік: {msg.age}")
print(f"  адреса:")
print(f"    вулиця: {msg.address.street}")
print(f"    місто: {msg.address.city}")
print(f"    країна: {msg.address.country}")

Спочатку скомпілюйте визначення protobuf для Python:

compile_python_nested.sh

protoc --python_out=. nested.proto

Потім змініть приклад на C, щоб зберегти закодовані дані у файл:

save_encoded_nested.c

// Після кодування додайте це:
FILE *f = fopen("encoded.bin", "wb");
fwrite(buffer, 1, message_length, f);
fclose(f);

Приклад з необов’язковим вкладеним повідомленням

Ось приклад з необов’язковим вкладеним повідомленням:

nested_optional.proto

syntax = "proto3";

package example;

message Address {
  string street = 1;
  string city = 2;
}

message Person {
  string name = 1;
  optional Address address = 2;
}

Створіть nested_optional.options:

nested_optional.options

example.Address.street max_size:64
example.Address.city max_size:32
example.Person.name max_size:64

nested_optional_example.c

#include <stdio.h>
#include <stdint.h>
#include <string.h>
#include "nested_optional.pb.h"
#include "pb_encode.h"
#include "pb_decode.h"

int main() {
    uint8_t buffer[256];
    size_t message_length;
    
    // --- КОДУВАННЯ ---
    example_Person person = example_Person_init_zero;
    
    strncpy(person.name, "Jane Doe", sizeof(person.name) - 1);
    
    // Встановити необов'язкове вкладене повідомлення
    strncpy(person.address.street, "456 Oak Ave", sizeof(person.address.street) - 1);
    strncpy(person.address.city, "Boston", sizeof(person.address.city) - 1);
    person.has_address = true;  // Важливо: встановити прапорець has_*
    
    pb_ostream_t ostream = pb_ostream_from_buffer(buffer, sizeof(buffer));
    
    if (!pb_encode(&ostream, example_Person_fields, &person)) {
        printf("Помилка кодування: %s\n", PB_GET_ERROR(&ostream));
        return 1;
    }
    
    message_length = ostream.bytes_written;
    printf("Закодовано %zu байтів\n", message_length);
    
    // --- ДЕКОДУВАННЯ ---
    example_Person decoded = example_Person_init_zero;
    
    pb_istream_t istream = pb_istream_from_buffer(buffer, message_length);
    
    if (!pb_decode(&istream, example_Person_fields, &decoded)) {
        printf("Помилка декодування: %s\n", PB_GET_ERROR(&istream));
        return 1;
    }
    
    printf("Декодовані значення:\n");
    printf("  ім'я: %s\n", decoded.name);
    if (decoded.has_address) {
        printf("  адреса:\n");
        printf("    вулиця: %s\n", decoded.address.street);
        printf("    місто: %s\n", decoded.address.city);
    } else {
        printf("  адреса: (не встановлено)\n");
    }
    
    return 0;
}

Ключові моменти

Вкладені повідомлення: Повідомлення можуть містити інші повідомлення як поля
Ініціалізація: Використовуйте *_init_zero для ініціалізації як зовнішніх, так і вкладених повідомлень
Кодування: Встановлюйте поля вкладеного повідомлення безпосередньо, потім кодуйте зовнішнє повідомлення
Декодування: Декодуйте зовнішнє повідомлення, вкладені повідомлення декодуються автоматично
Необов’язкове вкладене: Використовуйте ключове слово optional та встановлюйте прапорець has_*
Структура: Вкладені повідомлення забезпечують ієрархічну організацію даних
Розміри буферів: Вказуйте розміри буферів для всіх строкових полів у файлі .options

Коли використовувати вкладені повідомлення

Коли ви маєте ієрархічні або згруповані дані
Коли ви хочете повторно використовувати визначення повідомлень
Коли вам потрібно організувати пов’язані поля разом
Коли ви хочете покращити читабельність повідомлень
Коли ви маєте складні структури даних

Очікуваний вивід

nested_expected_output.txt

Закодовано 35 байтів
Закодовані дані: 0a 08 4a 6f 68 6e 20 44 6f 65 10 1e 1a 1b 0a 0b 31 32 33 20 4d 61 69 6e 20 53 74 12 08 4e 65 77 20 59 6f 72 6b 1a 03 55 53 41
Декодовані значення:
  ім'я: John Doe
  вік: 30
  адреса:
    вулиця: 123 Main St
    місто: New York
    країна: USA

Очікуваний вивід (необов’язкове вкладене)

nested_optional_expected_output.txt

Закодовано 27 байтів
Декодовані значення:
  ім'я: Jane Doe
  адреса:
    вулиця: 456 Oak Ave
    місто: Boston

Відмінності від C++

Версія на C майже ідентична версії на C++, з ключовими відмінностями:

У C використовуйте явне приведення типів для специфікаторів формату printf
Для обробки вкладених повідомлень не потрібні специфічні для C++ можливості
Згенерований код однаковий для обох мов
Управління пам’яттю однакове (статичне розподілення в обох випадках)