pw::protobuf::StreamDecoder Class Reference

Overview

A low-level, event-based protobuf wire format decoder that operates on a stream.

The decoder processes an encoded message by iterating over its fields using Next(). The caller can then check FieldNumber() and extract the values of fields using the Read*() methods.

While individual read calls return pw::Result, pw::StatusWithSize, or pw::Status objects, the decoder tracks all status returns and latches onto the first error encountered. This status can be accessed via StreamDecoder::status().

In the case of errors during reading, decoding stops and returns with the cursor on the field that caused the error. Unknown fields in the wire encoding are skipped automatically during iteration.

Note

This decoder does not provide in-memory data structures representing a protobuf message and is intended for messages too large to fit in memory or where streaming is required. For smaller messages where the complete data is available in memory, prefer MemoryDecoder (Decoder), which avoids stream overhead.

stream::Reader& my_stream = GetProtoStream();
StreamDecoder decoder(my_stream);
 
while (decoder.Next().ok()) {
  // FieldNumber() will always be valid if Next() returns OK.
  switch (decoder.FieldNumber().value()) {
    case 1:
      Result<uint32_t> result = decoder.ReadUint32();
      if (result.ok()) {
        DoSomething(result.value());
      }
      break;
    // ... and other fields.
  }
}

Classes
struct	Bounds
	Bounds of a payload interval within a reader. More...
class	BytesReader

Public Member Functions
constexpr	StreamDecoder (stream::Reader &reader)
constexpr	StreamDecoder (stream::Reader &reader, size_t length)
	StreamDecoder (const StreamDecoder &other)=delete
StreamDecoder &	operator= (const StreamDecoder &other)=delete
Status	Next ()
constexpr Result< uint32_t >	FieldNumber () const
Result< int32_t >	ReadInt32 ()
	Reads a proto int32 value from the current position.
StatusWithSize	ReadPackedInt32 (span< int32_t > out)
Status	ReadRepeatedInt32 (pw::Vector< int32_t > &out)
Result< uint32_t >	ReadUint32 ()
	Reads a proto uint32 value from the current position.
StatusWithSize	ReadPackedUint32 (span< uint32_t > out)
Status	ReadRepeatedUint32 (pw::Vector< uint32_t > &out)
template<typename T , typename = std::enable_if_t<std::is_enum_v<T>>>
StatusWithSize	ReadPackedEnum (span< T > out)
template<typename T , typename = std::enable_if_t<std::is_enum_v<T>>>
Status	ReadRepeatedEnum (pw::Vector< T > &out)
Result< int64_t >	ReadInt64 ()
	Reads a proto int64 value from the current position.
StatusWithSize	ReadPackedInt64 (span< int64_t > out)
Status	ReadRepeatedInt64 (pw::Vector< int64_t > &out)
Result< uint64_t >	ReadUint64 ()
	Reads a proto uint64 value from the current position.
StatusWithSize	ReadPackedUint64 (span< uint64_t > out)
Status	ReadRepeatedUint64 (pw::Vector< uint64_t > &out)
Result< int32_t >	ReadSint32 ()
	Reads a proto sint32 value from the current position.
StatusWithSize	ReadPackedSint32 (span< int32_t > out)
Status	ReadRepeatedSint32 (pw::Vector< int32_t > &out)
Result< int64_t >	ReadSint64 ()
	Reads a proto sint64 value from the current position.
StatusWithSize	ReadPackedSint64 (span< int64_t > out)
Status	ReadRepeatedSint64 (pw::Vector< int64_t > &out)
Result< bool >	ReadBool ()
	Reads a proto bool value from the current position.
StatusWithSize	ReadPackedBool (span< bool > out)
Status	ReadRepeatedBool (pw::Vector< bool > &out)
Result< uint32_t >	ReadFixed32 ()
	Reads a proto fixed32 value from the current position.
StatusWithSize	ReadPackedFixed32 (span< uint32_t > out)
Status	ReadRepeatedFixed32 (pw::Vector< uint32_t > &out)
Result< uint64_t >	ReadFixed64 ()
	Reads a proto fixed64 value from the current position.
