NanoPB: Как работать с перечислениями (enum) в C

NanoPB — это оптимизированная по размеру кода реализация Protocol Buffers для встраиваемых систем. В этом посте показано, как работать с типами перечислений (enum) в C с помощью NanoPB.

Определение в Proto

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

enums.proto

syntax = "proto3";

package example;

enum Status {
  UNKNOWN = 0;
  OK = 1;
  ERROR = 2;
  BUSY = 3;
}

message EnumMessage {
  Status status = 1;
}

syntax = "proto3";

package example;

enum Status {
  UNKNOWN = 0;
  OK = 1;
  ERROR = 2;
  BUSY = 3;
}

message EnumMessage {
  Status status = 1;
}

Генерация кода NanoPB

Сгенерируйте код NanoPB:

generate_nanopb_enums.sh

protoc --nanopb_out=. enums.proto

protoc --nanopb_out=. enums.proto

Это создаст файлы enums.pb.h и enums.pb.c.

Пример на C

Вот полный пример на C для работы с перечислениями:

enums_example.c

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

// Вспомогательная функция для преобразования enum в строку
const char* status_to_string(example_Status status) {
    switch (status) {
        case example_Status_UNKNOWN: return "UNKNOWN";
        case example_Status_OK: return "OK";
        case example_Status_ERROR: return "ERROR";
        case example_Status_BUSY: return "BUSY";
        default: return "INVALID";
    }
}

int main() {
    // Буфер для закодированного сообщения
    uint8_t buffer[64];
    size_t message_length;
    
    // --- КОДИРОВАНИЕ ---
    example_EnumMessage message = example_EnumMessage_init_zero;
    
    // Установка значения enum
    message.status = example_Status_OK;
    
    // Создание потока для кодирования
    pb_ostream_t ostream = pb_ostream_from_buffer(buffer, sizeof(buffer));
    
    // Кодирование сообщения
    if (!pb_encode(&ostream, example_EnumMessage_fields, &message)) {
        printf("Encoding failed: %s\n", PB_GET_ERROR(&ostream));
        return 1;
    }
    
    message_length = ostream.bytes_written;
    printf("Encoded %zu bytes\n", message_length);
    
    // Вывод шестнадцатеричного дампа закодированных данных
    printf("Encoded data: ");
    for (size_t i = 0; i < message_length; i++) {
        printf("%02x ", buffer[i]);
    }
    printf("\n");
    
    // --- ДЕКОДИРОВАНИЕ ---
    example_EnumMessage decoded = example_EnumMessage_init_zero;
    
    // Создание потока для декодирования
    pb_istream_t istream = pb_istream_from_buffer(buffer, message_length);
    
    // Декодирование сообщения
    if (!pb_decode(&istream, example_EnumMessage_fields, &decoded)) {
        printf("Decoding failed: %s\n", PB_GET_ERROR(&istream));
        return 1;
    }
    
    // Вывод декодированного значения
    printf("Decoded value:\n");
    printf("  status: %s (enum value: %d)\n", 
           status_to_string(decoded.status), (int)decoded.status);
    
    return 0;
}

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

// Вспомогательная функция для преобразования enum в строку
const char* status_to_string(example_Status status) {
    switch (status) {
        case example_Status_UNKNOWN: return "UNKNOWN";
        case example_Status_OK: return "OK";
        case example_Status_ERROR: return "ERROR";
        case example_Status_BUSY: return "BUSY";
        default: return "INVALID";
    }
}

