Class CodedOutputStream (3.27.1) 

public sealed class CodedOutputStream : IDisposable

Encodes and writes protocol message fields.

Inheritance

object > CodedOutputStream

Implements

IDisposable

Namespace

Google.Protobuf

Assembly

Google.Protobuf.dll

Remarks

This class is generally used by generated code to write appropriate primitives to the stream. It effectively encapsulates the lowest levels of protocol buffer format. Unlike some other implementations, this does not include combined "write tag and value" methods. Generated code knows the exact byte representations of the tags they're going to write, so there's no need to re-encode them each time. Manually-written code calling this class should just call one of the WriteTag overloads before each value.

Repeated fields and map fields are not handled by this class; use RepeatedField<T> and MapField<TKey, TValue> to serialize such fields.

Constructors

CodedOutputStream(byte[])

public CodedOutputStream(byte[] flatArray)

Creates a new CodedOutputStream that writes directly to the given byte array. If more bytes are written than fit in the array, OutOfSpaceException will be thrown.

Parameter
Name Description
flatArray byte

CodedOutputStream(Stream)

public CodedOutputStream(Stream output)

Creates a new CodedOutputStream which write to the given stream, and disposes of that stream when the returned CodedOutputStream is disposed.

Parameter
Name Description
output Stream

The stream to write to. It will be disposed when the returned CodedOutputStream is disposed.

CodedOutputStream(Stream, bool)

public CodedOutputStream(Stream output, bool leaveOpen)

Creates a new CodedOutputStream which write to the given stream.

Parameters
Name Description
output Stream

The stream to write to.
leaveOpen bool

If true, output is left open when the returned CodedOutputStream is disposed; if false, the provided stream is disposed as well.

CodedOutputStream(Stream, int)

public CodedOutputStream(Stream output, int bufferSize)

Creates a new CodedOutputStream which write to the given stream and uses the specified buffer size.

Parameters
Name Description
output Stream

The stream to write to. It will be disposed when the returned CodedOutputStream is disposed.
bufferSize int

The size of buffer to use internally.

CodedOutputStream(Stream, int, bool)

public CodedOutputStream(Stream output, int bufferSize, bool leaveOpen)

Creates a new CodedOutputStream which write to the given stream and uses the specified buffer size.

Parameters
Name Description
output Stream

The stream to write to.
bufferSize int

The size of buffer to use internally.
leaveOpen bool

If true, output is left open when the returned CodedOutputStream is disposed; if false, the provided stream is disposed as well.

Fields

DefaultBufferSize

public static readonly int DefaultBufferSize

The buffer size used by CreateInstance(Stream).

Field Value
Type Description
int

Properties

Deterministic

public bool Deterministic { get; set; }

Configures whether or not serialization is deterministic.

Property Value
Type Description
bool
Remarks

Deterministic serialization guarantees that for a given binary, equal messages (defined by the equals methods in protos) will always be serialized to the same bytes. This implies:

  • Repeated serialization of a message will return the same bytes.
  • Different processes of the same binary (which may be executing on different machines) will serialize equal messages to the same bytes.
Note the deterministic serialization is NOT canonical across languages; it is also unstable across different builds with schema changes due to unknown fields. Users who need canonical serialization, e.g. persistent storage in a canonical form, fingerprinting, etc, should define their own canonicalization specification and implement the serializer using reflection APIs rather than relying on this API. Once set, the serializer will: (Note this is an implementation detail and may subject to change in the future)
  • Sort map entries by keys in lexicographical order or numerical order. Note: For string keys, the order is based on comparing the UTF-16 code unit value of each character in the strings. The order may be different from the deterministic serialization in other languages where maps are sorted on the lexicographical order of the UTF8 encoded keys.

Position

public long Position { get; }

Returns the current position in the stream, or the position in the output buffer

Property Value
Type Description
long

SpaceLeft

public int SpaceLeft { get; }

If writing to a flat array, returns the space left in the array. Otherwise, throws an InvalidOperationException.

Property Value
Type Description
int

Methods

CheckNoSpaceLeft()

public void CheckNoSpaceLeft()

Verifies that SpaceLeft returns zero. It's common to create a byte array that is exactly big enough to hold a message, then write to it with a CodedOutputStream. Calling CheckNoSpaceLeft after writing verifies that the message was actually as big as expected, which can help finding bugs.

ComputeBoolSize(bool)

public static int ComputeBoolSize(bool value)

Computes the number of bytes that would be needed to encode a bool field, including the tag.

Parameter
Name Description
value bool
Returns
Type Description
int

ComputeBytesSize(ByteString)

public static int ComputeBytesSize(ByteString value)

Computes the number of bytes that would be needed to encode a bytes field, including the tag.

Parameter
Name Description
value ByteString
Returns
Type Description
int

ComputeDoubleSize(double)

public static int ComputeDoubleSize(double value)

Computes the number of bytes that would be needed to encode a double field, including the tag.

Parameter
Name Description
value double
Returns
Type Description
int

ComputeEnumSize(int)

public static int ComputeEnumSize(int value)