StatusWithSize	ReadPackedFixed64 (span< uint64_t > out)
Status	ReadRepeatedFixed64 (pw::Vector< uint64_t > &out)
Result< int32_t >	ReadSfixed32 ()
	Reads a proto sfixed32 value from the current position.
StatusWithSize	ReadPackedSfixed32 (span< int32_t > out)
Status	ReadRepeatedSfixed32 (pw::Vector< int32_t > &out)
Result< int64_t >	ReadSfixed64 ()
	Reads a proto sfixed64 value from the current position.
StatusWithSize	ReadPackedSfixed64 (span< int64_t > out)
Status	ReadRepeatedSfixed64 (pw::Vector< int64_t > &out)
Result< float >	ReadFloat ()
	Reads a proto float value from the current position.
StatusWithSize	ReadPackedFloat (span< float > out)
Status	ReadRepeatedFloat (pw::Vector< float > &out)
Result< double >	ReadDouble ()
	Reads a proto double value from the current position.
StatusWithSize	ReadPackedDouble (span< double > out)
Status	ReadRepeatedDouble (pw::Vector< double > &out)
StatusWithSize	ReadString (span< char > out)
StatusWithSize	ReadBytes (span< std::byte > out)
BytesReader	GetBytesReader ()
StreamDecoder	GetNestedDecoder ()
Status	SkipField ()
Result< Bounds >	GetLengthDelimitedPayloadBounds ()

Protected Member Functions
constexpr	StreamDecoder (StreamDecoder &&other)
Status	Read (span< std::byte > message, span< const internal::MessageField > table)

Friends
class	BytesReader
class	Message

Constructor & Destructor Documentation

StreamDecoder() [1/2]

constexpr pw::protobuf::StreamDecoder::StreamDecoder ( stream::Reader &  reader )

inlineconstexpr

Constructs a StreamDecoder operating on reader with unbounded length.

Parameters

[in]

reader

Source stream reader containing serialized protobuf data.

StreamDecoder() [2/2]

constexpr pw::protobuf::StreamDecoder::StreamDecoder ( stream::Reader &  reader, size_t  length  )

inlineconstexpr

Constructs a StreamDecoder with a specified maximum length.

Where the length of the protobuf message is known in advance, the decoder can be prevented from reading from the stream beyond the known bounds by specifying the length. When a decoder constructed in this way goes out of scope, it automatically consumes any remaining bytes up to length, allowing the next Read() on the stream to start after the protobuf even if it was not fully parsed.

Parameters

[in]	reader	Source stream reader containing serialized protobuf data.
[in]	length	Maximum number of bytes belonging to this protobuf message.

Member Function Documentation

FieldNumber()

constexpr Result< uint32_t > pw::protobuf::StreamDecoder::FieldNumber ( ) const

inlineconstexpr

Returns the field number of the current field.

Returns

A Result containing the field number of the current field on success or one of the following error codes on failure:

• FAILED_PRECONDITION: The current field has already been consumed or Next() has not been called successfully.
• Other error statuses latched by the decoder.

Precondition

Must only be called after a successful call to Next() and before any Read*() operation.

GetBytesReader()

BytesReader pw::protobuf::StreamDecoder::GetBytesReader

(

)

Returns a stream::Reader (BytesReader) for accessing a bytes (or string) field as a stream.

The BytesReader shares the same stream as the decoder, using RAII to manage ownership of the stream.

Warning

When a BytesReader is active, any use of the parent StreamDecoder that created it will trigger a crash. To resume using the parent decoder, destroy the BytesReader first.

StreamDecoder decoder(my_stream);
 
while (decoder.Next().ok()) {
  switch (decoder.FieldNumber().value()) {
    case 1: {
      // The BytesReader is created within a new C++ scope. While it is
      // alive, the decoder cannot be used.
      StreamDecoder::BytesReader reader = decoder.GetBytesReader();
      reader.Read(some_buffer);
      break;
    }
  }
}