int main() {
    // Буфер для закодированного сообщения
    uint8_t buffer[64];
    size_t message_length;
    
    // --- КОДИРОВАНИЕ ---
    example_EnumMessage message = example_EnumMessage_init_zero;
    
    // Установка значения enum
    message.status = example_Status_OK;
    
    // Создание потока для кодирования
    pb_ostream_t ostream = pb_ostream_from_buffer(buffer, sizeof(buffer));
    
    // Кодирование сообщения
    if (!pb_encode(&ostream, example_EnumMessage_fields, &message)) {
        printf("Encoding failed: %s\n", PB_GET_ERROR(&ostream));
        return 1;
    }
    
    message_length = ostream.bytes_written;
    printf("Encoded %zu bytes\n", message_length);
    
    // Вывод шестнадцатеричного дампа закодированных данных
    printf("Encoded data: ");
    for (size_t i = 0; i < message_length; i++) {
        printf("%02x ", buffer[i]);
    }
    printf("\n");
    
    // --- ДЕКОДИРОВАНИЕ ---
    example_EnumMessage decoded = example_EnumMessage_init_zero;
    
    // Создание потока для декодирования
    pb_istream_t istream = pb_istream_from_buffer(buffer, message_length);
    
    // Декодирование сообщения
    if (!pb_decode(&istream, example_EnumMessage_fields, &decoded)) {
        printf("Decoding failed: %s\n", PB_GET_ERROR(&istream));
        return 1;
    }
    
    // Вывод декодированного значения
    printf("Decoded value:\n");
    printf("  status: %s (enum value: %d)\n", 
           status_to_string(decoded.status), (int)decoded.status);
    
    return 0;
}

Команда компиляции

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

compile_enums_example.sh

gcc -o enums_example enums_example.c enums.pb.c pb_common.c pb_encode.c pb_decode.c -I.

gcc -o enums_example enums_example.c enums.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_enums.py

import enums_pb2

# Чтение бинарных данных
with open('encoded.bin', 'rb') as f:
    data = f.read()

# Декодирование
msg = enums_pb2.EnumMessage()
msg.ParseFromString(data)

print("Python decoded values:")
print(f"  status: {enums_pb2.Status.Name(msg.status)}")

import enums_pb2

# Чтение бинарных данных
with open('encoded.bin', 'rb') as f:
    data = f.read()

# Декодирование
msg = enums_pb2.EnumMessage()
msg.ParseFromString(data)

print("Python decoded values:")
print(f"  status: {enums_pb2.Status.Name(msg.status)}")

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

compile_python_enums.sh

protoc --python_out=. enums.proto

protoc --python_out=. enums.proto

Затем измените пример на C, чтобы сохранить закодированные данные в файл:

save_encoded_enums.c

// После кодирования добавьте это:
FILE *f = fopen("encoded.bin", "wb");
fwrite(buffer, 1, message_length, f);
fclose(f);

// После кодирования добавьте это:
FILE *f = fopen("encoded.bin", "wb");
fwrite(buffer, 1, message_length, f);
fclose(f);

Пример с enum в операторе switch

Вот пример, показывающий, как использовать перечисления в операторах switch:

enums_switch_example.c

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

void handle_status(example_Status status) {
    printf("Handling status: ");
    
    switch (status) {
        case example_Status_UNKNOWN:
            printf("UNKNOWN - Default state\n");
            break;
        case example_Status_OK:
            printf("OK - Operation successful\n");
            break;
        case example_Status_ERROR:
            printf("ERROR - Operation failed\n");
            break;
        case example_Status_BUSY:
            printf("BUSY - System busy\n");
            break;
        default:
            printf("INVALID - Unknown enum value\n");
            break;
    }
}

int main() {
    uint8_t buffer[64];
    size_t message_length;
    
    // Тестирование всех значений enum
    example_Status test_values[] = {
        example_Status_UNKNOWN,
        example_Status_OK,
        example_Status_ERROR,
        example_Status_BUSY
    };
    
    for (size_t i = 0; i < 4; i++) {
        example_EnumMessage message = example_EnumMessage_init_zero;
        message.status = test_values[i];
        
        pb_ostream_t ostream = pb_ostream_from_buffer(buffer, sizeof(buffer));
        
        if (!pb_encode(&ostream, example_EnumMessage_fields, &message)) {
            printf("Encoding failed: %s\n", PB_GET_ERROR(&ostream));
            return 1;
        }
        
        message_length = ostream.bytes_written;
        
        example_EnumMessage decoded = example_EnumMessage_init_zero;
        pb_istream_t istream = pb_istream_from_buffer(buffer, message_length);
        
        if (!pb_decode(&istream, example_EnumMessage_fields, &decoded)) {
            printf("Decoding failed: %s\n", PB_GET_ERROR(&istream));
            return 1;
        }
        
        handle_status(decoded.status);
    }
    
    return 0;
}

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

