C/C++ API Reference
Loading...
Searching...
No Matches
pw::protobuf::StreamEncoder Class Reference

Overview

A protobuf encoder that encodes serialized proto data to a pw::stream::Writer.

While individual write calls on a proto encoder return pw::Status objects, the encoder tracks all status returns and latches onto the first error encountered. This status can be accessed via StreamEncoder::status().

See also
If you need to avoid scratch buffers or reduce copying of nested submessages, consider using BufferEncoder rather than StreamEncoder.
Inheritance diagram for pw::protobuf::StreamEncoder:
pw::protobuf::MemoryEncoder

Public Types

enum class  EmptyEncoderBehavior { kWriteFieldNumber , kWriteNothing }
 

Public Member Functions

constexpr StreamEncoder (stream::Writer &writer, ByteSpan scratch_buffer)
 
 StreamEncoder (stream::CountingNullStream &counting_stream)
 
 ~StreamEncoder ()
 
StreamEncoderoperator= (const StreamEncoder &other)=delete
 
 StreamEncoder (const StreamEncoder &other)=delete
 
StreamEncoderoperator= (StreamEncoder &&other)=delete
 
void CloseEncoder ()
 
size_t ConservativeWriteLimit () const
 
StreamEncoder GetNestedEncoder (uint32_t field_number, EmptyEncoderBehavior empty_encoder_behavior=EmptyEncoderBehavior::kWriteFieldNumber)
 
Status WriteNestedMessage (uint32_t field_number, FunctionRef< Status(StreamEncoder &)> write_message, EmptyEncoderBehavior empty_encoder_behavior=EmptyEncoderBehavior::kWriteFieldNumber)
 
Status status () const
 
Status WriteUint32 (uint32_t field_number, uint32_t value)
 
Status WritePackedUint32 (uint32_t field_number, span< const uint32_t > values)
 
template<typename T , typename = std::enable_if_t<std::is_enum_v<T>>>
Status WritePackedEnum (uint32_t field_number, span< const T > values)
 
Status WriteRepeatedUint32 (uint32_t field_number, const pw::Vector< uint32_t > &values)
 
Status WriteUint64 (uint32_t field_number, uint64_t value)
 
Status WritePackedUint64 (uint32_t field_number, span< const uint64_t > values)
 
Status WriteRepeatedUint64 (uint32_t field_number, const pw::Vector< uint64_t > &values)
 
Status WriteInt32 (uint32_t field_number, int32_t value)
 
Status WritePackedInt32 (uint32_t field_number, span< const int32_t > values)
 
Status WriteRepeatedInt32 (uint32_t field_number, const pw::Vector< int32_t > &values)
 
Status WriteInt64 (uint32_t field_number, int64_t value)
 
Status WritePackedInt64 (uint32_t field_number, span< const int64_t > values)
 
Status WriteRepeatedInt64 (uint32_t field_number, const pw::Vector< int64_t > &values)
 
Status WriteSint32 (uint32_t field_number, int32_t value)
 
Status WritePackedSint32 (uint32_t field_number, span< const int32_t > values)
 
Status WriteRepeatedSint32 (uint32_t field_number, const pw::Vector< int32_t > &values)
 
Status WriteSint64 (uint32_t field_number, int64_t value)
 
Status WritePackedSint64 (uint32_t field_number, span< const int64_t > values)
 
Status WriteRepeatedSint64 (uint32_t field_number, const pw::Vector< int64_t > &values)
 
Status WriteBool (uint32_t field_number, bool value)
 
Status WritePackedBool (uint32_t field_number, span< const bool > values)
 
Status WriteRepeatedBool (uint32_t field_number, const pw::Vector< bool > &values)
 
Status WriteFixed32 (uint32_t field_number, uint32_t value)
 
Status WritePackedFixed32 (uint32_t field_number, span< const uint32_t > values)
 
Status WriteRepeatedFixed32 (uint32_t field_number, const pw::Vector< uint32_t > &values)
 
Status WriteFixed64 (uint32_t field_number, uint64_t value)
 
Status WritePackedFixed64 (uint32_t field_number, span< const uint64_t > values)
 
Status WriteRepeatedFixed64 (uint32_t field_number, const pw::Vector< uint64_t > &values)
 