Returns

A BytesReader stream reader targeting the current field. The reader supports seeking if the underlying StreamDecoder stream supports seeking.

GetLengthDelimitedPayloadBounds()

Result< Bounds > pw::protobuf::StreamDecoder::GetLengthDelimitedPayloadBounds

(

)

Gets the interval of the payload part of a length-delimited field.

That is, the interval excluding the field key and the length prefix. The bounds are relative to the given reader.

Returns

A Result containing the bounds of the payload interval on success or one of the following error codes on failure:

GetNestedDecoder()

StreamDecoder pw::protobuf::StreamDecoder::GetNestedDecoder

(

)

Returns a decoder for a nested protobuf message located at the current position.

The nested decoder shares the same stream as its parent, using RAII to manage ownership of the stream.

Warning

When a nested submessage is being decoded, any use of the parent decoder that created the nested decoder will trigger a crash. To resume using the parent decoder, destroy the submessage decoder first.

Returns

A StreamDecoder for reading the nested submessage.

Next()

Status pw::protobuf::StreamDecoder::Next

(

)

Advances to the next field in the proto.

If Next() returns \ref pw::OkStatus() "OK", there is guaranteed to be a valid protobuf field at the current position, which can then be consumed through one of the Read*() methods.

Returns

• OK: Advanced to a valid proto field.
• OUT_OF_RANGE: Reached the end of the proto message.
• DATA_LOSS: Encountered invalid protobuf wire data.
• Other errors encountered while reading from the underlying stream.

ReadBytes()

StatusWithSize pw::protobuf::StreamDecoder::ReadBytes ( span< std::byte >  out )

inline

Reads a proto bytes value from the current position into the provided span.

The value is copied into the provided buffer and the read size is returned. For larger bytes values that won't fit into memory, use GetBytesReader() to acquire a stream::Reader to the bytes instead.

Parameters

[out]

out

Destination span for the bytes data.

Returns

• OK with the number of bytes read: Bytes successfully read.
• RESOURCE_EXHAUSTED with 0 bytes: The buffer is too small to fit the bytes value. No data is read, and the decoder's position remains on the bytes field.

ReadPackedBool()

StatusWithSize pw::protobuf::StreamDecoder::ReadPackedBool ( span< bool >  out )

inline

Reads repeated bool values from the current position using packed encoding into the provided span.

Parameters

[out]

out

Destination span for read values.

Returns

Status with the number of values successfully read.

ReadPackedDouble()

StatusWithSize pw::protobuf::StreamDecoder::ReadPackedDouble ( span< double >  out )

inline

Reads repeated double values from the current position using packed encoding into the provided span.

Parameters

[out]

out

Destination span for read values.

Returns

Status with the number of values successfully read.

ReadPackedEnum()

template<typename T , typename = std::enable_if_t<std::is_enum_v<T>>>

StatusWithSize pw::protobuf::StreamDecoder::ReadPackedEnum ( span< T >  out )

inline

Reads repeated enum values from the current position using packed encoding into the provided span.

Parameters

[out]

out

Destination span for read values.

Returns

Status with the number of values successfully read.

ReadPackedFixed32()

StatusWithSize pw::protobuf::StreamDecoder::ReadPackedFixed32 ( span< uint32_t >  out )

inline

Reads repeated fixed32 values from the current position using packed encoding into the provided span.

Parameters

[out]

out

Destination span for read values.

Returns

Status with the number of values successfully read.

ReadPackedFixed64()

StatusWithSize pw::protobuf::StreamDecoder::ReadPackedFixed64 ( span< uint64_t >  out )

inline

Reads repeated fixed64 values from the current position using packed encoding into the provided span.

Parameters

[out]

out

Destination span for read values.

Returns

Status with the number of values successfully read.

ReadPackedFloat()

StatusWithSize pw::protobuf::StreamDecoder::ReadPackedFloat ( span< float >  out )

inline

Reads repeated float values from the current position using packed encoding into the provided span.

Parameters

