NanoPB: Jak pracovat s výčty v C

Viz také: Verze v C++: Jak pracovat s výčty v C++

NanoPB je implementace Protocol Buffers optimalizovaná na velikost kódu pro vestavěné systémy. Tento příspěvek ukazuje, jak pracovat s typy výčtů v C s NanoPB.

Definice Proto

Nejprve vytvořte soubor .proto s výčty:

enums.proto

syntax = "proto3";

package example;

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

message EnumMessage {
  Status status = 1;
}

Generování NanoPB kódu

Vygenerujte NanoPB kód:

generate_nanopb_enums.sh

protoc --nanopb_out=. enums.proto

Tím se vygenerují enums.pb.h a enums.pb.c.

Příklad v C

Zde je kompletní příklad v C zpracovávající výčty:

enums_example.c

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

// Pomocná funkce pro převod výčtu na řetězec
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() {
    // Buffer pro kódovanou zprávu
    uint8_t buffer[64];
    size_t message_length;
    
    // --- KÓDOVÁNÍ ---
    example_EnumMessage message = example_EnumMessage_init_zero;
    
    // Nastavení hodnoty výčtu
    message.status = example_Status_OK;
    
    // Vytvoření streamu pro kódování
    pb_ostream_t ostream = pb_ostream_from_buffer(buffer, sizeof(buffer));
    
    // Kódování zprávy
    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);
    
    // Výpis hex dumpu kódovaných dat
    printf("Encoded data: ");
    for (size_t i = 0; i < message_length; i++) {
        printf("%02x ", buffer[i]);
    }
    printf("\n");
    
    // --- DEKÓDOVÁNÍ ---
    example_EnumMessage decoded = example_EnumMessage_init_zero;
    
    // Vytvoření streamu pro dekódování
    pb_istream_t istream = pb_istream_from_buffer(buffer, message_length);
    
    // Dekódování zprávy
    if (!pb_decode(&istream, example_EnumMessage_fields, &decoded)) {
        printf("Decoding failed: %s\n", PB_GET_ERROR(&istream));
        return 1;
    }
    
    // Výpis dekódované hodnoty
    printf("Decoded value:\n");
    printf("  status: %s (enum value: %d)\n", 
           status_to_string(decoded.status), (int)decoded.status);
    
    return 0;
}

Příkaz pro kompilaci

Zkompilujte příklad s nanopb. NanoPB se typicky používá tak, že se zdrojové soubory přímo vloží do vašeho projektu:

compile_enums_example.sh

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

Poznámka: Zdrojové soubory NanoPB (pb_common.c, pb_encode.c, pb_decode.c) je třeba kompilovat přímo s vaším projektem. Můžete je získat z NanoPB GitHub repozitáře.

Testovací skript v Pythonu

Pro ověření kódování můžete použít knihovnu protobuf v Pythonu:

test_enums.py

import enums_pb2

# Načtení binárních dat
with open('encoded.bin', 'rb') as f:
    data = f.read()

# Dekódování
msg = enums_pb2.EnumMessage()
msg.ParseFromString(data)

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

Nejprve zkompilujte definice protobuf pro Python:

compile_python_enums.sh

protoc --python_out=. enums.proto

Poté upravte příklad v C tak, aby ukládal kódovaná data do souboru:

save_encoded_enums.c

// Po kódování přidejte toto:
FILE *f = fopen("encoded.bin", "wb");
fwrite(buffer, 1, message_length, f);
fclose(f);

Příklad s výčtem v příkazu switch

Zde je příklad ukazující, jak používat výčty v příkazech 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;
    
    // Test všech hodnot výčtu
    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;
}

Klíčové body

Definice výčtu: Definujte výčty v souboru .proto s explicitními hodnotami
Generované typy: NanoPB generuje typy výčtů s pojmenováním package_EnumName
Kódování: Přiřaďte hodnotu výčtu přímo k poli
Dekódování: Hodnoty výčtů se dekódují automaticky
Výchozí hodnoty: První hodnota výčtu (typicky 0) je výchozí
Příkazy switch: Výčty fungují přirozeně v příkazech switch
Typová bezpečnost: Výčty poskytují typovou bezpečnost oproti surovým celým číslům
Neznámé hodnoty: Neplatné hodnoty výčtu mohou být dekódovány jako jejich číselná hodnota

Kdy použít výčty

Pokud máte pevnou sadu možných hodnot
Pokud chcete typovou bezpečnost pro pole stavu nebo režimu
Pokud chcete samodokumentující kód
Pokud potřebujete rozlišit mezi různými režimy operací
Pokud chcete zakódovat sémantický význam do zpráv

Očekávaný výstup

enums_expected_output.txt

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

Očekávaný výstup (příklad se 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

Rozdíly oproti C++

Verze v C je téměř identická s verzí v C++:

Výčty fungují stejně v C i C++
Použijte explicitní přetypování pro specifikátory formátu printf v C
Nejsou potřeba žádné funkce specifické pro C++ pro zpracování výčtů
Vygenerovaný kód je identický pro oba jazyky