Status WriteSfixed32 (uint32_t field_number, int32_t value)
 
Status WritePackedSfixed32 (uint32_t field_number, span< const int32_t > values)
 
Status WriteRepeatedSfixed32 (uint32_t field_number, const pw::Vector< int32_t > &values)
 
Status WriteSfixed64 (uint32_t field_number, int64_t value)
 
Status WritePackedSfixed64 (uint32_t field_number, span< const int64_t > values)
 
Status WriteRepeatedSfixed64 (uint32_t field_number, const pw::Vector< int64_t > &values)
 
Status WriteFloat (uint32_t field_number, float value)
 
Status WritePackedFloat (uint32_t field_number, span< const float > values)
 
Status WriteRepeatedFloat (uint32_t field_number, const pw::Vector< float > &values)
 
Status WriteDouble (uint32_t field_number, double value)
 
Status WritePackedDouble (uint32_t field_number, span< const double > values)
 
Status WriteRepeatedDouble (uint32_t field_number, const pw::Vector< double > &values)
 
Status WriteBytes (uint32_t field_number, ConstByteSpan value)
 
Status WriteBytes (uint32_t field_number, size_t num_bytes, FunctionRef< Status(stream::Writer &)> write_func)
 
Status WriteBytesFromStream (uint32_t field_number, stream::Reader &bytes_reader, size_t num_bytes, ByteSpan stream_pipe_buffer)
 
Status WriteString (uint32_t field_number, std::string_view value)
 
Status WriteString (uint32_t field_number, const char *value, size_t len)
 
Status WriteStringFromStream (uint32_t field_number, stream::Reader &bytes_reader, size_t num_bytes, ByteSpan stream_pipe_buffer)
 

Protected Member Functions

constexpr StreamEncoder (StreamEncoder &&other)
 
Status Write (span< const std::byte > message, span< const internal::MessageField > table)
 
StreamEncoder GetNestedEncoder (uint32_t field_number, bool write_when_empty)
 

Friends

class MemoryEncoder
 

Constructor & Destructor Documentation

◆ StreamEncoder() [1/2]

constexpr pw::protobuf::StreamEncoder::StreamEncoder ( stream::Writer writer,
ByteSpan  scratch_buffer 
)
inlineconstexpr

Constructs a StreamEncoder that serializes proto data to the provided writer.

The scratch buffer provided is for internal use ONLY and should not be considered valid proto data. All submessage data is buffered to this scratch buffer until the submessage is finalized.

If a StreamEncoder object will be writing nested proto messages, it must provide a scratch buffer large enough to hold the largest submessage plus some additional overhead incurred by the encoder's implementation. It is a good idea to be generous when sizing this buffer. MaxScratchBufferSize() can be helpful in providing an estimated size for this buffer. The scratch buffer must exist for the lifetime of the StreamEncoder object.

StreamEncoder objects that do not write nested proto messages can provide a zero-length scratch buffer.

Warning
If the scratch buffer size is not sufficient, encoding will fail with \ref pw::Status::ResourceExhausted() "RESOURCE_EXHAUSTED". Always check the results of Write calls or the encoder status to ensure success, as otherwise the encoded data will be invalid.
Parameters
[in]writerThe destination stream writer for serialized data.
[in]scratch_bufferBuffer for staging nested submessages before their final sizes are known.

◆ StreamEncoder() [2/2]

pw::protobuf::StreamEncoder::StreamEncoder ( stream::CountingNullStream counting_stream)
inline

Constructs a StreamEncoder that counts encoded bytes without writing data.

Parameters
[in]counting_streamThe counting null stream used to measure encoded size.

◆ ~StreamEncoder()

pw::protobuf::StreamEncoder::~StreamEncoder ( )
inline

Destructs the StreamEncoder, closing it if active.

Precondition
Encoder has no active child encoder.
Postcondition
If this encoder is a nested one, the parent encoder is unlocked and proto encoding may resume on the parent.

Member Function Documentation

◆ CloseEncoder()

void pw::protobuf::StreamEncoder::CloseEncoder ( )

Closes this encoder, finalizing its output.

This method is called automatically by StreamEncoder's destructor, but may be invoked manually in order to close an encoder before the end of its lexical scope.

Precondition
Encoder has no active child encoder.
Postcondition
If this encoder is a nested one, the parent encoder is unlocked and proto encoding may resume on the parent. No more writes to this encoder may be performed.