Computes the number of bytes that would be needed to encode a enum field, including the tag. The caller is responsible for converting the enum value to its numeric value.

Parameter
Name Description
value int
Returns
Type Description
int

ComputeFixed32Size(uint)

public static int ComputeFixed32Size(uint value)

Computes the number of bytes that would be needed to encode a fixed32 field, including the tag.

Parameter
Name Description
value uint
Returns
Type Description
int

ComputeFixed64Size(ulong)

public static int ComputeFixed64Size(ulong value)

Computes the number of bytes that would be needed to encode a fixed64 field, including the tag.

Parameter
Name Description
value ulong
Returns
Type Description
int

ComputeFloatSize(float)

public static int ComputeFloatSize(float value)

Computes the number of bytes that would be needed to encode a float field, including the tag.

Parameter
Name Description
value float
Returns
Type Description
int

ComputeGroupSize(IMessage)

public static int ComputeGroupSize(IMessage value)

Computes the number of bytes that would be needed to encode a group field, including the tag.

Parameter
Name Description
value IMessage
Returns
Type Description
int

ComputeInt32Size(int)

public static int ComputeInt32Size(int value)

Computes the number of bytes that would be needed to encode an int32 field, including the tag.

Parameter
Name Description
value int
Returns
Type Description
int

ComputeInt64Size(long)

public static int ComputeInt64Size(long value)

Computes the number of bytes that would be needed to encode an int64 field, including the tag.

Parameter
Name Description
value long
Returns
Type Description
int

ComputeLengthSize(int)

public static int ComputeLengthSize(int length)

Computes the number of bytes that would be needed to encode a length, as written by WriteLength(int).

Parameter
Name Description
length int
Returns
Type Description
int

ComputeMessageSize(IMessage)

public static int ComputeMessageSize(IMessage value)

Computes the number of bytes that would be needed to encode an embedded message field, including the tag.

Parameter
Name Description
value IMessage
Returns
Type Description
int

ComputeRawVarint32Size(uint)

public static int ComputeRawVarint32Size(uint value)

Computes the number of bytes that would be needed to encode a varint.

Parameter
Name Description
value uint
Returns
Type Description
int

ComputeRawVarint64Size(ulong)

public static int ComputeRawVarint64Size(ulong value)

Computes the number of bytes that would be needed to encode a varint.

Parameter
Name Description
value ulong
Returns
Type Description
int

ComputeSFixed32Size(int)

public static int ComputeSFixed32Size(int value)

Computes the number of bytes that would be needed to encode an sfixed32 field, including the tag.

Parameter
Name Description
value int
Returns
Type Description
int

ComputeSFixed64Size(long)

public static int ComputeSFixed64Size(long value)

Computes the number of bytes that would be needed to encode an sfixed64 field, including the tag.

Parameter
Name Description
value long
Returns
Type Description
int

ComputeSInt32Size(int)

public static int ComputeSInt32Size(int value)

Computes the number of bytes that would be needed to encode an sint32 field, including the tag.

Parameter
Name Description
value int
Returns
Type Description
int

ComputeSInt64Size(long)

public static int ComputeSInt64Size(long value)

Computes the number of bytes that would be needed to encode an sint64 field, including the tag.

Parameter
Name Description
value long
Returns
Type Description
int

ComputeStringSize(string)

public static int ComputeStringSize(string value)

Computes the number of bytes that would be needed to encode a string field, including the tag.

Parameter
Name Description
value string
Returns
Type Description
int

ComputeTagSize(int)

public static int ComputeTagSize(int fieldNumber)

Computes the number of bytes that would be needed to encode a tag.

Parameter
Name Description
fieldNumber int
Returns
Type Description
int

ComputeUInt32Size(uint)

public static int ComputeUInt32Size(uint value)

Computes the number of bytes that would be needed to encode a uint32 field, including the tag.

Parameter
Name Description
value uint
Returns
Type Description
int

ComputeUInt64Size(ulong)

public static int ComputeUInt64Size(ulong value)

Computes the number of bytes that would be needed to encode a uint64 field, including the tag.

Parameter
Name Description
value ulong
Returns
Type Description
int

Dispose()

public void Dispose()

Flushes any buffered data and optionally closes the underlying stream, if any.

Remarks

By default, any underlying stream is closed by this method. To configure this behaviour, use a constructor overload with a leaveOpen parameter. If this instance does not have an underlying stream, this method does nothing.

For the sake of efficiency, calling this method does not prevent future write calls - but if a later write ends up writing to a stream which has been disposed, that is likely to fail. It is recommend that you not call any other methods after this.

Flush()

public void Flush()

Flushes any buffered data to the underlying stream (if there is one).

WriteBool(bool)

public void WriteBool(bool value)

Writes a bool field value, without a tag, to the stream.

Parameter
Name Description
value bool

The value to write

WriteBytes(ByteString)

public void WriteBytes(ByteString value)

Write a byte string, without a tag, to the stream. The data is length-prefixed.

Parameter
Name Description
value ByteString

The value to write

WriteDouble(double)

public void WriteDouble(double value)

