View Source Protobuf behaviour (protobuf v0.13.0)

protoc should always be used to generate code instead of writing the code by hand.

Usage

By use'ing this module, macros defined in Protobuf.DSL will be injected. Most of these macros are equal to definition in .proto schemas.

defmodule Foo do
  use Protobuf, syntax: :proto3

  field :a, 1, type: :int32
  field :b, 2, type: :string
end

Your Protobuf message (module) is just a normal Elixir struct. The default values in the struct match the correct ones for the Protobuf schema definition. You can construct new messages by hand:

foo = %Foo{a: 1}
Protobuf.encode(foo)
#=> <<...>>

Except functions in "Callbacks", some other functions may be defined:

Extension functions when your Protobuf message use extensions. See Protobuf.Extension for details.
- put_extension(struct, extension_mod, field, value)
- get_extension(struct, extension_mod, field, default \ nil)

Options

These are the options that you can pass to use Protobuf:

:syntax - The syntax of the schema. Can be :proto2 or :proto3. Defaults to :proto2.
:enum - A boolean that tells whether this message is an enum. Defaults to false.
:map - A boolean that tells whether this message is a map. Defaults to false.

Summary

Callbacks

decode(binary)

Decodes a Protobuf binary into a struct.

encode(struct)

Encodes the given struct into to a Protobuf binary.

new()

Builds a blank struct with default values.

new(attributes)

Builds and updates the struct with passed fields.

new!(attributes)

Similar to new/1, but use struct!/2 to build the struct, so errors will be raised if unknown keys are passed.

transform_module()

Returns nil or a transformer module that implements the Protobuf.TransformModule behaviour.

Functions

decode(data, module)

Decodes the given binary data interpreting it as the Protobuf message module.

encode(struct)

Encodes the given Protobuf struct into a binary.

encode_to_iodata(struct)

Encodes the given Protobuf struct into iodata.

get_unknown_fields(message)

Returns the unknown fields that were decoded but were not understood from the schema.

load_extensions()

Loads extensions modules.

Callbacks

decode(binary)

@callback decode(binary()) :: struct()

Decodes a Protobuf binary into a struct.

Errors may be raised if there's something wrong in the binary.

encode(struct)

@callback encode(struct()) :: binary()

Encodes the given struct into to a Protobuf binary.

Errors may be raised if there's something wrong in the struct.

If you want to encode to iodata instead of to a binary, use encode_to_iodata/1.

new()

@callback new() :: struct()

Builds a blank struct with default values.

Deprecated
This is deprecated in favor of building the struct with %MyMessage{...} or using struct/1.

new(attributes)

@callback new(attributes :: Enum.t()) :: struct()

Builds and updates the struct with passed fields.

This function will:

Recursively call new/1 for embedded fields
Create structs using struct/2 for keyword lists and maps
Create the correct struct if passed the wrong struct
Call new/1 for each element in the list for repeated fields

Deprecated
This is deprecated in favor of building the struct with %MyMessage{...} or using struct/2.

Examples

MyMessage.new(field1: "foo")
#=> %MyMessage{field1: "foo", ...}

MyMessage.new(field1: [field2: "foo"])
#=> %MyMessage{field1: %MySubMessage{field2: "foo"}}

MyMessage.new(field1: %WrongStruct{field2: "foo"})
#=> %MyMessage{field1: %MySubMessage{field2: "foo"}}

MyMessage.new(repeated: [%{field1: "foo"}, %{field1: "bar"}])
#=> %MyMessage{repeated: [%MyRepeated{field1: "foo"}, %MyRepeated{field1: "bar"}]}

new!(attributes)

@callback new!(attributes :: Enum.t()) :: struct()

Similar to new/1, but use struct!/2 to build the struct, so errors will be raised if unknown keys are passed.

Deprecated
This is deprecated in favor of building the struct with %MyMessage{...} or using struct!/2 directly.

transform_module()

@callback transform_module() :: module() | nil

Returns nil or a transformer module that implements the Protobuf.TransformModule behaviour.

This function is overridable in your module.

Functions

decode(data, module)

@spec decode(binary(), message) :: %{
  :__struct__ => message,
  optional(atom()) => any()
}
when message: module()

Decodes the given binary data interpreting it as the Protobuf message module.

This function raises an error if anything goes wrong with decoding.

Examples

Protobuf.decode(<<...>>, MyMessage)
#=> %MyMessage{...}

Protobuf.decode(<<"bad data">>, MyMessage)
#=> ** (Protobuf.DecodeError) ...

encode(struct)

@spec encode(struct()) :: binary()

Encodes the given Protobuf struct into a binary.

If you want to encode to iodata instead, see encode_to_iodata/1.

Examples

Protobuf.encode(%MyMessage{...})
#=> <<...>>

encode_to_iodata(struct)

@spec encode_to_iodata(struct()) :: iodata()

Encodes the given Protobuf struct into iodata.

Examples

Protobuf.encode_to_iodata(%MyMessage{...})
#=> [...]

get_unknown_fields(message)

(since 0.10.0)

@spec get_unknown_fields(struct()) :: [unknown_field]
when unknown_field:
       {field_number :: integer(), Protobuf.Wire.Types.wire_type(),
        value :: any()}

Returns the unknown fields that were decoded but were not understood from the schema.

In Protobuf, you can decode a payload (for the same message) encoded with a different version of the schema for that message. This can result in, for example, the payload containing fields that cannot be decoded correctly because they're not present in the schema used for decoding. These fields are skipped, but in some cases you might wish to preserve them in order to re-encode them, log them, or other. A common case is having to do "round-trips" with messages: you decode a payload, update the resulting message somehow, and re-encode it for future use. In these cases, you would probably want to re-encode the unknown fields to maintain symmetry.

The returned value of this function is a list of {field_number, field_value} tuples where field_number is the number of the unknown field in the schema used for its encoding and field_value is its value. The library does not make any assumptions on the value of the field since it can't know for sure. This means that, for example, it can't properly decode an integer as signed or unsigned. The only guarantee is that the unknown fields are re-encoded correctly.

The reason why these fields need to be accessed through this function is that the way they are stored in the struct is private.

Examples

Imagine you have this Protobuf schema:

message User {
  string email = 1;
}

You encode this:

payload = Protobuf.encode(User.new!(email: "user@example.com))
#=> <<...>>

Now, you try to decode this payload using this schema instead:

message User {
  string full_name = 2;
}

In this case, this function will return the decoded unknown field:

message = User.decode(<<...>>)
Protobuf.get_unknown_fields(message)
#=> [{_field_number = 1, _wire_type = 3, "user@example.com}]

load_extensions()

@spec load_extensions() :: :ok

Loads extensions modules.

This function should be called in your application's Application.start/2 callback, as seen in the example below, if you wish to use extensions.

Example

@impl Application
def start(_type, _args) do
  Protobuf.load_extensions()
  Supervisor.start_link([], strategy: :one_for_one)
end