◆ ConservativeWriteLimit()

size_t pw::protobuf::StreamEncoder::ConservativeWriteLimit ( ) const
inline

Forwards the conservative write limit of the underlying pw::stream::Writer.

Precondition
Encoder has no active child encoder.

◆ GetNestedEncoder()

StreamEncoder pw::protobuf::StreamEncoder::GetNestedEncoder ( uint32_t  field_number,
EmptyEncoderBehavior  empty_encoder_behavior = EmptyEncoderBehavior::kWriteFieldNumber 
)
inline

Creates a nested encoder with the provided field number.

Once this is called, the parent encoder is locked and not available for use until the nested encoder is finalized (either explicitly or through destruction).

The untyped encoder that this method returns can be cast to a typed encoder if needed.

Warning
When a nested submessage is created, any use of the parent encoder that created the nested encoder will trigger a crash. To resume using the parent encoder, destroy the submessage encoder first.
Parameters
[in]field_numberThe field number for the nested message.
[in]empty_encoder_behaviorWhether to write the tag number for the nested encoder if no data is written to that nested encoder. Defaults to EmptyEncoderBehavior::kWriteFieldNumber.
Precondition
Encoder has no active child encoder.
Postcondition
Until the nested child encoder has been destroyed, this encoder cannot be used.

◆ status()

Status pw::protobuf::StreamEncoder::status ( ) const
inline

Returns the current encoder's status.

While individual write calls return status objects, the encoder tracks all status returns and latches onto the first error encountered.

Precondition
Encoder has no active child encoder.

◆ WriteBool()

Status pw::protobuf::StreamEncoder::WriteBool ( uint32_t  field_number,
bool  value 
)
inline

Writes a proto bool key-value pair.

Precondition
Encoder has no active child encoder.

◆ WriteBytes() [1/2]

Status pw::protobuf::StreamEncoder::WriteBytes ( uint32_t  field_number,
ConstByteSpan  value 
)
inline

Writes a proto bytes field as a key-value pair. This can also be used to write a pre-encoded nested submessage directly without using a nested encoder.

Precondition
Encoder has no active child encoder.

◆ WriteBytes() [2/2]

Status pw::protobuf::StreamEncoder::WriteBytes ( uint32_t  field_number,
size_t  num_bytes,
FunctionRef< Status(stream::Writer &)>  write_func 
)
inline

Provides access to a stream writer to a proto bytes field through a given callback function. The function must write exactly num_bytes bytes of data to the stream.

Precondition
Encoder has no active child encoder.

◆ WriteBytesFromStream()

Status pw::protobuf::StreamEncoder::WriteBytesFromStream ( uint32_t  field_number,
stream::Reader bytes_reader,
size_t  num_bytes,
ByteSpan  stream_pipe_buffer 
)
inline

Writes a proto 'bytes' field from the stream bytes_reader.

The payload for the value is provided through the stream::Reader bytes_reader. The method reads a chunk of the data from the reader using the stream_pipe_buffer and writes it to the encoder.

Precondition
The stream_pipe_buffer.byte_size() >= 1
Encoder has no active child encoder.
Returns
  • OK - Bytes field is written successfully.
  • RESOURCE_EXHAUSTED - Exceeds write limits.
  • OUT_OF_RANGE - bytes_reader is exhausted before num_bytes of bytes is read.
  • Other errors encountered by the writer will be returned as it is.

◆ WriteDouble()

Status pw::protobuf::StreamEncoder::WriteDouble ( uint32_t  field_number,
double  value 
)
inline

Writes a proto double key-value pair.

Precondition
Encoder has no active child encoder.

◆ WriteFixed32()

Status pw::protobuf::StreamEncoder::WriteFixed32 ( uint32_t  field_number,
uint32_t  value 
)
inline

Writes a proto fixed32 key-value pair.

Precondition
Encoder has no active child encoder.

◆ WriteFixed64()

Status pw::protobuf::StreamEncoder::WriteFixed64 ( uint32_t  field_number,
uint64_t  value 
)
inline

Writes a proto fixed64 key-value pair.

Precondition
Encoder has no active child encoder.

◆ WriteFloat()

