Added in API level 30

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 ProtoOutputStream.write(...) method.
static Long

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

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

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

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

Unknown field count, encoded into a field id used with a ProtoOutputStream.write(...) method.
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 with the default chunk size.
ProtoOutputStream(chunkSize: Int)

Construct a with the given chunk size.

Construct a ProtoOutputStream that sits on top of an OutputStream.
Public methods
static Int
checkFieldId(fieldId: Long, expectedFlags: Long)

Validates that the fieldId provided is of the type and count from expectedType.
Unit
dump(tag: String)

Dump debugging data about the buffers with the given log tag.
Unit
end(token: Long)

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

Write remaining data to the output stream.
ByteArray

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

Get the developer-usable name of a field count.
static String

Get a debug string for a fieldId.
static String?

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?

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
makeToken(tagSize: Int, repeated: Boolean, depth: Int, objectId: Int, offset: Int)

Make a token.
Long
start(fieldId: Long)

Start a sub object.
static String

Return a debugging string of a token.
Unit
write(fieldId: Long, val: Double)

Write a value for the given fieldId.
Unit
write(fieldId: Long, val: Float)

Write a value for the given fieldId.
Unit
write(fieldId: Long, val: Int)

Write a value for the given fieldId.
Unit
write(fieldId: Long, val: Long)

Write a value for the given fieldId.
Unit
write(fieldId: Long, val: Boolean)

Write a boolean value for the given fieldId.
Unit
write(fieldId: Long, val: String?)

Write a string value for the given fieldId.
Unit
write(fieldId: Long, val: ByteArray?)

Write a byte[] value for the given fieldId.
Unit
writeTag(id: Int, wireType: Int)

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 ProtoOutputStream.write(...) method.

Value: 16492674416640L

FIELD_COUNT_PACKED

static val FIELD_COUNT_PACKED: Long

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

Value: 5497558138880L

FIELD_COUNT_REPEATED

static val FIELD_COUNT_REPEATED: Long

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

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 ProtoOutputStream.write(...) method.

Value: 1099511627776L

FIELD_COUNT_UNKNOWN

static val FIELD_COUNT_UNKNOWN: Long

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

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_END_GROUP

    static val WIRE_TYPE_END_GROUP: Int

    End group wire type code.

    Value: 4

    See Also

      WIRE_TYPE_FIXED32

      static val WIRE_TYPE_FIXED32: Int

      Fixed32 wire type code.

      Value: 5

      See Also

        WIRE_TYPE_FIXED64

        static val WIRE_TYPE_FIXED64: Int

        Fixed64 wire type code.

        Value: 1

        See Also

          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

                WIRE_TYPE_VARINT

                static val WIRE_TYPE_VARINT: Int

                Varint wire type code.

                Value: 0

                See Also

                  Public constructors

                  ProtoOutputStream

                  Added in API level 30
                  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(chunkSize: Int)

                  Construct a with the given chunk size.

                  ProtoOutputStream

                  Added in API level 30
                  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

                  Added in API level 30
                  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

                  Added in API level 30
                  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

                  Added in API level 30
                  fun end(token: Long): Unit

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

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

                  flush

                  Added in API level 30
                  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

                  Added in API level 30
                  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

                  Added in API level 30
                  static fun getFieldCountString(fieldCount: Long): String?

                  Get the developer-usable name of a field count.

                  Return
                  String? This value may be null.

                  getFieldIdString

                  Added in API level 30
                  static fun getFieldIdString(fieldId: Long): String

                  Get a debug string for a fieldId.

                  Return
                  String This value cannot be null.

                  getFieldTypeString

                  Added in API level 30
                  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

                  Added in API level 30
                  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

                  Added in API level 30
                  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

                  Added in API level 30
                  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

                  Added in API level 30
                  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

                  Added in API level 30
                  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

                  Added in API level 30
                  static fun token2String(token: Long): String

                  Return a debugging string of a token.

                  Return
                  String This value cannot be null.

                  write

                  Added in API level 30
                  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

                  Added in API level 30
                  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

                  Added in API level 30
                  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

                  Added in API level 30
                  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

                  Added in API level 30
                  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

                  Added in API level 30
                  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

                  Added in API level 30
                  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

                  Added in API level 30
                  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