ProtoOutputStream

public final class ProtoOutputStream
extends Object

java.lang.Object
   ↳ android.util.proto.ProtoOutputStream


Class to write to a protobuf stream.

This API is not as convenient or type safe as the standard protobuf classes. If possible, the best recommended library is to use protobuf lite. However, in environments (such as the Android platform itself), a more memory efficient version is necessary.

Each write method takes an ID code from the protoc generated classes and the value to write. To make a nested object, call start(long) and then end(long) when you are done.

The ID codes have type information embedded into them, so if you call the incorrect function you will get an IllegalArgumentException.

To retrieve the encoded protobuf stream, call getBytes(). stream as the top-level objects are finished.

Summary

Constants

long FIELD_COUNT_MASK

Bit mask for selecting the field count when reading a field id that is used with a ProtoOutputStream.write(...) method.

long FIELD_COUNT_PACKED

Repeated packed field count, encoded into a field id used with a ProtoOutputStream.write(...) method.

long FIELD_COUNT_REPEATED

Repeated field count, encoded into a field id used with a ProtoOutputStream.write(...) method.

int FIELD_COUNT_SHIFT

Bit offset for building a field id to be used with a ProtoOutputStream.write(...).

long FIELD_COUNT_SINGLE

Single field count, encoded into a field id used with a ProtoOutputStream.write(...) method.

long FIELD_COUNT_UNKNOWN

Unknown field count, encoded into a field id used with a ProtoOutputStream.write(...) method.

int FIELD_ID_SHIFT

Number of bits to shift the field number to form a tag.

long FIELD_TYPE_BOOL

Field type code for bool fields.

long FIELD_TYPE_BYTES

Field type code for bytes fields.

long FIELD_TYPE_DOUBLE

Field type code for double fields.

long FIELD_TYPE_ENUM

Field type code for enum fields.

long FIELD_TYPE_FIXED32

Field type code for fixed32 fields.

long FIELD_TYPE_FIXED64

Field type code for fixed64 fields.

long FIELD_TYPE_FLOAT

Field type code for float fields.

long FIELD_TYPE_INT32

Field type code for int32 fields.

long FIELD_TYPE_INT64

Field type code for int64 fields.

long FIELD_TYPE_MASK

Mask for the field types stored in a fieldId.

long FIELD_TYPE_MESSAGE

Field type code for message fields.

long FIELD_TYPE_SFIXED32

Field type code for sfixed32 fields.

long FIELD_TYPE_SFIXED64

Field type code for sfixed64 fields.

int FIELD_TYPE_SHIFT

Position of the field type in a (long) fieldId.

long FIELD_TYPE_SINT32

Field type code for sint32 fields.

long FIELD_TYPE_SINT64

Field type code for sint64 fields.

long FIELD_TYPE_STRING

Field type code for string fields.

long FIELD_TYPE_UINT32

Field type code for uint32 fields.

long FIELD_TYPE_UINT64

Field type code for uint64 fields.

int WIRE_TYPE_END_GROUP

End group wire type code.

int WIRE_TYPE_FIXED32

Fixed32 wire type code.

int WIRE_TYPE_FIXED64

Fixed64 wire type code.

int WIRE_TYPE_LENGTH_DELIMITED

Length delimited wire type code.

int WIRE_TYPE_MASK

Mask to select the wire type from a tag.

int WIRE_TYPE_START_GROUP

Start group wire type code.

int WIRE_TYPE_VARINT

Varint wire type code.

Public constructors

ProtoOutputStream()

Construct a ProtoOutputStream with the default chunk size.

ProtoOutputStream(int chunkSize)

Construct a with the given chunk size.