Writes a double field value, without a tag, to the stream.

Parameter
Name Description
value double

The value to write

WriteEnum(int)

public void WriteEnum(int value)

Writes an enum value, without a tag, to the stream.

Parameter
Name Description
value int

The value to write

WriteFixed32(uint)

public void WriteFixed32(uint value)

Writes a fixed32 field value, without a tag, to the stream.

Parameter
Name Description
value uint

The value to write

WriteFixed64(ulong)

public void WriteFixed64(ulong value)

Writes a fixed64 field value, without a tag, to the stream.

Parameter
Name Description
value ulong

The value to write

WriteFloat(float)

public void WriteFloat(float value)

Writes a float field value, without a tag, to the stream.

Parameter
Name Description
value float

The value to write

WriteGroup(IMessage)

public void WriteGroup(IMessage value)

Writes a group, without a tag, to the stream.

Parameter
Name Description
value IMessage

The value to write

WriteInt32(int)

public void WriteInt32(int value)

Writes an int32 field value, without a tag, to the stream.

Parameter
Name Description
value int

The value to write

WriteInt64(long)

public void WriteInt64(long value)

Writes an int64 field value, without a tag, to the stream.

Parameter
Name Description
value long

The value to write

WriteLength(int)

public void WriteLength(int length)

Writes a length (in bytes) for length-delimited data.

Parameter
Name Description
length int

Length value, in bytes.
Remarks

This method simply writes a rawint, but exists for clarity in calling code.

WriteMessage(IMessage)

public void WriteMessage(IMessage value)

Writes a message, without a tag, to the stream. The data is length-prefixed.

Parameter
Name Description
value IMessage

The value to write

WriteRawMessage(IMessage)

public void WriteRawMessage(IMessage value)

Writes a message, without a tag, to the stream. Only the message data is written, without a length-delimiter.

Parameter
Name Description
value IMessage

The value to write

WriteRawTag(byte)

public void WriteRawTag(byte b1)

Writes the given single-byte tag directly to the stream.

Parameter
Name Description
b1 byte

The encoded tag

WriteRawTag(byte, byte)

public void WriteRawTag(byte b1, byte b2)

Writes the given two-byte tag directly to the stream.

Parameters
Name Description
b1 byte

The first byte of the encoded tag
b2 byte

The second byte of the encoded tag

WriteRawTag(byte, byte, byte)

public void WriteRawTag(byte b1, byte b2, byte b3)

Writes the given three-byte tag directly to the stream.

Parameters
Name Description
b1 byte

The first byte of the encoded tag
b2 byte

The second byte of the encoded tag
b3 byte

The third byte of the encoded tag

WriteRawTag(byte, byte, byte, byte)

public void WriteRawTag(byte b1, byte b2, byte b3, byte b4)

Writes the given four-byte tag directly to the stream.

Parameters
Name Description
b1 byte

The first byte of the encoded tag
b2 byte

The second byte of the encoded tag
b3 byte

The third byte of the encoded tag
b4 byte

The fourth byte of the encoded tag

WriteRawTag(byte, byte, byte, byte, byte)

public void WriteRawTag(byte b1, byte b2, byte b3, byte b4, byte b5)

Writes the given five-byte tag directly to the stream.

Parameters
Name Description
b1 byte

The first byte of the encoded tag
b2 byte

The second byte of the encoded tag
b3 byte

The third byte of the encoded tag
b4 byte

The fourth byte of the encoded tag
b5 byte

The fifth byte of the encoded tag

WriteSFixed32(int)

public void WriteSFixed32(int value)

Writes an sfixed32 value, without a tag, to the stream.

Parameter
Name Description
value int

The value to write.

WriteSFixed64(long)

public void WriteSFixed64(long value)

Writes an sfixed64 value, without a tag, to the stream.

Parameter
Name Description
value long

The value to write

WriteSInt32(int)

public void WriteSInt32(int value)

Writes an sint32 value, without a tag, to the stream.

Parameter
Name Description
value int

The value to write

WriteSInt64(long)

public void WriteSInt64(long value)

Writes an sint64 value, without a tag, to the stream.

Parameter
Name Description
value long

The value to write

WriteString(string)

public void WriteString(string value)

Writes a string field value, without a tag, to the stream. The data is length-prefixed.

Parameter
Name Description
value string

The value to write

WriteTag(int, WireType)

public void WriteTag(int fieldNumber, WireFormat.WireType type)

Encodes and writes a tag.

Parameters
Name Description
fieldNumber int

The number of the field to write the tag for
type WireFormatWireType

The wire format type of the tag to write

WriteTag(uint)

public void WriteTag(uint tag)

Writes an already-encoded tag.

Parameter
Name Description
tag uint

The encoded tag

WriteUInt32(uint)

public void WriteUInt32(uint value)

Writes a uint32 value, without a tag, to the stream.

Parameter
Name Description
value uint

The value to write

WriteUInt64(ulong)

public void WriteUInt64(ulong value)

Writes a uint64 field value, without a tag, to the stream.

Parameter
Name Description
value ulong

The value to write