[out]

out

Destination span for read values.

Returns

Status with the number of values successfully read.

ReadPackedInt32()

StatusWithSize pw::protobuf::StreamDecoder::ReadPackedInt32 ( span< int32_t >  out )

inline

Reads repeated int32 values from the current position using packed encoding into the provided span.

Parameters

[out]

out

Destination span for read values.

Returns

Status with the number of values successfully read.

ReadPackedInt64()

StatusWithSize pw::protobuf::StreamDecoder::ReadPackedInt64 ( span< int64_t >  out )

inline

Reads repeated int64 values from the current position using packed encoding into the provided span.

Parameters

[out]

out

Destination span for read values.

Returns

Status with the number of values successfully read.

ReadPackedSfixed32()

StatusWithSize pw::protobuf::StreamDecoder::ReadPackedSfixed32 ( span< int32_t >  out )

inline

Reads repeated sfixed32 values from the current position using packed encoding into the provided span.

Parameters

[out]

out

Destination span for read values.

Returns

Status with the number of values successfully read.

ReadPackedSfixed64()

StatusWithSize pw::protobuf::StreamDecoder::ReadPackedSfixed64 ( span< int64_t >  out )

inline

Reads repeated sfixed64 values from the current position using packed encoding into the provided span.

Parameters

[out]

out

Destination span for read values.

Returns

Status with the number of values successfully read.

ReadPackedSint32()

StatusWithSize pw::protobuf::StreamDecoder::ReadPackedSint32 ( span< int32_t >  out )

inline

Reads repeated sint32 values from the current position using packed encoding into the provided span.

Parameters

[out]

out

Destination span for read values.

Returns

Status with the number of values successfully read.

ReadPackedSint64()

StatusWithSize pw::protobuf::StreamDecoder::ReadPackedSint64 ( span< int64_t >  out )

inline

Reads repeated sint64 values from the current position using packed encoding into the provided span.

Parameters

[out]

out

Destination span for read values.

Returns

Status with the number of values successfully read.

ReadPackedUint32()

StatusWithSize pw::protobuf::StreamDecoder::ReadPackedUint32 ( span< uint32_t >  out )

inline

Reads repeated uint32 values from the current position using packed encoding into the provided span.

Parameters

[out]

out

Destination span for read values.

Returns

Status with the number of values successfully read.

ReadPackedUint64()

StatusWithSize pw::protobuf::StreamDecoder::ReadPackedUint64 ( span< uint64_t >  out )

inline

Reads repeated uint64 values from the current position using packed encoding into the provided span.

Parameters

[out]

out

Destination span for read values.

Returns

Status with the number of values successfully read.

ReadRepeatedBool()

Status pw::protobuf::StreamDecoder::ReadRepeatedBool ( pw::Vector< bool > &  out )

inline

Reads repeated bool values from the current position into the vector, supporting either repeated single field elements or packed encoding.

Parameters

[out]

out

Vector where values will be appended.

ReadRepeatedDouble()

Status pw::protobuf::StreamDecoder::ReadRepeatedDouble ( pw::Vector< double > &  out )

inline

Reads repeated double values from the current position into the vector, supporting either repeated single field elements or packed encoding.

Parameters

[out]

out

Vector where values will be appended.

ReadRepeatedEnum()

template<typename T , typename = std::enable_if_t<std::is_enum_v<T>>>

Status pw::protobuf::StreamDecoder::ReadRepeatedEnum ( pw::Vector< T > &  out )

inline

Reads repeated enum values from the current position into the vector, supporting either repeated single field elements or packed encoding.

Parameters

[out]

out

Vector where values will be appended.

ReadRepeatedFixed32()

Status pw::protobuf::StreamDecoder::ReadRepeatedFixed32 ( pw::Vector< uint32_t > &  out )

inline

Reads repeated fixed32 values from the current position into the vector, supporting either repeated single field elements or packed encoding.

Parameters

[out]

out

Vector where values will be appended.

ReadRepeatedFixed64()