This is for an in-memory proto. The caller should use {@link #getBytes()} for the result.

ProtoOutputStream(OutputStream stream)

Construct a ProtoOutputStream that sits on top of an OutputStream.

Public methods

static int checkFieldId(long fieldId, long expectedFlags)

Validates that the fieldId provided is of the type and count from expectedType.

void dump(String tag)

Dump debugging data about the buffers with the given log tag.

void end(long token)

End the object started by start() that returned token.

void flush()

Write remaining data to the output stream.

byte[] getBytes()

Finish the encoding of the data, and return a byte[] with the protobuf formatted data.

static String getFieldCountString(long fieldCount)

Get the developer-usable name of a field count.

static String getFieldIdString(long fieldId)

Get a debug string for a fieldId.

static String getFieldTypeString(long fieldType)

Get the developer-usable name of a field type.

int getRawSize()

Returns the total size of the data that has been written, after full protobuf encoding has occurred.

static String getWireTypeString(int wireType)

Get the developer-usable name of a wire type.

static long makeFieldId(int id, long fieldFlags)

Combine a fieldId (the field keys in the proto file) and the field flags.

static long makeToken(int tagSize, boolean repeated, int depth, int objectId, int offset)

Make a token.

long start(long fieldId)

Start a sub object.

static String token2String(long token)

Return a debugging string of a token.

void write(long fieldId, String val)

Write a string value for the given fieldId.

void write(long fieldId, boolean val)

Write a boolean value for the given fieldId.

void write(long fieldId, int val)

Write a value for the given fieldId.

void write(long fieldId, float val)

Write a value for the given fieldId.

void write(long fieldId, long val)

Write a value for the given fieldId.

void write(long fieldId, double val)

Write a value for the given fieldId.

void write(long fieldId, byte[] val)

Write a byte[] value for the given fieldId.

void writeTag(int id, int wireType)

Write an individual field tag by hand.

Inherited methods

Constants

FIELD_COUNT_MASK

public static final long FIELD_COUNT_MASK

Bit mask for selecting the field count when reading a field id that is used with a ProtoOutputStream.write(...) method.

Constant Value: 16492674416640 (0x00000f0000000000)

FIELD_COUNT_PACKED

public static final long FIELD_COUNT_PACKED

Repeated packed field count, encoded into a field id used with a ProtoOutputStream.write(...) method.

Constant Value: 5497558138880 (0x0000050000000000)

FIELD_COUNT_REPEATED

public static final long FIELD_COUNT_REPEATED

Repeated field count, encoded into a field id used with a ProtoOutputStream.write(...) method.

Constant Value: 2199023255552 (0x0000020000000000)

FIELD_COUNT_SHIFT

public static final int FIELD_COUNT_SHIFT

Bit offset for building a field id to be used with a ProtoOutputStream.write(...).

Constant Value: 40 (0x00000028)

FIELD_COUNT_SINGLE

public static final long FIELD_COUNT_SINGLE

Single field count, encoded into a field id used with a ProtoOutputStream.write(...) method.

Constant Value: 1099511627776 (0x0000010000000000)

FIELD_COUNT_UNKNOWN

public static final long FIELD_COUNT_UNKNOWN

Unknown field count, encoded into a field id used with a ProtoOutputStream.write(...) method.

Constant Value: 0 (0x0000000000000000)

FIELD_ID_SHIFT

public static final int FIELD_ID_SHIFT

Number of bits to shift the field number to form a tag.

 // Reading a field number from a tag.
 int fieldNumber = tag >>> FIELD_ID_SHIFT;

 // Building a tag from a field number and a wire type.
 int tag = (fieldNumber << FIELD_ID_SHIFT) | wireType;
 

See also:

Constant Value: 3 (0x00000003)

FIELD_TYPE_BOOL

public static final long FIELD_TYPE_BOOL

Field type code for bool fields. Used to build constants in generated code for use with the ProtoOutputStream.write(long, boolean) method.

Constant Value: 34359738368 (0x0000000800000000)

FIELD_TYPE_BYTES

public static final long FIELD_TYPE_BYTES

Field type code for bytes fields. Used to build constants in generated code for use with the ProtoOutputStream.write(long, byte[]) method.

Constant Value: 51539607552 (0x0000000c00000000)

FIELD_TYPE_DOUBLE

public static final long FIELD_TYPE_DOUBLE

Field type code for double fields. Used to build constants in generated code for use with the ProtoOutputStream.write(long, double) method.

Constant Value: 4294967296 (0x0000000100000000)

FIELD_TYPE_ENUM

public static final long FIELD_TYPE_ENUM

Field type code for enum fields. Used to build constants in generated code for use with the ProtoOutputStream.write(long, int) method.

Constant Value: 60129542144 (0x0000000e00000000)

FIELD_TYPE_FIXED32

public static final long FIELD_TYPE_FIXED32

Field type code for fixed32 fields. Used to build constants in generated code for use with the ProtoOutputStream.write(long, int) method.

Constant Value: 30064771072 (0x0000000700000000)

FIELD_TYPE_FIXED64

public static final long FIELD_TYPE_FIXED64

Field type code for fixed64 fields. Used to build constants in generated code for use with the ProtoOutputStream.write(long, long) method.

Constant Value: 25769803776 (0x0000000600000000)

FIELD_TYPE_FLOAT

public static final long FIELD_TYPE_FLOAT

Field type code for float fields. Used to build constants in generated code for use with the ProtoOutputStream.write(long, float) method.

Constant Value: 8589934592 (0x0000000200000000)

FIELD_TYPE_INT32

public static final long FIELD_TYPE_INT32

Field type code for int32 fields. Used to build constants in generated code for use with the ProtoOutputStream.write(long, int) method.

Constant Value: 21474836480 (0x0000000500000000)

FIELD_TYPE_INT64

public static final long FIELD_TYPE_INT64

Field type code for int64 fields. Used to build constants in generated code for use with the ProtoOutputStream.write(long, long) method.

Constant Value: 12884901888 (0x0000000300000000)

FIELD_TYPE_MASK

public static final long FIELD_TYPE_MASK

Mask for the field types stored in a fieldId. Leaves a whole byte for future expansion, even though there are currently only 17 types.

Constant Value: 1095216660480 (0x000000ff00000000)

FIELD_TYPE_MESSAGE

public static final long FIELD_TYPE_MESSAGE

Field type code for message fields. Used to build constants in generated code for use with the ProtoOutputStream.start(long) method.

Constant Value: 47244640256 (0x0000000b00000000)

FIELD_TYPE_SFIXED32

public static final long FIELD_TYPE_SFIXED32

Field type code for sfixed32 fields. Used to build constants in generated code for use with the ProtoOutputStream.write(long, int) method.

Constant Value: 64424509440 (0x0000000f00000000)

FIELD_TYPE_SFIXED64

public static final long FIELD_TYPE_SFIXED64

Field type code for sfixed64 fields. Used to build constants in generated code for use with the ProtoOutputStream.write(long, long) method.

Constant Value: 68719476736 (0x0000001000000000)

FIELD_TYPE_SHIFT

public static final int FIELD_TYPE_SHIFT

Position of the field type in a (long) fieldId.

Constant Value: 32 (0x00000020)

FIELD_TYPE_SINT32

public static final long FIELD_TYPE_SINT32

Field type code for sint32 fields. Used to build constants in generated code for use with the ProtoOutputStream.write(long, int) method.

Constant Value: 73014444032 (0x0000001100000000)

FIELD_TYPE_SINT64

public static final long FIELD_TYPE_SINT64

Field type code for sint64 fields. Used to build constants in generated code for use with the ProtoOutputStream.write(long, long) method.

Constant Value: 77309411328 (0x0000001200000000)

FIELD_TYPE_STRING

public static final long FIELD_TYPE_STRING

Field type code for string fields. Used to build constants in generated code for use with the ProtoOutputStream.write(long, String) method.

Constant Value: 38654705664 (0x0000000900000000)

FIELD_TYPE_UINT32

public static final long FIELD_TYPE_UINT32

Field type code for uint32 fields. Used to build constants in generated code for use with the ProtoOutputStream.write(long, int) method.

Constant Value: 55834574848 (0x0000000d00000000)

FIELD_TYPE_UINT64

public static final long FIELD_TYPE_UINT64

Field type code for uint64 fields. Used to build constants in generated code for use with the ProtoOutputStream.write(long, long) method.

Constant Value: 17179869184 (0x0000000400000000)

WIRE_TYPE_END_GROUP

public static final int WIRE_TYPE_END_GROUP

End group wire type code.

See also:

Constant Value: 4 (0x00000004)

WIRE_TYPE_FIXED32

public static final int WIRE_TYPE_FIXED32

Fixed32 wire type code.

See also:

Constant Value: 5 (0x00000005)

WIRE_TYPE_FIXED64

public static final int WIRE_TYPE_FIXED64

Fixed64 wire type code.

See also:

Constant Value: 1 (0x00000001)

WIRE_TYPE_LENGTH_DELIMITED

public static final int WIRE_TYPE_LENGTH_DELIMITED

Length delimited wire type code.

See also:

Constant Value: 2 (0x00000002)

WIRE_TYPE_MASK

public static final int WIRE_TYPE_MASK

Mask to select the wire type from a tag.

 // Reading a wire type from a tag.
 int wireType = tag & WIRE_TYPE_MASK;

 // Building a tag from a field number and a wire type.
 int tag = (fieldNumber << FIELD_ID_SHIFT) | wireType;
 

See also:

Constant Value: 7 (0x00000007)

WIRE_TYPE_START_GROUP

public static final int WIRE_TYPE_START_GROUP

Start group wire type code.

See also:

Constant Value: 3 (0x00000003)

WIRE_TYPE_VARINT

public static final int WIRE_TYPE_VARINT

Varint wire type code.

See also:

Constant Value: 0 (0x00000000)

Public constructors

ProtoOutputStream

Added in API level 30
public ProtoOutputStream ()

Construct a ProtoOutputStream with the default chunk size.

This is for an in-memory proto. The caller should use getBytes() for the result.

ProtoOutputStream

Added in API level 30
public ProtoOutputStream (int chunkSize)

Construct a with the given chunk size.

This is for an in-memory proto. The caller should use {@link #getBytes()} for the result.

Parameters
chunkSize int

ProtoOutputStream

Added in API level 30
public ProtoOutputStream (OutputStream stream)

Construct a ProtoOutputStream that sits on top of an OutputStream.

The flush() method must be called when done writing to flush any remaining data, although data *may* be written at intermediate points within the writing as well.

Parameters
stream OutputStream: This value cannot be null.

Public methods

checkFieldId

Added in API level 30
public static int checkFieldId (long fieldId, 
                long expectedFlags)

Validates that the fieldId provided is of the type and count from expectedType.

The type must match exactly to pass this check.

The count must match according to this truth table to pass the check: expectedFlags UNKNOWN SINGLE REPEATED PACKED fieldId UNKNOWN true false false false SINGLE x true false false REPEATED x false true false PACKED x false true true

Parameters
fieldId long

expectedFlags long

Returns
int The raw ID of that field.

Throws
java.lang.IllegalArgumentException IllegalArgumentException} if it is not.

dump

Added in API level 30
public void dump (String tag)

Dump debugging data about the buffers with the given log tag.

Parameters
tag String: This value cannot be null.

end

Added in API level 30
public void end (long token)

End the object started by start() that returned token.

Parameters
token long: The token returned from start(long)

flush

Added in API level 30
public void flush ()

Write remaining data to the output stream. If there is no output stream, this function does nothing. Any currently open objects (i.e. ones that have not had end(long) called for them will not be written). Whether this writes objects that are closed if there are remaining open objects is undefined (current implementation does not write it, future ones will). For now, can either call getBytes() or flush(), but not both.

getBytes

Added in API level 30
public byte[] getBytes ()

Finish the encoding of the data, and return a byte[] with the protobuf formatted data.

After this call, do not call any of the write* functions. The behavior is undefined.

Returns
byte[] This value cannot be null.

getFieldCountString

Added in API level 30
public static String getFieldCountString (long fieldCount)

Get the developer-usable name of a field count.

Parameters
fieldCount long

Returns
String This value may be null.

getFieldIdString

Added in API level 30
public static String getFieldIdString (long fieldId)

Get a debug string for a fieldId.

Parameters
fieldId long

Returns
String This value cannot be null.

getFieldTypeString

Added in API level 30
public static String getFieldTypeString (long fieldType)

Get the developer-usable name of a field type.

Parameters
fieldType long: Value is android.util.proto.ProtoStream.FIELD_TYPE_UNKNOWN, android.util.proto.ProtoStream.FIELD_TYPE_DOUBLE, android.util.proto.ProtoStream.FIELD_TYPE_FLOAT, android.util.proto.ProtoStream.FIELD_TYPE_INT64, android.util.proto.ProtoStream.FIELD_TYPE_UINT64, android.util.proto.ProtoStream.FIELD_TYPE_INT32, android.util.proto.ProtoStream.FIELD_TYPE_FIXED64, android.util.proto.ProtoStream.FIELD_TYPE_FIXED32, android.util.proto.ProtoStream.FIELD_TYPE_BOOL, android.util.proto.ProtoStream.FIELD_TYPE_STRING, android.util.proto.ProtoStream.FIELD_TYPE_MESSAGE, android.util.proto.ProtoStream.FIELD_TYPE_BYTES, android.util.proto.ProtoStream.FIELD_TYPE_UINT32, android.util.proto.ProtoStream.FIELD_TYPE_ENUM, android.util.proto.ProtoStream.FIELD_TYPE_SFIXED32, android.util.proto.ProtoStream.FIELD_TYPE_SFIXED64, android.util.proto.ProtoStream.FIELD_TYPE_SINT32, or android.util.proto.ProtoStream.FIELD_TYPE_SINT64

Returns
String This value may be null.

getRawSize

Added in API level 30
public int getRawSize ()

Returns the total size of the data that has been written, after full protobuf encoding has occurred.

Returns
int the uncompressed buffer size

getWireTypeString

Added in API level 30
public static String getWireTypeString (int wireType)

Get the developer-usable name of a wire type.

Parameters
wireType int: Value is android.util.proto.ProtoStream.WIRE_TYPE_VARINT, android.util.proto.ProtoStream.WIRE_TYPE_FIXED64, android.util.proto.ProtoStream.WIRE_TYPE_LENGTH_DELIMITED, android.util.proto.ProtoStream.WIRE_TYPE_START_GROUP, android.util.proto.ProtoStream.WIRE_TYPE_END_GROUP, or android.util.proto.ProtoStream.WIRE_TYPE_FIXED32

Returns
String This value may be null.

makeFieldId

Added in API level 30
public static long makeFieldId (int id, 
                long fieldFlags)

Combine a fieldId (the field keys in the proto file) and the field flags. Mostly useful for testing because the generated code contains the fieldId constants.

Parameters
id int

fieldFlags long

Returns
long

makeToken

Added in API level 30
public static long makeToken (int tagSize, 
                boolean repeated, 
                int depth, 
                int objectId, 
                int offset)

Make a token. Bits 61-63 - tag size (So we can go backwards later if the object had not data) - 3 bits, max value 7, max value needed 5 Bit 60 - true if the object is repeated (lets us require endObject or endRepeatedObject) Bits 59-51 - depth (For error checking) - 9 bits, max value 512, when checking, value is masked (if we really are more than 512 levels deep) Bits 32-50 - objectId (For error checking) - 19 bits, max value 524,288. that's a lot of objects. IDs will wrap because of the overflow, and only the tokens are compared. Bits 0-31 - offset of interest for the object.

Parameters
tagSize int

repeated boolean

depth int

objectId int

offset int

Returns
long

start

Added in API level 30
public long start (long fieldId)

Start a sub object.

Parameters
fieldId long: The field identifier constant from the generated class.

Returns
long The token to call end(long) with.

token2String

Added in API level 30
public static String token2String (long token)

Return a debugging string of a token.

Parameters
token long

Returns
String This value cannot be null.

write

Added in API level 30
public void write (long fieldId, 
                String val)

Write a string value for the given fieldId.

If the field is not a string field, an exception will be thrown.

Parameters
fieldId long: The field identifier constant from the generated class.

val String: The value. This value may be null.

write

Added in API level 30
public void write (long fieldId, 
                boolean val)

Write a boolean value for the given fieldId.

If the field is not a bool field, an IllegalStateException will be thrown.

Parameters
fieldId long: The field identifier constant from the generated class.

val boolean: The value.

write

Added in API level 30
public void write (long fieldId, 
                int val)

Write a value for the given fieldId.

Will automatically convert for the following field types, and throw an exception for others: double, float, int32, int64, uint32, uint64, sint32, sint64, fixed32, fixed64, sfixed32, sfixed64, bool, enum.

Parameters
fieldId long: The field identifier constant from the generated class.

val int: The value.

write

Added in API level 30
public void write (long fieldId, 
                float val)

Write a value for the given fieldId.

Will automatically convert for the following field types, and throw an exception for others: double, float, int32, int64, uint32, uint64, sint32, sint64, fixed32, fixed64, sfixed32, sfixed64, bool, enum.

Parameters
fieldId long: The field identifier constant from the generated class.

val float: The value.

write

Added in API level 30
public void write (long fieldId, 
                long val)

Write a value for the given fieldId.

Will automatically convert for the following field types, and throw an exception for others: double, float, int32, int64, uint32, uint64, sint32, sint64, fixed32, fixed64, sfixed32, sfixed64, bool, enum.

Parameters
fieldId long: The field identifier constant from the generated class.

val long: The value.

write

Added in API level 30
public void write (long fieldId, 
                double val)

Write a value for the given fieldId.

Will automatically convert for the following field types, and throw an exception for others: double, float, int32, int64, uint32, uint64, sint32, sint64, fixed32, fixed64, sfixed32, sfixed64, bool, enum.

Parameters
fieldId long: The field identifier constant from the generated class.

val double: The value.

write

Added in API level 30
public void write (long fieldId, 
                byte[] val)

Write a byte[] value for the given fieldId.

If the field is not a bytes or object field, an exception will be thrown.

Parameters
fieldId long: The field identifier constant from the generated class.

val byte: The value. This value may be null.

writeTag

Added in API level 30
public void writeTag (int id, 
                int wireType)

Write an individual field tag by hand. See Protobuf Encoding for details on the structure of how tags and data are written.

Parameters
id int

wireType int: Value is android.util.proto.ProtoStream.WIRE_TYPE_VARINT, android.util.proto.ProtoStream.WIRE_TYPE_FIXED64, android.util.proto.ProtoStream.WIRE_TYPE_LENGTH_DELIMITED, android.util.proto.ProtoStream.WIRE_TYPE_START_GROUP, android.util.proto.ProtoStream.WIRE_TYPE_END_GROUP, or android.util.proto.ProtoStream.WIRE_TYPE_FIXED32