Status pw::protobuf::StreamEncoder::WriteFloat ( uint32_t  field_number,
float  value 
)
inline

Writes a proto float key-value pair.

Precondition
Encoder has no active child encoder.

◆ WriteInt32()

Status pw::protobuf::StreamEncoder::WriteInt32 ( uint32_t  field_number,
int32_t  value 
)
inline

Writes a proto int32 key-value pair.

Precondition
Encoder has no active child encoder.

◆ WriteInt64()

Status pw::protobuf::StreamEncoder::WriteInt64 ( uint32_t  field_number,
int64_t  value 
)
inline

Writes a proto int64 key-value pair.

Precondition
Encoder has no active child encoder.

◆ WriteNestedMessage()

Status pw::protobuf::StreamEncoder::WriteNestedMessage ( uint32_t  field_number,
FunctionRef< Status(StreamEncoder &)>  write_message,
EmptyEncoderBehavior  empty_encoder_behavior = EmptyEncoderBehavior::kWriteFieldNumber 
)

Invokes a given callback with an encoder to write a nested message field.

This performs a multi-pass encoding and invokes the callback twice: once to compute the total size of the nested message, and again to actually write the encoded data to the stream (after the nested message field prefix has been written).

Warning
The callable must write the exact same fields, with the exact same values, in the same order, on both invocations. If the data being written might change during writing, the caller is expected to capture a snapshot prior to encoding or implement explicit synchronization. Failure to do so may silently corrupt output data or produce an error result.
Parameters
[in]field_numberThe field number of the submessage to be written.
[in]write_messageA callable responsible for writing the submessage fields using the encoder passed to it. It must have the signature Status(StreamEncoder& encoder). It will be invoked twice and MUST perform the exact same set of writes on both invocations.
[in]empty_encoder_behaviorIndicates the action to take when nothing is written to the nested message encoder. Defaults to EmptyEncoderBehavior::kWriteFieldNumber.
Returns
  • OK: The nested message was successfully written.
  • OUT_OF_RANGE: The callback wrote fewer bytes on the second pass than on the first.
  • RESOURCE_EXHAUSTED: The callback wrote more bytes on the second pass than on the first.
  • Other statuses encountered from the underlying stream.
Precondition
Encoder has no active child encoder.

◆ WritePackedBool()

Status pw::protobuf::StreamEncoder::WritePackedBool ( uint32_t  field_number,
span< const bool >  values 
)
inline

Writes a repeated bool using packed encoding.

Precondition
Encoder has no active child encoder.

◆ WritePackedDouble()

Status pw::protobuf::StreamEncoder::WritePackedDouble ( uint32_t  field_number,
span< const double >  values 
)
inline

Writes a repeated double field using packed encoding.

Precondition
Encoder has no active child encoder.

◆ WritePackedEnum()

template<typename T , typename = std::enable_if_t<std::is_enum_v<T>>>
Status pw::protobuf::StreamEncoder::WritePackedEnum ( uint32_t  field_number,
span< const T >  values 
)
inline

Writes a repeated enum using packed encoding.

Precondition
Encoder has no active child encoder.

◆ WritePackedFixed32()

Status pw::protobuf::StreamEncoder::WritePackedFixed32 ( uint32_t  field_number,
span< const uint32_t >  values 
)
inline

Writes a repeated fixed32 field using packed encoding.

Precondition
Encoder has no active child encoder.

◆ WritePackedFixed64()

Status pw::protobuf::StreamEncoder::WritePackedFixed64 ( uint32_t  field_number,
span< const uint64_t >  values 
)
inline

Writes a repeated fixed64 field using packed encoding.

Precondition
Encoder has no active child encoder.

◆ WritePackedFloat()

Status pw::protobuf::StreamEncoder::WritePackedFloat ( uint32_t  field_number,
span< const float >  values 
)
inline

Writes a repeated float field using packed encoding.

Precondition
Encoder has no active child encoder.

◆ WritePackedInt32()

Status pw::protobuf::StreamEncoder::WritePackedInt32 ( uint32_t  field_number,
span< const int32_t >  values 
)
inline

Writes a repeated int32 using packed encoding.

Precondition
Encoder has no active child encoder.

◆ WritePackedInt64()

Status pw::protobuf::StreamEncoder::WritePackedInt64 ( uint32_t  field_number,
span< const int64_t >  values 
)
inline

