Dart Generated Code

This page describes what Dart code the protocol buffer compiler
generates for any given protocol definition. Any differences between proto2
and proto3 generated code are highlighted - note that these differences are in
the generated code as described in this document, not the base API, which are
the same in both versions. You should read the
proto2 language guide and/or the
proto3 language guide before
reading this document.

Compiler Invocation

The protocol buffer compiler requires a
plugin to generate Dart code.
Installing it following the
instructions
provides a protoc-gen-dart binary which protoc uses
when invoked with the --dart_out command-line flag. The
--dart_out flag tells the compiler where to write the Dart source
files. For a .proto file input, the compiler produces among others a
.pb.dart file.

The name of the .pb.dart file is computed by taking the name of the
.proto file and making two changes:

The extension (.proto) is replaced with .pb.dart.
For example, a file called foo.proto results in an
output file called foo.pb.go.

The proto path (specified with the --proto_path or
-I command-line flag) is replaced with the output path
(specified with the --dart_out flag).

the compiler will read the files src/foo.proto and
src/bar/baz.proto. It produces:
build/gen/foo.pb.dart and build/gen/bar/baz.pb.dart.
The compiler automatically creates the directory build/gen/bar
if necessary, but it will not create build or
build/gen; they must already exist.

Messages

Given a simple message declaration:

message Foo {}

The protocol buffer compiler generates a class called Foo, which extends the class
GeneratedMessage.

The class GeneratedMessage defines methods that let you check, manipulate, read,
or write the entire message. In addition to these methods, the Foo class defines the
following methods and constructors:

Foo(): Default constructor. Creates an instance where all singular fields are unset and repeated fields are empty.

Any

In our generated code, the getter for the details field returns an instance of
com.google.protobuf.Any. This provides the following special methods to pack and
unpack the Any's values:

/// Unpacks the message in [value] into [instance].
///
/// Throws a [InvalidProtocolBufferException] if [typeUrl] does not correspond
/// to the type of [instance].
///
/// A typical usage would be `any.unpackInto(new Message())`.
///
/// Returns [instance].
T unpackInto<T extends GeneratedMessage>(T instance,
{ExtensionRegistry extensionRegistry = ExtensionRegistry.EMPTY});
/// Returns `true` if the encoded message matches the type of [instance].
///
/// Can be used with a default instance:
/// `any.canUnpackInto(Message.getDefault())`
bool canUnpackInto(GeneratedMessage instance);
/// Creates a new [Any] encoding [message].
///
/// The [typeUrl] will be [typeUrlPrefix]/`fullName` where `fullName` is
/// the fully qualified name of the type of [message].
static Any pack(GeneratedMessage message,
{String typeUrlPrefix = 'type.googleapis.com'});

Foo_Test whichTest(): Returns the enum indicating which field is set. Returns Foo_Test.notSet if none of them is set.

void clearTest(): Clears the value of the oneof field which is currently set (if any), and sets the oneof case to Foo_Test.notSet.

For each field inside the oneof definition the regular field accessor methods are generated. For instance for name:

String get name: Returns the current value of the field if the oneof case is Foo_Test.name. Otherwise, returns the default value.

set name(String value): Sets the value of the field and sets the oneof case to Foo_Test.name.
After calling this, get name will return value and whichTest() will return Foo_Test.name.

void clearName(): Nothing will be changed if the oneof case is not Foo_Test.name.
Otherwise, clears the value of the field. After calling this, get name will return the
default value and whichTest() will return Foo_Test.notSet.

Enumerations

Given an enum definition like:

enum Color {
RED = 0;
GREEN = 1;
BLUE = 2;
}

The protocol buffer compiler will generate a class called Color, which extends the
ProtobufEnum class.
The class will include a static const Color for each of the three values defined as well as
a static const List<Color> containing all the three values. It will also include the following method:

static Color valueOf(int value): Returns the Color corresponding to the given numeric value.

Each value will have the following properties:

name: The enum's name, as specified in the .proto file.

value: The enum's integer value, as specified in the .proto file.

Note that the .proto language allows multiple enum symbols to have the same numeric value.
Symbols with the same numeric value are synonyms. For example:

enum Foo {
BAR = 0;
BAZ = 0;
}

In this case, BAZ is a synonym for BAR and will be defined like so:

static const Foo BAZ = BAR;

An enum can be defined nested within a message type. For instance, given an enum definition like:

Extensions (proto2 only)

The protocol buffer compiler will generate, in addition to the Foo class, a class
Foo_test which will contain a
static Extension
for each extension field in the file along with a method for registering all the exensions in an
ExtensionRegistry :

static final Extension bar

static void registerAllExtensions(ExtensionRegistry registry) : Registers all the defined extensions in the given registry.

In this case, the extension bar is instead declared as a static member of the Baz class .

When parsing a message that might have extensions, you must provide an ExtensionRegistry
in which you have registered any extensions that you want to be able to parse. Otherwise, those
extensions will just be treated like unknown fields. For example:

Services

Given a service definition:

service Foo {
rpc Bar(FooRequest) returns(FooResponse);
}

The protocol buffer compiler can be invoked with the `grpc` option (e.g.
--dart_out=grpc:output_folder), in which case it will generate code to support
gRPC. See the gRPC
Dart Quickstart guide for more details.