Documentation

Overview

    Package proto converts data structures to and from the wire format of protocol buffers. It works in concert with the Go source code generated for .proto files by the protocol compiler.

    A summary of the properties of the protocol buffer interface for a protocol buffer variable v:

      - Names are turned from camel_case to CamelCase for export.
      - There are no methods on v to set fields; just treat
    	them as structure fields.
      - There are getters that return a field's value if set,
    	and return the field's default value if unset.
    	The getters work even if the receiver is a nil message.
      - The zero value for a struct is its correct initialization state.
    	All desired fields must be set before marshaling.
      - A Reset() method will restore a protobuf struct to its zero state.
      - Non-repeated fields are pointers to the values; nil means unset.
    	That is, optional or required field int32 f becomes F *int32.
      - Repeated fields are slices.
      - Helper functions are available to aid the setting of fields.
    	msg.Foo = proto.String("hello") // set field
      - Constants are defined to hold the default values of all fields that
    	have them.  They have the form Default_StructName_FieldName.
    	Because the getter methods handle defaulted values,
    	direct use of these constants should be rare.
      - Enums are given type names and maps from names to values.
    	Enum values are prefixed by the enclosing message's name, or by the
    	enum's type name if it is a top-level enum. Enum types have a String
    	method, and a Enum method to assist in message construction.
      - Nested messages, groups and enums have type names prefixed with the name of
    	the surrounding message type.
      - Extensions are given descriptor names that start with E_,
    	followed by an underscore-delimited list of the nested messages
    	that contain it (if any) followed by the CamelCased name of the
    	extension field itself.  HasExtension, ClearExtension, GetExtension
    	and SetExtension are functions for manipulating extensions.
      - Oneof field sets are given a single field in their message,
    	with distinguished wrapper types for each possible field value.
      - Marshal and Unmarshal are functions to encode and decode the wire format.
    

    When the .proto file specifies `syntax="proto3"`, there are some differences:

    - Non-repeated fields of non-message type are values instead of pointers.
    - Enum types do not get an Enum method.
    

    The simplest way to describe this is to see an example. Given file test.proto, containing

    package example;
    
    enum FOO { X = 17; }
    
    message Test {
      required string label = 1;
      optional int32 type = 2 [default=77];
      repeated int64 reps = 3;
      optional group OptionalGroup = 4 {
        required string RequiredField = 5;
      }
      oneof union {
        int32 number = 6;
        string name = 7;
      }
    }
    

    The resulting file, test.pb.go, is:

    package example
    
    import proto "github.com/gogo/protobuf/proto"
    import math "math"
    
    type FOO int32
    const (
    	FOO_X FOO = 17
    )
    var FOO_name = map[int32]string{
    	17: "X",
    }
    var FOO_value = map[string]int32{
    	"X": 17,
    }
    
    func (x FOO) Enum() *FOO {
    	p := new(FOO)
    	*p = x
    	return p
    }
    func (x FOO) String() string {
    	return proto.EnumName(FOO_name, int32(x))
    }
    func (x *FOO) UnmarshalJSON(data []byte) error {
    	value, err := proto.UnmarshalJSONEnum(FOO_value, data)
    	if err != nil {
    		return err
    	}
    	*x = FOO(value)
    	return nil
    }
    
    type Test struct {
    	Label         *string             `protobuf:"bytes,1,req,name=label" json:"label,omitempty"`
    	Type          *int32              `protobuf:"varint,2,opt,name=type,def=77" json:"type,omitempty"`
    	Reps          []int64             `protobuf:"varint,3,rep,name=reps" json:"reps,omitempty"`
    	Optionalgroup *Test_OptionalGroup `protobuf:"group,4,opt,name=OptionalGroup" json:"optionalgroup,omitempty"`
    	// Types that are valid to be assigned to Union:
    	//	*Test_Number
    	//	*Test_Name
    	Union            isTest_Union `protobuf_oneof:"union"`
    	XXX_unrecognized []byte       `json:"-"`
    }
    func (m *Test) Reset()         { *m = Test{} }
    func (m *Test) String() string { return proto.CompactTextString(m) }
    func (*Test) ProtoMessage() {}
    
    type isTest_Union interface {
    	isTest_Union()
    }
    
    type Test_Number struct {
    	Number int32 `protobuf:"varint,6,opt,name=number"`
    }
    type Test_Name struct {
    	Name string `protobuf:"bytes,7,opt,name=name"`
    }
    
    func (*Test_Number) isTest_Union() {}
    func (*Test_Name) isTest_Union()   {}
    
    func (m *Test) GetUnion() isTest_Union {
    	if m != nil {
    		return m.Union
    	}
    	return nil
    }
    const Default_Test_Type int32 = 77
    
    func (m *Test) GetLabel() string {
    	if m != nil && m.Label != nil {
    		return *m.Label
    	}
    	return ""
    }
    
    func (m *Test) GetType() int32 {
    	if m != nil && m.Type != nil {
    		return *m.Type
    	}
    	return Default_Test_Type
    }
    
    func (m *Test) GetOptionalgroup() *Test_OptionalGroup {
    	if m != nil {
    		return m.Optionalgroup
    	}
    	return nil
    }
    
    type Test_OptionalGroup struct {
    	RequiredField *string `protobuf:"bytes,5,req" json:"RequiredField,omitempty"`
    }
    func (m *Test_OptionalGroup) Reset()         { *m = Test_OptionalGroup{} }
    func (m *Test_OptionalGroup) String() string { return proto.CompactTextString(m) }
    
    func (m *Test_OptionalGroup) GetRequiredField() string {
    	if m != nil && m.RequiredField != nil {
    		return *m.RequiredField
    	}
    	return ""
    }
    
    func (m *Test) GetNumber() int32 {
    	if x, ok := m.GetUnion().(*Test_Number); ok {
    		return x.Number
    	}
    	return 0
    }
    
    func (m *Test) GetName() string {
    	if x, ok := m.GetUnion().(*Test_Name); ok {
    		return x.Name
    	}
    	return ""
    }
    
    func init() {
    	proto.RegisterEnum("example.FOO", FOO_name, FOO_value)
    }
    

    To create and play with a Test object:

    package main
    
    import (
    	"log"
    
    	"github.com/gogo/protobuf/proto"
    	pb "./example.pb"
    )
    
    func main() {
    	test := &pb.Test{
    		Label: proto.String("hello"),
    		Type:  proto.Int32(17),
    		Reps:  []int64{1, 2, 3},
    		Optionalgroup: &pb.Test_OptionalGroup{
    			RequiredField: proto.String("good bye"),
    		},
    		Union: &pb.Test_Name{"fred"},
    	}
    	data, err := proto.Marshal(test)
    	if err != nil {
    		log.Fatal("marshaling error: ", err)
    	}
    	newTest := &pb.Test{}
    	err = proto.Unmarshal(data, newTest)
    	if err != nil {
    		log.Fatal("unmarshaling error: ", err)
    	}
    	// Now test and newTest contain the same data.
    	if test.GetLabel() != newTest.GetLabel() {
    		log.Fatalf("data mismatch %q != %q", test.GetLabel(), newTest.GetLabel())
    	}
    	// Use a type switch to determine which oneof was set.
    	switch u := test.Union.(type) {
    	case *pb.Test_Number: // u.Number contains the number.
    	case *pb.Test_Name: // u.Name contains the string.
    	}
    	// etc.
    }
    

    Index

    Constants

    View Source
    const (
    	// ProtoPackageIsVersion3 is referenced from generated protocol buffer files
    	// to assert that that code is compatible with this version of the proto package.
    	GoGoProtoPackageIsVersion3 = true
    
    	// ProtoPackageIsVersion2 is referenced from generated protocol buffer files
    	// to assert that that code is compatible with this version of the proto package.
    	GoGoProtoPackageIsVersion2 = true
    
    	// ProtoPackageIsVersion1 is referenced from generated protocol buffer files
    	// to assert that that code is compatible with this version of the proto package.
    	GoGoProtoPackageIsVersion1 = true
    )
    View Source
    const (
    	WireVarint     = 0
    	WireFixed64    = 1
    	WireBytes      = 2
    	WireStartGroup = 3
    	WireEndGroup   = 4
    	WireFixed32    = 5
    )

      Constants that identify the encoding of a value on the wire.

      Variables

      View Source
      var (
      
      	// ErrNil is the error returned if Marshal is called with nil.
      	ErrNil = errors.New("proto: Marshal called with nil")
      
      	// ErrTooLarge is the error returned if Marshal is called with a
      	// message that encodes to >2GB.
      	ErrTooLarge = errors.New("proto: message encodes to over 2 GB")
      )
      View Source
      var ErrInternalBadWireType = errors.New("proto: internal error: bad wiretype for oneof")

        ErrInternalBadWireType is returned by generated code when an incorrect wire type is encountered. It does not get returned to user code.

        View Source
        var ErrMissingExtension = errors.New("proto: missing extension")

          ErrMissingExtension is the error returned by GetExtension if the named extension is not in the message.

          Functions

          func AppendExtension

          func AppendExtension(e Message, tag int32, buf []byte)

          func Bool

          func Bool(v bool) *bool

            Bool is a helper routine that allocates a new bool value to store v and returns a pointer to it.

            func BytesToExtensionsMap

            func BytesToExtensionsMap(buf []byte) (map[int32]Extension, error)

            func ClearAllExtensions

            func ClearAllExtensions(pb Message)

              ClearAllExtensions clears all extensions from pb.

              func ClearExtension

              func ClearExtension(pb Message, extension *ExtensionDesc)

                ClearExtension removes the given extension from pb.

                func CompactText

                func CompactText(w io.Writer, pb Message) error

                  CompactText writes a given protocol buffer in compact text format (one line).

                  func CompactTextString

                  func CompactTextString(pb Message) string

                    CompactTextString is the same as CompactText, but returns the string directly.

                    func DecodeVarint

                    func DecodeVarint(buf []byte) (x uint64, n int)

                      DecodeVarint reads a varint-encoded integer from the slice. It returns the integer and the number of bytes consumed, or zero if there is not enough. This is the format for the int32, int64, uint32, uint64, bool, and enum protocol buffer types.

                      func DiscardUnknown

                      func DiscardUnknown(m Message)

                        DiscardUnknown recursively discards all unknown fields from this message and all embedded messages.

                        When unmarshaling a message with unrecognized fields, the tags and values of such fields are preserved in the Message. This allows a later call to marshal to be able to produce a message that continues to have those unrecognized fields. To avoid this, DiscardUnknown is used to explicitly clear the unknown fields after unmarshaling.

                        For proto2 messages, the unknown fields of message extensions are only discarded from messages that have been accessed via GetExtension.

                        func EncodeExtensionMap

                        func EncodeExtensionMap(m map[int32]Extension, data []byte) (n int, err error)

                        func EncodeExtensionMapBackwards

                        func EncodeExtensionMapBackwards(m map[int32]Extension, data []byte) (n int, err error)

                        func EncodeInternalExtension

                        func EncodeInternalExtension(m extendableProto, data []byte) (n int, err error)

                        func EncodeInternalExtensionBackwards

                        func EncodeInternalExtensionBackwards(m extendableProto, data []byte) (n int, err error)

                        func EncodeVarint

                        func EncodeVarint(x uint64) []byte

                          EncodeVarint returns the varint encoding of x. This is the format for the int32, int64, uint32, uint64, bool, and enum protocol buffer types. Not used by the package itself, but helpful to clients wishing to use the same encoding.

                          func EnumName

                          func EnumName(m map[int32]string, v int32) string

                            EnumName is a helper function to simplify printing protocol buffer enums by name. Given an enum map and a value, it returns a useful string.

                            func EnumValueMap

                            func EnumValueMap(enumType string) map[string]int32

                              EnumValueMap returns the mapping from names to integers of the enum type enumType, or a nil if not found.

                              func Equal

                              func Equal(a, b Message) bool

                                Equal returns true iff protocol buffers a and b are equal. The arguments must both be pointers to protocol buffer structs.

                                Equality is defined in this way:

                                - Two messages are equal iff they are the same type,
                                  corresponding fields are equal, unknown field sets
                                  are equal, and extensions sets are equal.
                                - Two set scalar fields are equal iff their values are equal.
                                  If the fields are of a floating-point type, remember that
                                  NaN != x for all x, including NaN. If the message is defined
                                  in a proto3 .proto file, fields are not "set"; specifically,
                                  zero length proto3 "bytes" fields are equal (nil == {}).
                                - Two repeated fields are equal iff their lengths are the same,
                                  and their corresponding elements are equal. Note a "bytes" field,
                                  although represented by []byte, is not a repeated field and the
                                  rule for the scalar fields described above applies.
                                - Two unset fields are equal.
                                - Two unknown field sets are equal if their current
                                  encoded state is equal.
                                - Two extension sets are equal iff they have corresponding
                                  elements that are pairwise equal.
                                - Two map fields are equal iff their lengths are the same,
                                  and they contain the same set of elements. Zero-length map
                                  fields are equal.
                                - Every other combination of things are not equal.
                                

                                The return value is undefined if a and b are not protocol buffers.

                                func FileDescriptor

                                func FileDescriptor(filename string) []byte

                                  FileDescriptor returns the compressed FileDescriptorProto for a .proto file.

                                  func Float32

                                  func Float32(v float32) *float32

                                    Float32 is a helper routine that allocates a new float32 value to store v and returns a pointer to it.

                                    func Float64

                                    func Float64(v float64) *float64

                                      Float64 is a helper routine that allocates a new float64 value to store v and returns a pointer to it.

                                      func GetBoolExtension

                                      func GetBoolExtension(pb Message, extension *ExtensionDesc, ifnotset bool) bool

                                      func GetExtension

                                      func GetExtension(pb Message, extension *ExtensionDesc) (interface{}, error)

                                        GetExtension retrieves a proto2 extended field from pb.

                                        If the descriptor is type complete (i.e., ExtensionDesc.ExtensionType is non-nil), then GetExtension parses the encoded field and returns a Go value of the specified type. If the field is not present, then the default value is returned (if one is specified), otherwise ErrMissingExtension is reported.

                                        If the descriptor is not type complete (i.e., ExtensionDesc.ExtensionType is nil), then GetExtension returns the raw encoded bytes of the field extension.

                                        func GetExtensions

                                        func GetExtensions(pb Message, es []*ExtensionDesc) (extensions []interface{}, err error)

                                          GetExtensions returns a slice of the extensions present in pb that are also listed in es. The returned slice has the same length as es; missing extensions will appear as nil elements.

                                          func GetRawExtension

                                          func GetRawExtension(m map[int32]Extension, id int32) ([]byte, error)

                                          func GetUnsafeExtension

                                          func GetUnsafeExtension(pb Message, fieldNum int32) (interface{}, error)

                                          func GetUnsafeExtensionsMap

                                          func GetUnsafeExtensionsMap(extendable Message) map[int32]Extension

                                          func HasExtension

                                          func HasExtension(pb Message, extension *ExtensionDesc) bool

                                            HasExtension returns whether the given extension is present in pb.

                                            func Int

                                            func Int(v int) *int32

                                              Int is a helper routine that allocates a new int32 value to store v and returns a pointer to it, but unlike Int32 its argument value is an int.

                                              func Int32

                                              func Int32(v int32) *int32

                                                Int32 is a helper routine that allocates a new int32 value to store v and returns a pointer to it.

                                                func Int64

                                                func Int64(v int64) *int64

                                                  Int64 is a helper routine that allocates a new int64 value to store v and returns a pointer to it.

                                                  func Marshal

                                                  func Marshal(pb Message) ([]byte, error)

                                                    Marshal takes a protocol buffer message and encodes it into the wire format, returning the data. This is the main entry point.

                                                    func MarshalJSONEnum

                                                    func MarshalJSONEnum(m map[int32]string, value int32) ([]byte, error)

                                                    func MarshalMessageSet

                                                    func MarshalMessageSet(interface{}) ([]byte, error)

                                                      Deprecated: do not use.

                                                      func MarshalMessageSetJSON

                                                      func MarshalMessageSetJSON(interface{}) ([]byte, error)

                                                        Deprecated: do not use.

                                                        func MarshalText

                                                        func MarshalText(w io.Writer, pb Message) error

                                                          MarshalText writes a given protocol buffer in text format. The only errors returned are from w.

                                                          func MarshalTextString

                                                          func MarshalTextString(pb Message) string

                                                            MarshalTextString is the same as MarshalText, but returns the string directly.

                                                            func Merge

                                                            func Merge(dst, src Message)

                                                              Merge merges src into dst. Required and optional fields that are set in src will be set to that value in dst. Elements of repeated fields will be appended. Merge panics if src and dst are not the same type, or if dst is nil.

                                                              func MessageName

                                                              func MessageName(x Message) string

                                                                MessageName returns the fully-qualified proto name for the given message type.

                                                                func MessageType

                                                                func MessageType(name string) reflect.Type

                                                                  MessageType returns the message type (pointer to struct) for a named message. The type is not guaranteed to implement proto.Message if the name refers to a map entry.

                                                                  func RegisterEnum

                                                                  func RegisterEnum(typeName string, unusedNameMap map[int32]string, valueMap map[string]int32)

                                                                    RegisterEnum is called from the generated code to install the enum descriptor maps into the global table to aid parsing text format protocol buffers.

                                                                    func RegisterExtension

                                                                    func RegisterExtension(desc *ExtensionDesc)

                                                                      RegisterExtension is called from the generated code.

                                                                      func RegisterFile

                                                                      func RegisterFile(filename string, fileDescriptor []byte)

                                                                        RegisterFile is called from generated code and maps from the full file name of a .proto file to its compressed FileDescriptorProto.

                                                                        func RegisterMapType

                                                                        func RegisterMapType(x interface{}, name string)

                                                                          RegisterMapType is called from generated code and maps from the fully qualified proto name to the native map type of the proto map definition.

                                                                          func RegisterMessageSetType

                                                                          func RegisterMessageSetType(Message, int32, string)

                                                                            Deprecated: do not use.

                                                                            func RegisterType

                                                                            func RegisterType(x Message, name string)

                                                                              RegisterType is called from generated code and maps from the fully qualified proto name to the type (pointer to struct) of the protocol buffer.

                                                                              func RegisteredExtensions

                                                                              func RegisteredExtensions(pb Message) map[int32]*ExtensionDesc

                                                                                RegisteredExtensions returns a map of the registered extensions of a protocol buffer struct, indexed by the extension number. The argument pb should be a nil pointer to the struct type.

                                                                                func SetDefaults

                                                                                func SetDefaults(pb Message)

                                                                                  SetDefaults sets unset protocol buffer fields to their default values. It only modifies fields that are both unset and have defined defaults. It recursively sets default values in any non-nil sub-messages.

                                                                                  func SetExtension

                                                                                  func SetExtension(pb Message, extension *ExtensionDesc, value interface{}) error

                                                                                    SetExtension sets the specified extension of pb to the specified value.

                                                                                    func SetRawExtension

                                                                                    func SetRawExtension(base Message, id int32, b []byte)

                                                                                      SetRawExtension is for testing only.

                                                                                      func SetUnsafeExtension

                                                                                      func SetUnsafeExtension(pb Message, fieldNum int32, value interface{}) error

                                                                                      func Size

                                                                                      func Size(pb Message) int

                                                                                        Size returns the encoded size of a protocol buffer message. This is the main entry point.

                                                                                        func SizeOfInternalExtension

                                                                                        func SizeOfInternalExtension(m extendableProto) (n int)

                                                                                        func SizeVarint

                                                                                        func SizeVarint(x uint64) int

                                                                                          SizeVarint returns the varint encoding size of an integer.

                                                                                          func Skip

                                                                                          func Skip(data []byte) (n int, err error)

                                                                                          func String

                                                                                          func String(v string) *string

                                                                                            String is a helper routine that allocates a new string value to store v and returns a pointer to it.

                                                                                            func StringFromExtensionsBytes

                                                                                            func StringFromExtensionsBytes(ext []byte) string

                                                                                            func StringFromExtensionsMap

                                                                                            func StringFromExtensionsMap(m map[int32]Extension) string

                                                                                            func StringFromInternalExtension

                                                                                            func StringFromInternalExtension(m extendableProto) string

                                                                                            func Uint32

                                                                                            func Uint32(v uint32) *uint32

                                                                                              Uint32 is a helper routine that allocates a new uint32 value to store v and returns a pointer to it.

                                                                                              func Uint64

                                                                                              func Uint64(v uint64) *uint64

                                                                                                Uint64 is a helper routine that allocates a new uint64 value to store v and returns a pointer to it.

                                                                                                func Unmarshal

                                                                                                func Unmarshal(buf []byte, pb Message) error

                                                                                                  Unmarshal parses the protocol buffer representation in buf and places the decoded result in pb. If the struct underlying pb does not match the data in buf, the results can be unpredictable.

                                                                                                  Unmarshal resets pb before starting to unmarshal, so any existing data in pb is always removed. Use UnmarshalMerge to preserve and append to existing data.

                                                                                                  func UnmarshalJSONEnum

                                                                                                  func UnmarshalJSONEnum(m map[string]int32, data []byte, enumName string) (int32, error)

                                                                                                    UnmarshalJSONEnum is a helper function to simplify recovering enum int values from their JSON-encoded representation. Given a map from the enum's symbolic names to its int values, and a byte buffer containing the JSON-encoded value, it returns an int32 that can be cast to the enum type by the caller.

                                                                                                    The function can deal with both JSON representations, numeric and symbolic.

                                                                                                    func UnmarshalMerge

                                                                                                    func UnmarshalMerge(buf []byte, pb Message) error

                                                                                                      UnmarshalMerge parses the protocol buffer representation in buf and writes the decoded result to pb. If the struct underlying pb does not match the data in buf, the results can be unpredictable.

                                                                                                      UnmarshalMerge merges into existing data in pb. Most code should use Unmarshal instead.

                                                                                                      func UnmarshalMessageSet

                                                                                                      func UnmarshalMessageSet([]byte, interface{}) error

                                                                                                        Deprecated: do not use.

                                                                                                        func UnmarshalMessageSetJSON

                                                                                                        func UnmarshalMessageSetJSON([]byte, interface{}) error

                                                                                                          Deprecated: do not use.

                                                                                                          func UnmarshalText

                                                                                                          func UnmarshalText(s string, pb Message) error

                                                                                                            UnmarshalText reads a protocol buffer in Text format. UnmarshalText resets pb before starting to unmarshal, so any existing data in pb is always removed. If a required field is not set and no other error occurs, UnmarshalText returns *RequiredNotSetError.

                                                                                                            Types

                                                                                                            type Buffer

                                                                                                            type Buffer struct {
                                                                                                            	// contains filtered or unexported fields
                                                                                                            }

                                                                                                              A Buffer is a buffer manager for marshaling and unmarshaling protocol buffers. It may be reused between invocations to reduce memory usage. It is not necessary to use a Buffer; the global functions Marshal and Unmarshal create a temporary Buffer and are fine for most applications.

                                                                                                              func NewBuffer

                                                                                                              func NewBuffer(e []byte) *Buffer

                                                                                                                NewBuffer allocates a new Buffer and initializes its internal data to the contents of the argument slice.

                                                                                                                func (*Buffer) Bytes

                                                                                                                func (p *Buffer) Bytes() []byte

                                                                                                                  Bytes returns the contents of the Buffer.

                                                                                                                  func (*Buffer) DebugPrint

                                                                                                                  func (p *Buffer) DebugPrint(s string, b []byte)

                                                                                                                    DebugPrint dumps the encoded data in b in a debugging format with a header including the string s. Used in testing but made available for general debugging.

                                                                                                                    func (*Buffer) DecodeFixed32

                                                                                                                    func (p *Buffer) DecodeFixed32() (x uint64, err error)

                                                                                                                      DecodeFixed32 reads a 32-bit integer from the Buffer. This is the format for the fixed32, sfixed32, and float protocol buffer types.

                                                                                                                      func (*Buffer) DecodeFixed64

                                                                                                                      func (p *Buffer) DecodeFixed64() (x uint64, err error)

                                                                                                                        DecodeFixed64 reads a 64-bit integer from the Buffer. This is the format for the fixed64, sfixed64, and double protocol buffer types.

                                                                                                                        func (*Buffer) DecodeGroup

                                                                                                                        func (p *Buffer) DecodeGroup(pb Message) error

                                                                                                                          DecodeGroup reads a tag-delimited group from the Buffer. StartGroup tag is already consumed. This function consumes EndGroup tag.

                                                                                                                          func (*Buffer) DecodeMessage

                                                                                                                          func (p *Buffer) DecodeMessage(pb Message) error

                                                                                                                            DecodeMessage reads a count-delimited message from the Buffer.

                                                                                                                            func (*Buffer) DecodeRawBytes

                                                                                                                            func (p *Buffer) DecodeRawBytes(alloc bool) (buf []byte, err error)

                                                                                                                              DecodeRawBytes reads a count-delimited byte buffer from the Buffer. This is the format used for the bytes protocol buffer type and for embedded messages.

                                                                                                                              func (*Buffer) DecodeStringBytes

                                                                                                                              func (p *Buffer) DecodeStringBytes() (s string, err error)

                                                                                                                                DecodeStringBytes reads an encoded string from the Buffer. This is the format used for the proto2 string type.

                                                                                                                                func (*Buffer) DecodeVarint

                                                                                                                                func (p *Buffer) DecodeVarint() (x uint64, err error)

                                                                                                                                  DecodeVarint reads a varint-encoded integer from the Buffer. This is the format for the int32, int64, uint32, uint64, bool, and enum protocol buffer types.

                                                                                                                                  func (*Buffer) DecodeZigzag32

                                                                                                                                  func (p *Buffer) DecodeZigzag32() (x uint64, err error)

                                                                                                                                    DecodeZigzag32 reads a zigzag-encoded 32-bit integer from the Buffer. This is the format used for the sint32 protocol buffer type.

                                                                                                                                    func (*Buffer) DecodeZigzag64

                                                                                                                                    func (p *Buffer) DecodeZigzag64() (x uint64, err error)

                                                                                                                                      DecodeZigzag64 reads a zigzag-encoded 64-bit integer from the Buffer. This is the format used for the sint64 protocol buffer type.

                                                                                                                                      func (*Buffer) EncodeFixed32

                                                                                                                                      func (p *Buffer) EncodeFixed32(x uint64) error

                                                                                                                                        EncodeFixed32 writes a 32-bit integer to the Buffer. This is the format for the fixed32, sfixed32, and float protocol buffer types.

                                                                                                                                        func (*Buffer) EncodeFixed64

                                                                                                                                        func (p *Buffer) EncodeFixed64(x uint64) error

                                                                                                                                          EncodeFixed64 writes a 64-bit integer to the Buffer. This is the format for the fixed64, sfixed64, and double protocol buffer types.

                                                                                                                                          func (*Buffer) EncodeMessage

                                                                                                                                          func (p *Buffer) EncodeMessage(pb Message) error

                                                                                                                                            EncodeMessage writes the protocol buffer to the Buffer, prefixed by a varint-encoded length.

                                                                                                                                            func (*Buffer) EncodeRawBytes

                                                                                                                                            func (p *Buffer) EncodeRawBytes(b []byte) error

                                                                                                                                              EncodeRawBytes writes a count-delimited byte buffer to the Buffer. This is the format used for the bytes protocol buffer type and for embedded messages.

                                                                                                                                              func (*Buffer) EncodeStringBytes

                                                                                                                                              func (p *Buffer) EncodeStringBytes(s string) error

                                                                                                                                                EncodeStringBytes writes an encoded string to the Buffer. This is the format used for the proto2 string type.

                                                                                                                                                func (*Buffer) EncodeVarint

                                                                                                                                                func (p *Buffer) EncodeVarint(x uint64) error

                                                                                                                                                  EncodeVarint writes a varint-encoded integer to the Buffer. This is the format for the int32, int64, uint32, uint64, bool, and enum protocol buffer types.

                                                                                                                                                  func (*Buffer) EncodeZigzag32

                                                                                                                                                  func (p *Buffer) EncodeZigzag32(x uint64) error

                                                                                                                                                    EncodeZigzag32 writes a zigzag-encoded 32-bit integer to the Buffer. This is the format used for the sint32 protocol buffer type.

                                                                                                                                                    func (*Buffer) EncodeZigzag64

                                                                                                                                                    func (p *Buffer) EncodeZigzag64(x uint64) error

                                                                                                                                                      EncodeZigzag64 writes a zigzag-encoded 64-bit integer to the Buffer. This is the format used for the sint64 protocol buffer type.

                                                                                                                                                      func (*Buffer) Marshal

                                                                                                                                                      func (p *Buffer) Marshal(pb Message) error

                                                                                                                                                        Marshal takes a protocol buffer message and encodes it into the wire format, writing the result to the Buffer. This is an alternative entry point. It is not necessary to use a Buffer for most applications.

                                                                                                                                                        func (*Buffer) Reset

                                                                                                                                                        func (p *Buffer) Reset()

                                                                                                                                                          Reset resets the Buffer, ready for marshaling a new protocol buffer.

                                                                                                                                                          func (*Buffer) SetBuf

                                                                                                                                                          func (p *Buffer) SetBuf(s []byte)

                                                                                                                                                            SetBuf replaces the internal buffer with the slice, ready for unmarshaling the contents of the slice.

                                                                                                                                                            func (*Buffer) SetDeterministic

                                                                                                                                                            func (p *Buffer) SetDeterministic(deterministic bool)

                                                                                                                                                              SetDeterministic sets whether to use deterministic serialization.

                                                                                                                                                              Deterministic serialization guarantees that for a given binary, equal messages will always be serialized to the same bytes. This implies:

                                                                                                                                                              - Repeated serialization of a message will return the same bytes.
                                                                                                                                                              - Different processes of the same binary (which may be executing on
                                                                                                                                                                different machines) will serialize equal messages to the same bytes.
                                                                                                                                                              

                                                                                                                                                              Note that the deterministic serialization is NOT canonical across languages. It is not guaranteed to remain stable over time. It is unstable across different builds with schema changes due to unknown fields. Users who need canonical serialization (e.g., persistent storage in a canonical form, fingerprinting, etc.) should define their own canonicalization specification and implement their own serializer rather than relying on this API.

                                                                                                                                                              If deterministic serialization is requested, map entries will be sorted by keys in lexographical order. This is an implementation detail and subject to change.

                                                                                                                                                              func (*Buffer) Unmarshal

                                                                                                                                                              func (p *Buffer) Unmarshal(pb Message) error

                                                                                                                                                                Unmarshal parses the protocol buffer representation in the Buffer and places the decoded result in pb. If the struct underlying pb does not match the data in the buffer, the results can be unpredictable.

                                                                                                                                                                Unlike proto.Unmarshal, this does not reset pb before starting to unmarshal.

                                                                                                                                                                type Extension

                                                                                                                                                                type Extension struct {
                                                                                                                                                                	// contains filtered or unexported fields
                                                                                                                                                                }

                                                                                                                                                                  Extension represents an extension in a message.

                                                                                                                                                                  func NewExtension

                                                                                                                                                                  func NewExtension(e []byte) Extension

                                                                                                                                                                  func (*Extension) Compare

                                                                                                                                                                  func (this *Extension) Compare(that *Extension) int

                                                                                                                                                                  func (*Extension) Encode

                                                                                                                                                                  func (this *Extension) Encode() error

                                                                                                                                                                  func (*Extension) Equal

                                                                                                                                                                  func (this *Extension) Equal(that *Extension) bool

                                                                                                                                                                  func (Extension) GoString

                                                                                                                                                                  func (this Extension) GoString() string

                                                                                                                                                                  type ExtensionDesc

                                                                                                                                                                  type ExtensionDesc struct {
                                                                                                                                                                  	ExtendedType  Message     // nil pointer to the type that is being extended
                                                                                                                                                                  	ExtensionType interface{} // nil pointer to the extension type
                                                                                                                                                                  	Field         int32       // field number
                                                                                                                                                                  	Name          string      // fully-qualified name of extension, for text formatting
                                                                                                                                                                  	Tag           string      // protobuf tag style
                                                                                                                                                                  	Filename      string      // name of the file in which the extension is defined
                                                                                                                                                                  }

                                                                                                                                                                    ExtensionDesc represents an extension specification. Used in generated code from the protocol compiler.

                                                                                                                                                                    func ExtensionDescs

                                                                                                                                                                    func ExtensionDescs(pb Message) ([]*ExtensionDesc, error)

                                                                                                                                                                      ExtensionDescs returns a new slice containing pb's extension descriptors, in undefined order. For non-registered extensions, ExtensionDescs returns an incomplete descriptor containing just the Field field, which defines the extension's field number.

                                                                                                                                                                      type ExtensionRange

                                                                                                                                                                      type ExtensionRange struct {
                                                                                                                                                                      	Start, End int32 // both inclusive
                                                                                                                                                                      }

                                                                                                                                                                        ExtensionRange represents a range of message extensions for a protocol buffer. Used in code generated by the protocol compiler.

                                                                                                                                                                        type InternalMessageInfo

                                                                                                                                                                        type InternalMessageInfo struct {
                                                                                                                                                                        	// contains filtered or unexported fields
                                                                                                                                                                        }

                                                                                                                                                                          InternalMessageInfo is a type used internally by generated .pb.go files. This type is not intended to be used by non-generated code. This type is not subject to any compatibility guarantee.

                                                                                                                                                                          func (*InternalMessageInfo) DiscardUnknown

                                                                                                                                                                          func (a *InternalMessageInfo) DiscardUnknown(m Message)

                                                                                                                                                                            DiscardUnknown recursively discards all unknown fields.

                                                                                                                                                                            func (*InternalMessageInfo) Marshal

                                                                                                                                                                            func (a *InternalMessageInfo) Marshal(b []byte, msg Message, deterministic bool) ([]byte, error)

                                                                                                                                                                              Marshal is the entry point from generated code, and should be ONLY called by generated code. It marshals msg to the end of b. a is a pointer to a place to store cached marshal info.

                                                                                                                                                                              func (*InternalMessageInfo) Merge

                                                                                                                                                                              func (a *InternalMessageInfo) Merge(dst, src Message)

                                                                                                                                                                                Merge merges the src message into dst. This assumes that dst and src of the same type and are non-nil.

                                                                                                                                                                                func (*InternalMessageInfo) Size

                                                                                                                                                                                func (a *InternalMessageInfo) Size(msg Message) int

                                                                                                                                                                                  Size is the entry point from generated code, and should be ONLY called by generated code. It computes the size of encoded data of msg. a is a pointer to a place to store cached marshal info.

                                                                                                                                                                                  func (*InternalMessageInfo) Unmarshal

                                                                                                                                                                                  func (a *InternalMessageInfo) Unmarshal(msg Message, b []byte) error

                                                                                                                                                                                    Unmarshal is the entry point from the generated .pb.go files. This function is not intended to be used by non-generated code. This function is not subject to any compatibility guarantee. msg contains a pointer to a protocol buffer struct. b is the data to be unmarshaled into the protocol buffer. a is a pointer to a place to store cached unmarshal information.

                                                                                                                                                                                    type Marshaler

                                                                                                                                                                                    type Marshaler interface {
                                                                                                                                                                                    	Marshal() ([]byte, error)
                                                                                                                                                                                    }

                                                                                                                                                                                      Marshaler is the interface representing objects that can marshal themselves.

                                                                                                                                                                                      type Merger

                                                                                                                                                                                      type Merger interface {
                                                                                                                                                                                      	// Merge merges src into this message.
                                                                                                                                                                                      	// Required and optional fields that are set in src will be set to that value in dst.
                                                                                                                                                                                      	// Elements of repeated fields will be appended.
                                                                                                                                                                                      	//
                                                                                                                                                                                      	// Merge may panic if called with a different argument type than the receiver.
                                                                                                                                                                                      	Merge(src Message)
                                                                                                                                                                                      }

                                                                                                                                                                                        Merger is the interface representing objects that can merge messages of the same type.

                                                                                                                                                                                        type Message

                                                                                                                                                                                        type Message interface {
                                                                                                                                                                                        	Reset()
                                                                                                                                                                                        	String() string
                                                                                                                                                                                        	ProtoMessage()
                                                                                                                                                                                        }

                                                                                                                                                                                          Message is implemented by generated protocol buffer messages.

                                                                                                                                                                                          func Clone

                                                                                                                                                                                          func Clone(src Message) Message

                                                                                                                                                                                            Clone returns a deep copy of a protocol buffer.

                                                                                                                                                                                            type OneofProperties

                                                                                                                                                                                            type OneofProperties struct {
                                                                                                                                                                                            	Type  reflect.Type // pointer to generated struct type for this oneof field
                                                                                                                                                                                            	Field int          // struct field number of the containing oneof in the message
                                                                                                                                                                                            	Prop  *Properties
                                                                                                                                                                                            }

                                                                                                                                                                                              OneofProperties represents information about a specific field in a oneof.

                                                                                                                                                                                              type ParseError

                                                                                                                                                                                              type ParseError struct {
                                                                                                                                                                                              	Message string
                                                                                                                                                                                              	Line    int // 1-based line number
                                                                                                                                                                                              	Offset  int // 0-based byte offset from start of input
                                                                                                                                                                                              }

                                                                                                                                                                                              func (*ParseError) Error

                                                                                                                                                                                              func (p *ParseError) Error() string

                                                                                                                                                                                              type Properties

                                                                                                                                                                                              type Properties struct {
                                                                                                                                                                                              	Name     string // name of the field, for error messages
                                                                                                                                                                                              	OrigName string // original name before protocol compiler (always set)
                                                                                                                                                                                              	JSONName string // name to use for JSON; determined by protoc
                                                                                                                                                                                              	Wire     string
                                                                                                                                                                                              	WireType int
                                                                                                                                                                                              	Tag      int
                                                                                                                                                                                              	Required bool
                                                                                                                                                                                              	Optional bool
                                                                                                                                                                                              	Repeated bool
                                                                                                                                                                                              	Packed   bool   // relevant for repeated primitives only
                                                                                                                                                                                              	Enum     string // set for enum types only
                                                                                                                                                                                              
                                                                                                                                                                                              	Default     string // default value
                                                                                                                                                                                              	HasDefault  bool   // whether an explicit default was provided
                                                                                                                                                                                              	CustomType  string
                                                                                                                                                                                              	CastType    string
                                                                                                                                                                                              	StdTime     bool
                                                                                                                                                                                              	StdDuration bool
                                                                                                                                                                                              	WktPointer  bool
                                                                                                                                                                                              
                                                                                                                                                                                              	MapKeyProp *Properties // set for map types only
                                                                                                                                                                                              	MapValProp *Properties // set for map types only
                                                                                                                                                                                              	// contains filtered or unexported fields
                                                                                                                                                                                              }

                                                                                                                                                                                                Properties represents the protocol-specific behavior of a single struct field.

                                                                                                                                                                                                func (*Properties) Init

                                                                                                                                                                                                func (p *Properties) Init(typ reflect.Type, name, tag string, f *reflect.StructField)

                                                                                                                                                                                                  Init populates the properties from a protocol buffer struct tag.

                                                                                                                                                                                                  func (*Properties) Parse

                                                                                                                                                                                                  func (p *Properties) Parse(s string)

                                                                                                                                                                                                    Parse populates p by parsing a string in the protobuf struct field tag style.

                                                                                                                                                                                                    func (*Properties) String

                                                                                                                                                                                                    func (p *Properties) String() string

                                                                                                                                                                                                      String formats the properties in the protobuf struct field tag style.

                                                                                                                                                                                                      type ProtoSizer

                                                                                                                                                                                                      type ProtoSizer interface {
                                                                                                                                                                                                      	ProtoSize() int
                                                                                                                                                                                                      }

                                                                                                                                                                                                      type RequiredNotSetError

                                                                                                                                                                                                      type RequiredNotSetError struct {
                                                                                                                                                                                                      	// contains filtered or unexported fields
                                                                                                                                                                                                      }

                                                                                                                                                                                                        RequiredNotSetError is an error type returned by either Marshal or Unmarshal. Marshal reports this when a required field is not initialized. Unmarshal reports this when a required field is missing from the wire data.

                                                                                                                                                                                                        func NewRequiredNotSetError

                                                                                                                                                                                                        func NewRequiredNotSetError(field string) *RequiredNotSetError

                                                                                                                                                                                                        func (*RequiredNotSetError) Error

                                                                                                                                                                                                        func (e *RequiredNotSetError) Error() string

                                                                                                                                                                                                        func (*RequiredNotSetError) RequiredNotSet

                                                                                                                                                                                                        func (e *RequiredNotSetError) RequiredNotSet() bool

                                                                                                                                                                                                        type Sizer

                                                                                                                                                                                                        type Sizer interface {
                                                                                                                                                                                                        	Size() int
                                                                                                                                                                                                        }

                                                                                                                                                                                                        type Stats

                                                                                                                                                                                                        type Stats struct{ Emalloc, Dmalloc, Encode, Decode, Chit, Cmiss, Size uint64 }

                                                                                                                                                                                                          Deprecated: do not use.

                                                                                                                                                                                                          func GetStats

                                                                                                                                                                                                          func GetStats() Stats

                                                                                                                                                                                                            Deprecated: do not use.

                                                                                                                                                                                                            type StructProperties

                                                                                                                                                                                                            type StructProperties struct {
                                                                                                                                                                                                            	Prop []*Properties // properties for each field
                                                                                                                                                                                                            
                                                                                                                                                                                                            	// OneofTypes contains information about the oneof fields in this message.
                                                                                                                                                                                                            	// It is keyed by the original name of a field.
                                                                                                                                                                                                            	OneofTypes map[string]*OneofProperties
                                                                                                                                                                                                            	// contains filtered or unexported fields
                                                                                                                                                                                                            }

                                                                                                                                                                                                              StructProperties represents properties for all the fields of a struct. decoderTags and decoderOrigNames should only be used by the decoder.

                                                                                                                                                                                                              func GetProperties

                                                                                                                                                                                                              func GetProperties(t reflect.Type) *StructProperties

                                                                                                                                                                                                                GetProperties returns the list of properties for the type represented by t. t must represent a generated struct type of a protocol message.

                                                                                                                                                                                                                func (*StructProperties) Len

                                                                                                                                                                                                                func (sp *StructProperties) Len() int

                                                                                                                                                                                                                func (*StructProperties) Less

                                                                                                                                                                                                                func (sp *StructProperties) Less(i, j int) bool

                                                                                                                                                                                                                func (*StructProperties) Swap

                                                                                                                                                                                                                func (sp *StructProperties) Swap(i, j int)

                                                                                                                                                                                                                type TextMarshaler

                                                                                                                                                                                                                type TextMarshaler struct {
                                                                                                                                                                                                                	Compact   bool // use compact text format (one line).
                                                                                                                                                                                                                	ExpandAny bool // expand google.protobuf.Any messages of known types
                                                                                                                                                                                                                }

                                                                                                                                                                                                                  TextMarshaler is a configurable text format marshaler.

                                                                                                                                                                                                                  func (*TextMarshaler) Marshal

                                                                                                                                                                                                                  func (tm *TextMarshaler) Marshal(w io.Writer, pb Message) error

                                                                                                                                                                                                                    Marshal writes a given protocol buffer in text format. The only errors returned are from w.

                                                                                                                                                                                                                    func (*TextMarshaler) Text

                                                                                                                                                                                                                    func (tm *TextMarshaler) Text(pb Message) string

                                                                                                                                                                                                                      Text is the same as Marshal, but returns the string directly.

                                                                                                                                                                                                                      type Unmarshaler

                                                                                                                                                                                                                      type Unmarshaler interface {
                                                                                                                                                                                                                      	Unmarshal([]byte) error
                                                                                                                                                                                                                      }

                                                                                                                                                                                                                        Unmarshaler is the interface representing objects that can unmarshal themselves. The argument points to data that may be overwritten, so implementations should not keep references to the buffer. Unmarshal implementations should not clear the receiver. Any unmarshaled data should be merged into the receiver. Callers of Unmarshal that do not want to retain existing data should Reset the receiver before calling Unmarshal.

                                                                                                                                                                                                                        type XXX_InternalExtensions

                                                                                                                                                                                                                        type XXX_InternalExtensions struct {
                                                                                                                                                                                                                        	// contains filtered or unexported fields
                                                                                                                                                                                                                        }

                                                                                                                                                                                                                          XXX_InternalExtensions is an internal representation of proto extensions.

                                                                                                                                                                                                                          Each generated message struct type embeds an anonymous XXX_InternalExtensions field, thus gaining the unexported 'extensions' method, which can be called only from the proto package.

                                                                                                                                                                                                                          The methods of XXX_InternalExtensions are not concurrency safe in general, but calls to logically read-only methods such as has and get may be executed concurrently.

                                                                                                                                                                                                                          func NewUnsafeXXX_InternalExtensions

                                                                                                                                                                                                                          func NewUnsafeXXX_InternalExtensions(m map[int32]Extension) XXX_InternalExtensions

                                                                                                                                                                                                                          Directories

                                                                                                                                                                                                                          Path Synopsis