void handle_status(example_Status status) {
    printf("Handling status: ");
    
    switch (status) {
        case example_Status_UNKNOWN:
            printf("UNKNOWN - Default state\n");
            break;
        case example_Status_OK:
            printf("OK - Operation successful\n");
            break;
        case example_Status_ERROR:
            printf("ERROR - Operation failed\n");
            break;
        case example_Status_BUSY:
            printf("BUSY - System busy\n");
            break;
        default:
            printf("INVALID - Unknown enum value\n");
            break;
    }
}

int main() {
    uint8_t buffer[64];
    size_t message_length;
    
    // Тестирование всех значений enum
    example_Status test_values[] = {
        example_Status_UNKNOWN,
        example_Status_OK,
        example_Status_ERROR,
        example_Status_BUSY
    };
    
    for (size_t i = 0; i < 4; i++) {
        example_EnumMessage message = example_EnumMessage_init_zero;
        message.status = test_values[i];
        
        pb_ostream_t ostream = pb_ostream_from_buffer(buffer, sizeof(buffer));
        
        if (!pb_encode(&ostream, example_EnumMessage_fields, &message)) {
            printf("Encoding failed: %s\n", PB_GET_ERROR(&ostream));
            return 1;
        }
        
        message_length = ostream.bytes_written;
        
        example_EnumMessage decoded = example_EnumMessage_init_zero;
        pb_istream_t istream = pb_istream_from_buffer(buffer, message_length);
        
        if (!pb_decode(&istream, example_EnumMessage_fields, &decoded)) {
            printf("Decoding failed: %s\n", PB_GET_ERROR(&istream));
            return 1;
        }
        
        handle_status(decoded.status);
    }
    
    return 0;
}

Ключевые моменты

Определение enum: Определяйте перечисления в файле .proto с явными значениями
Сгенерированные типы: NanoPB генерирует типы перечислений с именованием package_EnumName
Кодирование: Присваивайте значение enum непосредственно полю
Декодирование: Значения enum декодируются автоматически
Значения по умолчанию: Первое значение enum (обычно 0) является значением по умолчанию
Операторы switch: Перечисления естественно работают в операторах switch
Типобезопасность: Перечисления обеспечивают типобезопасность по сравнению с обычными целыми числами
Неизвестные значения: Неверные значения enum могут быть декодированы как их числовое значение

Когда использовать enum

Когда у вас есть фиксированный набор возможных значений
Когда вам нужна типобезопасность для полей состояния или режима
Когда вы хотите самодокументируемый код
Когда нужно различать разные режимы работы
Когда вы хотите закодировать семантическое значение в сообщениях

Ожидаемый вывод

enums_expected_output.txt

Encoded 2 bytes
Encoded data: 08 01 
Decoded value:
  status: OK (enum value: 1)

Encoded 2 bytes
Encoded data: 08 01 
Decoded value:
  status: OK (enum value: 1)

Ожидаемый вывод (пример со switch)

enums_switch_expected_output.txt

Handling status: UNKNOWN - Default state
Handling status: OK - Operation successful
Handling status: ERROR - Operation failed
Handling status: BUSY - System busy

Handling status: UNKNOWN - Default state
Handling status: OK - Operation successful
Handling status: ERROR - Operation failed
Handling status: BUSY - System busy

Отличия от C++

Версия на C практически идентична версии на C++:

Перечисления работают одинаково как в C, так и в C++
Используйте явное приведение типов для спецификаторов формата printf в C
Для работы с enum не требуются специфичные для C++ возможности
Сгенерированный код идентичен для обоих языков