ProtoOutputStream
class ProtoOutputStream
kotlin.Any | |
↳ | 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 | |
---|---|
static Long |
Bit mask for selecting the field count when reading a field id that is used with a |
static Long |
Repeated packed field count, encoded into a field id used with a |
static Long |
Repeated field count, encoded into a field id used with a |
static Int |
Bit offset for building a field id to be used with a |
static Long |
Single field count, encoded into a field id used with a |
static Long |
Unknown field count, encoded into a field id used with a |
static Int |
Number of bits to shift the field number to form a tag. |
static Long |
Field type code for bool fields. |
static Long |
Field type code for bytes fields. |
static Long |
Field type code for double fields. |
static Long |
Field type code for enum fields. |
static Long |
Field type code for fixed32 fields. |
static Long |
Field type code for fixed64 fields. |
static Long |
Field type code for float fields. |
static Long |
Field type code for int32 fields. |
static Long |
Field type code for int64 fields. |
static Long |
Mask for the field types stored in a fieldId. |
static Long |
Field type code for message fields. |
static Long |
Field type code for sfixed32 fields. |
static Long |
Field type code for sfixed64 fields. |
static Int |
Position of the field type in a (long) fieldId. |
static Long |
Field type code for sint32 fields. |
static Long |
Field type code for sint64 fields. |
static Long |
Field type code for string fields. |
static Long |
Field type code for uint32 fields. |
static Long |
Field type code for uint64 fields. |
static Int |
End group wire type code. |
static Int |
Fixed32 wire type code. |
static Int |
Fixed64 wire type code. |
static Int |
Length delimited wire type code. |
static Int |
Mask to select the wire type from a tag. |
static Int |
Start group wire type code. |
static Int |
Varint wire type code. |
Public constructors | |
---|---|
Construct a |
|
ProtoOutputStream(chunkSize: Int) Construct a |
|
ProtoOutputStream(stream: OutputStream) Construct a |
Public methods | |
---|---|
static Int |
checkFieldId(fieldId: Long, expectedFlags: Long) Validates that the fieldId provided is of the type and count from expectedType. |
Unit |
Dump debugging data about the buffers with the given log tag. |
Unit |
End the object started by start() that returned token. |
Unit |
flush() Write remaining data to the output stream. |
ByteArray |
getBytes() Finish the encoding of the data, and return a byte[] with the protobuf formatted data. |
static String? |
getFieldCountString(fieldCount: Long) Get the developer-usable name of a field count. |
static String |
getFieldIdString(fieldId: Long) Get a debug string for a fieldId. |
static String? |
getFieldTypeString(fieldType: Long) Get the developer-usable name of a field type. |
Int |
Returns the total size of the data that has been written, after full protobuf encoding has occurred. |
static String? |
getWireTypeString(wireType: Int) Get the developer-usable name of a wire type. |
static Long |
makeFieldId(id: Int, fieldFlags: Long) Combine a fieldId (the field keys in the proto file) and the field flags. |
static Long |
Make a token. |
Long |
Start a sub object. |
static String |
token2String(token: Long) Return a debugging string of a token. |
Unit |
Write a value for the given fieldId. |
Unit |
Write a value for the given fieldId. |
Unit |
Write a value for the given fieldId. |
Unit |
Write a value for the given fieldId. |
Unit |
Write a boolean value for the given fieldId. |
Unit |
Write a string value for the given fieldId. |
Unit |
Write a byte[] value for the given fieldId. |
Unit |
Write an individual field tag by hand. |
Constants
FIELD_COUNT_MASK
static val FIELD_COUNT_MASK: Long
Bit mask for selecting the field count when reading a field id that is used with a
method.ProtoOutputStream
.write(...)
Value: 16492674416640L
FIELD_COUNT_PACKED
static val FIELD_COUNT_PACKED: Long
Repeated packed field count, encoded into a field id used with a
method.ProtoOutputStream
.write(...)
Value: 5497558138880L
FIELD_COUNT_REPEATED
static val FIELD_COUNT_REPEATED: Long
Repeated field count, encoded into a field id used with a
method.ProtoOutputStream
.write(...)
Value: 2199023255552L
FIELD_COUNT_SHIFT
static val FIELD_COUNT_SHIFT: Int
Bit offset for building a field id to be used with a
.ProtoOutputStream
.write(...)
Value: 40
FIELD_COUNT_SINGLE
static val FIELD_COUNT_SINGLE: Long
Single field count, encoded into a field id used with a
method.ProtoOutputStream
.write(...)
Value: 1099511627776L
FIELD_COUNT_UNKNOWN
static val FIELD_COUNT_UNKNOWN: Long
Unknown field count, encoded into a field id used with a
method.ProtoOutputStream
.write(...)
Value: 0L
FIELD_ID_SHIFT
static val FIELD_ID_SHIFT: Int
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;
Value: 3
See Also
FIELD_TYPE_BOOL
static val FIELD_TYPE_BOOL: Long
Field type code for bool fields. Used to build constants in generated code for use with the ProtoOutputStream.write(long, boolean)
method.
Value: 34359738368L
FIELD_TYPE_BYTES
static val FIELD_TYPE_BYTES: Long
Field type code for bytes fields. Used to build constants in generated code for use with the ProtoOutputStream.write(long, byte[])
method.
Value: 51539607552L
FIELD_TYPE_DOUBLE
static val FIELD_TYPE_DOUBLE: Long
Field type code for double fields. Used to build constants in generated code for use with the ProtoOutputStream.write(long, double)
method.
Value: 4294967296L
FIELD_TYPE_ENUM
static val FIELD_TYPE_ENUM: Long
Field type code for enum fields. Used to build constants in generated code for use with the ProtoOutputStream.write(long, int)
method.
Value: 60129542144L
FIELD_TYPE_FIXED32
static val FIELD_TYPE_FIXED32: Long
Field type code for fixed32 fields. Used to build constants in generated code for use with the ProtoOutputStream.write(long, int)
method.
Value: 30064771072L
FIELD_TYPE_FIXED64
static val FIELD_TYPE_FIXED64: Long
Field type code for fixed64 fields. Used to build constants in generated code for use with the ProtoOutputStream.write(long, long)
method.
Value: 25769803776L
FIELD_TYPE_FLOAT
static val FIELD_TYPE_FLOAT: Long
Field type code for float fields. Used to build constants in generated code for use with the ProtoOutputStream.write(long, float)
method.
Value: 8589934592L
FIELD_TYPE_INT32
static val FIELD_TYPE_INT32: Long
Field type code for int32 fields. Used to build constants in generated code for use with the ProtoOutputStream.write(long, int)
method.
Value: 21474836480L
FIELD_TYPE_INT64
static val FIELD_TYPE_INT64: Long
Field type code for int64 fields. Used to build constants in generated code for use with the ProtoOutputStream.write(long, long)
method.
Value: 12884901888L
FIELD_TYPE_MASK
static val FIELD_TYPE_MASK: Long
Mask for the field types stored in a fieldId. Leaves a whole byte for future expansion, even though there are currently only 17 types.
Value: 1095216660480L
FIELD_TYPE_MESSAGE
static val FIELD_TYPE_MESSAGE: Long
Field type code for message fields. Used to build constants in generated code for use with the ProtoOutputStream.start(long)
method.
Value: 47244640256L
FIELD_TYPE_SFIXED32
static val FIELD_TYPE_SFIXED32: Long
Field type code for sfixed32 fields. Used to build constants in generated code for use with the ProtoOutputStream.write(long, int)
method.
Value: 64424509440L
FIELD_TYPE_SFIXED64
static val FIELD_TYPE_SFIXED64: Long
Field type code for sfixed64 fields. Used to build constants in generated code for use with the ProtoOutputStream.write(long, long)
method.
Value: 68719476736L
FIELD_TYPE_SHIFT
static val FIELD_TYPE_SHIFT: Int
Position of the field type in a (long) fieldId.
Value: 32
FIELD_TYPE_SINT32
static val FIELD_TYPE_SINT32: Long
Field type code for sint32 fields. Used to build constants in generated code for use with the ProtoOutputStream.write(long, int)
method.
Value: 73014444032L
FIELD_TYPE_SINT64
static val FIELD_TYPE_SINT64: Long
Field type code for sint64 fields. Used to build constants in generated code for use with the ProtoOutputStream.write(long, long)
method.
Value: 77309411328L
FIELD_TYPE_STRING
static val FIELD_TYPE_STRING: Long
Field type code for string fields. Used to build constants in generated code for use with the ProtoOutputStream.write(long, String)
method.
Value: 38654705664L
FIELD_TYPE_UINT32
static val FIELD_TYPE_UINT32: Long
Field type code for uint32 fields. Used to build constants in generated code for use with the ProtoOutputStream.write(long, int)
method.
Value: 55834574848L
FIELD_TYPE_UINT64
static val FIELD_TYPE_UINT64: Long
Field type code for uint64 fields. Used to build constants in generated code for use with the ProtoOutputStream.write(long, long)
method.
Value: 17179869184L
WIRE_TYPE_LENGTH_DELIMITED
static val WIRE_TYPE_LENGTH_DELIMITED: Int
Length delimited wire type code.
Value: 2
See Also
WIRE_TYPE_MASK
static val WIRE_TYPE_MASK: Int
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;
Value: 7
See Also
WIRE_TYPE_START_GROUP
static val WIRE_TYPE_START_GROUP: Int
Start group wire type code.
Value: 3
See Also
Public constructors
ProtoOutputStream
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
ProtoOutputStream(stream: OutputStream)
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
static fun checkFieldId(
fieldId: Long,
expectedFlags: Long
): Int
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
Return | |
---|---|
Int |
The raw ID of that field. |
Exceptions | |
---|---|
|
IllegalArgumentException if it is not. |
dump
fun dump(tag: String): Unit
Dump debugging data about the buffers with the given log tag.
Parameters | |
---|---|
tag |
String: This value cannot be null . |
end
fun end(token: Long): Unit
End the object started by start() that returned token.
Parameters | |
---|---|
token |
Long: The token returned from start(long) |
flush
fun flush(): Unit
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
fun getBytes(): ByteArray
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.
Return | |
---|---|
ByteArray |
This value cannot be null . |
getFieldCountString
static fun getFieldCountString(fieldCount: Long): String?
Get the developer-usable name of a field count.
Return | |
---|---|
String? |
This value may be null . |
getFieldIdString
static fun getFieldIdString(fieldId: Long): String
Get a debug string for a fieldId.
Return | |
---|---|
String |
This value cannot be null . |
getFieldTypeString
static fun getFieldTypeString(fieldType: Long): String?
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 |
Return | |
---|---|
String? |
This value may be null . |
getRawSize
fun getRawSize(): Int
Returns the total size of the data that has been written, after full protobuf encoding has occurred.
Return | |
---|---|
Int |
the uncompressed buffer size |
getWireTypeString
static fun getWireTypeString(wireType: Int): String?
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 |
Return | |
---|---|
String? |
This value may be null . |
makeFieldId
static fun makeFieldId(
id: Int,
fieldFlags: Long
): Long
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.
makeToken
static fun makeToken(
tagSize: Int,
repeated: Boolean,
depth: Int,
objectId: Int,
offset: Int
): Long
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.
start
fun start(fieldId: Long): Long
Start a sub object.
Parameters | |
---|---|
fieldId |
Long: The field identifier constant from the generated class. |
Return | |
---|---|
Long |
The token to call end(long) with. |
token2String
static fun token2String(token: Long): String
Return a debugging string of a token.
Return | |
---|---|
String |
This value cannot be null . |
write
fun write(
fieldId: Long,
val: Double
): Unit
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
fun write(
fieldId: Long,
val: Float
): Unit
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
fun write(
fieldId: Long,
val: Int
): Unit
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
fun write(
fieldId: Long,
val: Long
): Unit
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
fun write(
fieldId: Long,
val: Boolean
): Unit
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
fun write(
fieldId: Long,
val: String?
): Unit
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
fun write(
fieldId: Long,
val: ByteArray?
): Unit
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 |
ByteArray?: The value. This value may be null . |
writeTag
fun writeTag(
id: Int,
wireType: Int
): Unit
Write an individual field tag by hand. See Protobuf Encoding for details on the structure of how tags and data are written.
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 |