Status pw::protobuf::StreamDecoder::ReadRepeatedFixed64 ( pw::Vector< uint64_t > &  out )

inline

Reads repeated fixed64 values from the current position into the vector, supporting either repeated single field elements or packed encoding.

Parameters

[out]

out

Vector where values will be appended.

ReadRepeatedFloat()

Status pw::protobuf::StreamDecoder::ReadRepeatedFloat ( pw::Vector< float > &  out )

inline

Reads repeated float values from the current position into the vector, supporting either repeated single field elements or packed encoding.

Parameters

[out]

out

Vector where values will be appended.

ReadRepeatedInt32()

Status pw::protobuf::StreamDecoder::ReadRepeatedInt32 ( pw::Vector< int32_t > &  out )

inline

Reads repeated int32 values from the current position into the vector, supporting either repeated single field elements or packed encoding.

Parameters

[out]

out

Vector where values will be appended.

ReadRepeatedInt64()

Status pw::protobuf::StreamDecoder::ReadRepeatedInt64 ( pw::Vector< int64_t > &  out )

inline

Reads repeated int64 values from the current position into the vector, supporting either repeated single field elements or packed encoding.

Parameters

[out]

out

Vector where values will be appended.

ReadRepeatedSfixed32()

Status pw::protobuf::StreamDecoder::ReadRepeatedSfixed32 ( pw::Vector< int32_t > &  out )

inline

Reads repeated sfixed32 values from the current position into the vector, supporting either repeated single field elements or packed encoding.

Parameters

[out]

out

Vector where values will be appended.

ReadRepeatedSfixed64()

Status pw::protobuf::StreamDecoder::ReadRepeatedSfixed64 ( pw::Vector< int64_t > &  out )

inline

Reads repeated sfixed64 values from the current position into the vector, supporting either repeated single field elements or packed encoding.

Parameters

[out]

out

Vector where values will be appended.

ReadRepeatedSint32()

Status pw::protobuf::StreamDecoder::ReadRepeatedSint32 ( pw::Vector< int32_t > &  out )

inline

Reads repeated sint32 values from the current position into the vector, supporting either repeated single field elements or packed encoding.

Parameters

[out]

out

Vector where values will be appended.

ReadRepeatedSint64()

Status pw::protobuf::StreamDecoder::ReadRepeatedSint64 ( pw::Vector< int64_t > &  out )

inline

Reads repeated sint64 values from the current position into the vector, supporting either repeated single field elements or packed encoding.

Parameters

[out]

out

Vector where values will be appended.

ReadRepeatedUint32()

Status pw::protobuf::StreamDecoder::ReadRepeatedUint32 ( pw::Vector< uint32_t > &  out )

inline

Reads repeated uint32 values from the current position into the vector, supporting either repeated single field elements or packed encoding.

Parameters

[out]

out

Vector where values will be appended.

ReadRepeatedUint64()

Status pw::protobuf::StreamDecoder::ReadRepeatedUint64 ( pw::Vector< uint64_t > &  out )

inline

Reads repeated uint64 values from the current position into the vector, supporting either repeated single field elements or packed encoding.

Parameters

[out]

out

Vector where values will be appended.

ReadString()

StatusWithSize pw::protobuf::StreamDecoder::ReadString ( span< char >  out )

inline

Reads a proto string value from the current position into the provided span.

The string is copied into the provided buffer and the read size is returned. Since the span is updated with the size of the string, the string is NOT automatically null-terminated; this should be done manually if desired. pw_string provides utility methods to copy string data from spans into other targets.

Parameters

[out]

out

Destination span for the string data.

Returns

• OK with the number of bytes read: String successfully read.
• RESOURCE_EXHAUSTED with 0 bytes: The buffer is too small to fit the string value. No data is read, and the decoder's position remains on the string field.

SkipField()

Status pw::protobuf::StreamDecoder::SkipField

(

)

Consumes the current protobuf field, advancing the stream to the key of the next field (if one exists).

---

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

• pw_protobuf/public/pw_protobuf/stream_decoder.h