Writes a repeated int64 using packed encoding.

Precondition
Encoder has no active child encoder.

◆ WritePackedSfixed32()

Status pw::protobuf::StreamEncoder::WritePackedSfixed32 ( uint32_t  field_number,
span< const int32_t >  values 
)
inline

Writes a repeated sfixed32 field using packed encoding.

Precondition
Encoder has no active child encoder.

◆ WritePackedSfixed64()

Status pw::protobuf::StreamEncoder::WritePackedSfixed64 ( uint32_t  field_number,
span< const int64_t >  values 
)
inline

Writes a repeated sfixed64 field using packed encoding.

Precondition
Encoder has no active child encoder.

◆ WritePackedSint32()

Status pw::protobuf::StreamEncoder::WritePackedSint32 ( uint32_t  field_number,
span< const int32_t >  values 
)
inline

Writes a repeated sint32 using packed encoding.

Precondition
Encoder has no active child encoder.

◆ WritePackedSint64()

Status pw::protobuf::StreamEncoder::WritePackedSint64 ( uint32_t  field_number,
span< const int64_t >  values 
)
inline

Writes a repeated sint64 using packed encoding.

Precondition
Encoder has no active child encoder.

◆ WritePackedUint32()

Status pw::protobuf::StreamEncoder::WritePackedUint32 ( uint32_t  field_number,
span< const uint32_t >  values 
)
inline

Writes a repeated uint32 using packed encoding.

Precondition
Encoder has no active child encoder.

◆ WritePackedUint64()

Status pw::protobuf::StreamEncoder::WritePackedUint64 ( uint32_t  field_number,
span< const uint64_t >  values 
)
inline

Writes a repeated uint64 using packed encoding.

Precondition
Encoder has no active child encoder.

◆ WriteRepeatedBool()

Status pw::protobuf::StreamEncoder::WriteRepeatedBool ( uint32_t  field_number,
const pw::Vector< bool > &  values 
)
inline

Writes a repeated bool using packed encoding.

Precondition
Encoder has no active child encoder.

◆ WriteRepeatedDouble()

Status pw::protobuf::StreamEncoder::WriteRepeatedDouble ( uint32_t  field_number,
const pw::Vector< double > &  values 
)
inline

Writes a repeated double field using packed encoding.

Precondition
Encoder has no active child encoder.

◆ WriteRepeatedFixed32()

Status pw::protobuf::StreamEncoder::WriteRepeatedFixed32 ( uint32_t  field_number,
const pw::Vector< uint32_t > &  values 
)
inline

Writes a repeated fixed32 field using packed encoding.

Precondition
Encoder has no active child encoder.

◆ WriteRepeatedFixed64()

Status pw::protobuf::StreamEncoder::WriteRepeatedFixed64 ( uint32_t  field_number,
const pw::Vector< uint64_t > &  values 
)
inline

Writes a repeated fixed64 field using packed encoding.

Precondition
Encoder has no active child encoder.

◆ WriteRepeatedFloat()

Status pw::protobuf::StreamEncoder::WriteRepeatedFloat ( uint32_t  field_number,
const pw::Vector< float > &  values 
)
inline

Writes a repeated float field using packed encoding.

Precondition
Encoder has no active child encoder.

◆ WriteRepeatedInt32()

Status pw::protobuf::StreamEncoder::WriteRepeatedInt32 ( uint32_t  field_number,
const pw::Vector< int32_t > &  values 
)
inline

Writes a repeated int32 using packed encoding.

Precondition
Encoder has no active child encoder.

◆ WriteRepeatedInt64()

Status pw::protobuf::StreamEncoder::WriteRepeatedInt64 ( uint32_t  field_number,
const pw::Vector< int64_t > &  values 
)
inline

Writes a repeated int64 using packed encoding.

Precondition
Encoder has no active child encoder.

◆ WriteRepeatedSfixed32()

Status pw::protobuf::StreamEncoder::WriteRepeatedSfixed32 ( uint32_t  field_number,
const pw::Vector< int32_t > &  values 
)
inline

Writes a repeated sfixed32 field using packed encoding.

Precondition
Encoder has no active child encoder.

◆ WriteRepeatedSfixed64()

