pw::protobuf::Message Class Reference

Overview

A helper class for parsing and iterating over fields in a protobuf message.

Message provides stream-oriented, re-entrant parsing of protobuf fields without requiring code generation. All parser objects created from Message hold a reference to the underlying reader and work independently without blocking each other.

Note

All parser objects generated by Message internally reference the same reader. Therefore, the reader must maintain a valid lifespan throughout the operations. All method calls and for-range iterations are re-entrant and safe to interleave.

// message Nested {
//   string nested_str = 1;
//   bytes nested_bytes = 2;
// }
//
// message MyProto {
//   string str = 1;
//   bytes bytes = 2;
//   uint32 integer = 3;
//   repeated string rep_str = 4;
//   map<string, bytes> str_to_bytes = 5;
//   Nested nested = 6;
// }
 
// Given a seekable `reader` and a `size` for the proto message:
Message message(reader, size);
 
// Parse basic value fields
String str = message.AsString(1);
Bytes bytes = message.AsBytes(2);
Uint32 integer = message.AsUint32(3);
 
// Parse repeated field: repeated string rep_str = 4;
RepeatedStrings rep_str = message.AsRepeatedStrings(4);
for (String element : rep_str) {
  if (!element.ok()) {
    // Handle error; loop exits on next iteration if continued.
  }
}
 
// Parse map field: map<string, bytes> str_to_bytes = 5;
StringToBytesMap str_to_bytes = message.AsStringToBytesMap(5);
Bytes bytes_for_key = str_to_bytes["key"];
for (StringToBytesMapEntry entry : str_to_bytes) {
  if (!entry.ok()) {
    // Handle error.
  }
  String key = entry.Key();
  Bytes value = entry.Value();
}
 
// Parse nested message: Nested nested = 6;
Message nested = message.AsMessage(6);
String nested_str = nested.AsString(1);
Bytes nested_bytes = nested.AsBytes(2);
 
// The `AsXXX()` methods above internally traverse all fields to find the
// matching tag. This can be expensive if called multiple times. Whenever
// possible, prefer for-range iteration over `Message::Field` to process
// each field in a single pass:
for (Message::Field field : message) {
  if (!field.ok()) {
    // Handle error.
  }
  if (field.field_number() == 1) {
    String s = field.As<String>();
  } else if (field.field_number() == 2) {
    Bytes b = field.As<Bytes>();
  } else if (field.field_number() == 6) {
    Message m = field.As<Message>();
  }
}

Deprecated:

All APIs from message.h are deprecated.

Classes
class	Field
class	iterator

Public Member Functions
	Message (Status status)
	Message (stream::IntervalReader reader)
	Message (stream::SeekableReader &proto_source, size_t size)
Bytes	AsBytes (uint32_t field_number)
String	AsString (uint32_t field_number)
Int32	AsInt32 (uint32_t field_number)
Sint32	AsSint32 (uint32_t field_number)
Uint32	AsUint32 (uint32_t field_number)
Fixed32	AsFixed32 (uint32_t field_number)
Int64	AsInt64 (uint32_t field_number)
Sint64	AsSint64 (uint32_t field_number)
Uint64	AsUint64 (uint32_t field_number)
Fixed64	AsFixed64 (uint32_t field_number)
Sfixed32	AsSfixed32 (uint32_t field_number)
Sfixed64	AsSfixed64 (uint32_t field_number)
Float	AsFloat (uint32_t field_number)
Double	AsDouble (uint32_t field_number)
Bool	AsBool (uint32_t field_number)
Message	AsMessage (uint32_t field_number)
RepeatedBytes	AsRepeatedBytes (uint32_t field_number)
RepeatedStrings	AsRepeatedStrings (uint32_t field_number)
RepeatedMessages	AsRepeatedMessages (uint32_t field_number)
StringToMessageMap	AsStringToMessageMap (uint32_t field_number)
StringToBytesMap	AsStringToBytesMap (uint32_t field_number)
StringToStringMap	AsStringToStringMap (uint32_t field_number)
Bytes	ToBytes ()
bool	ok ()
Status	status ()
iterator	begin ()
iterator	end ()
template<typename FieldType >
FieldType	As (uint32_t field_number)
template<typename FieldType >
RepeatedFieldParser< FieldType >	AsRepeated (uint32_t field_number)
template<typename FieldParser >
StringMapParser< FieldParser >	AsStringMap (uint32_t field_number)

Member Function Documentation

As()

template<typename FieldType >

FieldType pw::protobuf::Message::As ( uint32_t  field_number )

inline

Parses a field given by field_number as the target parser type FieldType.

Note

This method assumes that the message has only one field with the given field_number and returns the first match it finds. It does not perform value overriding or string concatenation for multiple occurrences of the tag.

Since this method traverses fields sequentially, it can be inefficient if called multiple times, especially on slow stream readers. Prefer iterating over Message::Field when processing multiple fields.

Template Parameters

FieldType

Target parser type (e.g., String, Bytes, Uint32).

Parameters

[in]

field_number

Tag number to locate.

Deprecated:

All APIs from message.h are deprecated.

---

The documentation for this class was generated from the following file:

• pw_protobuf/public/pw_protobuf/message.h