Status pw::protobuf::StreamEncoder::WriteRepeatedSfixed64 ( uint32_t  field_number,
const pw::Vector< int64_t > &  values 
)
inline

Writes a repeated sfixed64 field using packed encoding.

Precondition
Encoder has no active child encoder.

◆ WriteRepeatedSint32()

Status pw::protobuf::StreamEncoder::WriteRepeatedSint32 ( uint32_t  field_number,
const pw::Vector< int32_t > &  values 
)
inline

Writes a repeated sint32 using packed encoding.

Precondition
Encoder has no active child encoder.

◆ WriteRepeatedSint64()

Status pw::protobuf::StreamEncoder::WriteRepeatedSint64 ( uint32_t  field_number,
const pw::Vector< int64_t > &  values 
)
inline

Writes a repeated sint64 using packed encoding.

Precondition
Encoder has no active child encoder.

◆ WriteRepeatedUint32()

Status pw::protobuf::StreamEncoder::WriteRepeatedUint32 ( uint32_t  field_number,
const pw::Vector< uint32_t > &  values 
)
inline

Writes a repeated uint32 using packed encoding.

Precondition
Encoder has no active child encoder.

◆ WriteRepeatedUint64()

Status pw::protobuf::StreamEncoder::WriteRepeatedUint64 ( uint32_t  field_number,
const pw::Vector< uint64_t > &  values 
)
inline

Writes a repeated uint64 using packed encoding.

Precondition
Encoder has no active child encoder.

◆ WriteSfixed32()

Status pw::protobuf::StreamEncoder::WriteSfixed32 ( uint32_t  field_number,
int32_t  value 
)
inline

Writes a proto sfixed32 key-value pair.

Precondition
Encoder has no active child encoder.

◆ WriteSfixed64()

Status pw::protobuf::StreamEncoder::WriteSfixed64 ( uint32_t  field_number,
int64_t  value 
)
inline

Writes a proto sfixed64 key-value pair.

Precondition
Encoder has no active child encoder.

◆ WriteSint32()

Status pw::protobuf::StreamEncoder::WriteSint32 ( uint32_t  field_number,
int32_t  value 
)
inline

Writes a proto sint32 key-value pair.

Precondition
Encoder has no active child encoder.

◆ WriteSint64()

Status pw::protobuf::StreamEncoder::WriteSint64 ( uint32_t  field_number,
int64_t  value 
)
inline

Writes a proto sint64 key-value pair.

Precondition
Encoder has no active child encoder.

◆ WriteString() [1/2]

Status pw::protobuf::StreamEncoder::WriteString ( uint32_t  field_number,
const char *  value,
size_t  len 
)
inline

Writes a proto string key-value pair.

Precondition
Encoder has no active child encoder.

◆ WriteString() [2/2]

Status pw::protobuf::StreamEncoder::WriteString ( uint32_t  field_number,
std::string_view  value 
)
inline

Writes a proto string key-value pair.

Precondition
Encoder has no active child encoder.

◆ WriteStringFromStream()

Status pw::protobuf::StreamEncoder::WriteStringFromStream ( uint32_t  field_number,
stream::Reader bytes_reader,
size_t  num_bytes,
ByteSpan  stream_pipe_buffer 
)
inline

Writes a proto 'string' field from the stream bytes_reader.

The payload for the value is provided through the stream::Reader bytes_reader. The method reads a chunk of the data from the reader using the stream_pipe_buffer and writes it to the encoder.

Precondition
The stream_pipe_buffer.byte_size() >= 1
Encoder has no active child encoder.
Returns
  • OK - String field is written successfully.
  • RESOURCE_EXHAUSTED - Exceeds write limits.
  • OUT_OF_RANGE - bytes_reader is exhausted before num_bytes of bytes is read.
  • Other errors encountered by the writer will be returned as it is.

◆ WriteUint32()

Status pw::protobuf::StreamEncoder::WriteUint32 ( uint32_t  field_number,
uint32_t  value 
)
inline

Writes a proto uint32 key-value pair.

Precondition
Encoder has no active child encoder.

◆ WriteUint64()

Status pw::protobuf::StreamEncoder::WriteUint64 ( uint32_t  field_number,
uint64_t  value 
)
inline

Writes a proto uint64 key-value pair.

Precondition
Encoder has no active child encoder.

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