proto - Go Packages (original) (raw)

Package proto provides functionality for handling protocol buffer messages. In particular, it provides marshaling and unmarshaling between a protobuf message and the binary wire format.

See https://developers.google.com/protocol-buffers/docs/gotutorial for more information.

Deprecated: Use the "google.golang.org/protobuf/proto" package instead.

Constants
Variables
func Bool(v bool) *bool
func ClearAllExtensions(m Message)
func ClearExtension(m Message, xt *ExtensionDesc)
func CompactText(w io.Writer, m Message) error
func CompactTextString(m Message) string
func DecodeVarint(b []byte) (uint64, int)
func DiscardUnknown(m Message)
func EncodeVarint(v uint64) []byte
func EnumName(m map[int32]string, v int32) stringdeprecated
func EnumValueMap(s enumName) enumsByNamedeprecated
func Equal(x, y Message) bool
func FileDescriptor(s filePath) fileDescGZIPdeprecated
func Float32(v float32) *float32
func Float64(v float64) *float64
func GetExtension(m Message, xt *ExtensionDesc) (interface{}, error)
func GetExtensions(m Message, xts []*ExtensionDesc) ([]interface{}, error)
func HasExtension(m Message, xt *ExtensionDesc) (has bool)
func Int(v int) *int32deprecated
func Int32(v int32) *int32
func Int64(v int64) *int64
func Marshal(m Message) ([]byte, error)
func MarshalMessageSet(interface{}) ([]byte, error)deprecated
func MarshalMessageSetJSON(interface{}) ([]byte, error)deprecated
func MarshalText(w io.Writer, m Message) error
func MarshalTextString(m Message) string
func Merge(dst, src Message)
func MessageName(m Message) messageNamedeprecated
func MessageReflect(m Message) protoreflect.Message
func MessageType(s messageName) reflect.Typedeprecated
func MessageV1(m GeneratedMessage) protoiface.MessageV1
func MessageV2(m GeneratedMessage) protoV2.Message
func RegisterEnum(s enumName, _ enumsByNumber, m enumsByName)deprecated
func RegisterExtension(d *ExtensionDesc)deprecated
func RegisterFile(s filePath, d fileDescGZIP)deprecated
func RegisterMapType(m interface{}, s messageName)deprecated
func RegisterMessageSetType(Message, int32, string)deprecated
func RegisterType(m Message, s messageName)deprecated
func RegisteredExtensions(m Message) extensionsByNumberdeprecated
func SetDefaults(m Message)
func SetExtension(m Message, xt *ExtensionDesc, v interface{}) error
func SetRawExtension(m Message, fnum int32, b []byte)deprecated
func Size(m Message) int
func SizeVarint(v uint64) int
func String(v string) *string
func Uint32(v uint32) *uint32
func Uint64(v uint64) *uint64
func Unmarshal(b []byte, m Message) error
func UnmarshalJSONEnum(m map[string]int32, data []byte, enumName string) (int32, error)deprecated
func UnmarshalMerge(b []byte, m Message) error
func UnmarshalMessageSet([]byte, interface{}) errordeprecated
func UnmarshalMessageSetJSON([]byte, interface{}) errordeprecated
func UnmarshalText(s string, m Message) error
type Buffer
- func NewBuffer(buf []byte) *Buffer
- func (b *Buffer) Bytes() []byte
- func (*Buffer) DebugPrint(s string, b []byte)
- func (b *Buffer) DecodeFixed32() (uint64, error)
- func (b *Buffer) DecodeFixed64() (uint64, error)
- func (b *Buffer) DecodeGroup(m Message) error
- func (b *Buffer) DecodeMessage(m Message) error
- func (b *Buffer) DecodeRawBytes(alloc bool) ([]byte, error)
- func (b *Buffer) DecodeStringBytes() (string, error)
- func (b *Buffer) DecodeVarint() (uint64, error)
- func (b *Buffer) DecodeZigzag32() (uint64, error)
- func (b *Buffer) DecodeZigzag64() (uint64, error)
- func (b *Buffer) EncodeFixed32(v uint64) error
- func (b *Buffer) EncodeFixed64(v uint64) error
- func (b *Buffer) EncodeMessage(m Message) error
- func (b *Buffer) EncodeRawBytes(v []byte) error
- func (b *Buffer) EncodeStringBytes(v string) error
- func (b *Buffer) EncodeVarint(v uint64) error
- func (b *Buffer) EncodeZigzag32(v uint64) error
- func (b *Buffer) EncodeZigzag64(v uint64) error
- func (b *Buffer) Marshal(m Message) error
- func (b *Buffer) Reset()
- func (b *Buffer) SetBuf(buf []byte)
- func (b *Buffer) SetDeterministic(deterministic bool)
- func (b *Buffer) Unmarshal(m Message) error
- func (b *Buffer) Unread() []byte
type Extensiondeprecated
type ExtensionDesc
- func ExtensionDescs(m Message) ([]*ExtensionDesc, error)
type ExtensionRange
type GeneratedEnum
type GeneratedMessage
type InternalMessageInfodeprecated
- func (*InternalMessageInfo) DiscardUnknown(m Message)deprecated
- func (*InternalMessageInfo) Marshal(b []byte, m Message, deterministic bool) ([]byte, error)deprecated
- func (*InternalMessageInfo) Merge(dst, src Message)deprecated
- func (*InternalMessageInfo) Size(m Message) intdeprecated
- func (*InternalMessageInfo) Unmarshal(m Message, b []byte) errordeprecated
type Marshalerdeprecated
type Mergerdeprecated
type Message
- func Clone(src Message) Message
type OneofPropertiesdeprecated
type ParseError
- func (e *ParseError) Error() string
type Propertiesdeprecated
- func (p *Properties) Init(typ reflect.Type, name, tag string, f *reflect.StructField)deprecated
- func (p *Properties) Parse(tag string)
- func (p *Properties) String() string
type RequiredNotSetError
- func (e *RequiredNotSetError) Error() string
- func (e *RequiredNotSetError) RequiredNotSet() bool
type Statsdeprecated
- func GetStats() Statsdeprecated
type StructPropertiesdeprecated
- func GetProperties(t reflect.Type) *StructPropertiesdeprecated
- func (sp *StructProperties) Len() int
- func (sp *StructProperties) Less(i, j int) bool
- func (sp *StructProperties) Swap(i, j int)
type TextMarshaler
- func (tm *TextMarshaler) Marshal(w io.Writer, m Message) error
- func (tm *TextMarshaler) Text(m Message) string
type Unmarshalerdeprecated
type XXX_InternalExtensionsdeprecated

View Source

const ( WireVarint = 0 WireFixed32 = 5 WireFixed64 = 1 WireBytes = 2 WireStartGroup = 3 WireEndGroup = 4 )

View Source

const ( ProtoPackageIsVersion1 = true ProtoPackageIsVersion2 = true ProtoPackageIsVersion3 = true ProtoPackageIsVersion4 = true )

View Source

var (

ErrNil = [errors](/errors).[New](/errors#New)("proto: Marshal called with nil")


ErrTooLarge = [errors](/errors).[New](/errors#New)("proto: message encodes to over 2 GB")


ErrInternalBadWireType = [errors](/errors).[New](/errors#New)("proto: internal error: bad wiretype for oneof")

)

ErrMissingExtension reports whether the extension was not present.

Bool stores v in a new bool value and returns a pointer to it.

func ClearAllExtensions(m Message)

ClearAllExtensions clears all extensions from m. This includes populated fields and unknown fields in the extension range.

func ClearExtension(m Message, xt *ExtensionDesc)

ClearExtension removes the extension field from m either as an explicitly populated field or as an unknown field.

CompactText writes the compact proto text format of m to w.

CompactTextString returns a compact proto text formatted string of m.

DecodeVarint parses a varint encoded integer from b, returning the integer value and the length of the varint. It returns (0, 0) if there is a parse error.

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.

EncodeVarint returns the varint encoded bytes of v.

func EnumValueMap(s enumName) enumsByName

EnumValueMap returns the mapping from enum value names to enum numbers for the enum of the given name. It returns nil if not found.

Deprecated: Use protoregistry.GlobalTypes.FindEnumByName instead.

Equal reports whether two messages are equal. If two messages marshal to the same bytes under deterministic serialization, then Equal is guaranteed to report true.

Two messages are equal if they are the same protobuf message type, have the same set of populated known and extension field values, and the same set of unknown fields values.

Scalar values are compared with the equivalent of the == operator in Go, except bytes values which are compared using bytes.Equal and floating point values which specially treat NaNs as equal. Message values are compared by recursively calling Equal. Lists are equal if each element value is also equal. Maps are equal if they have the same set of keys, where the pair of values for each key is also equal.

func FileDescriptor(s filePath) fileDescGZIP

FileDescriptor returns the compressed FileDescriptorProto given the file path for a proto source file. It returns nil if not found.

Deprecated: Use protoregistry.GlobalFiles.FindFileByPath instead.

Float32 stores v in a new float32 value and returns a pointer to it.

Float64 stores v in a new float64 value and returns a pointer to it.

func GetExtension(m Message, xt *ExtensionDesc) (interface{}, error)

GetExtension retrieves a proto2 extended field from m.

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 type incomplete (i.e., ExtensionDesc.ExtensionType is nil), then GetExtension returns the raw encoded bytes for the extension field.

func GetExtensions(m Message, xts []*ExtensionDesc) ([]interface{}, error)

GetExtensions returns a list of the extensions values present in m, corresponding with the provided list of extension descriptors, xts. If an extension is missing in m, the corresponding value is nil.

func HasExtension(m Message, xt *ExtensionDesc) (has bool)

HasExtension reports whether the extension field is present in m either as an explicitly populated field or as an unknown field.

Int stores v in a new int32 value and returns a pointer to it.

Deprecated: Use Int32 instead.

Int32 stores v in a new int32 value and returns a pointer to it.

Int64 stores v in a new int64 value and returns a pointer to it.

Marshal returns the wire-format encoding of m.

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

Deprecated: Do not use.

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

Deprecated: Do not use.

MarshalText writes the proto text format of m to w.

MarshalTextString returns a proto text formatted string of m.

func Merge(dst, src Message)

Merge merges src into dst, which must be messages of the same type.

Populated scalar fields in src are copied to dst, while populated singular messages in src are merged into dst by recursively calling Merge. The elements of every list field in src is appended to the corresponded list fields in dst. The entries of every map field in src is copied into the corresponding map field in dst, possibly replacing existing entries. The unknown fields of src are appended to the unknown fields of dst.

func MessageName(m Message) messageName

MessageName returns the full protobuf name for the given message type.

Deprecated: Use protoreflect.MessageDescriptor.FullName instead.

MessageReflect returns a reflective view for a message. It returns nil if m is nil.

MessageType returns the message type for a named message. It returns nil if not found.

Deprecated: Use protoregistry.GlobalTypes.FindMessageByName instead.

MessageV1 converts either a v1 or v2 message to a v1 message. It returns nil if m is nil.

MessageV2 converts either a v1 or v2 message to a v2 message. It returns nil if m is nil.

func RegisterEnum(s enumName, _ enumsByNumber, m enumsByName)

RegisterEnum is called from the generated code to register the mapping of enum value names to enum numbers for the enum identified by s.

Deprecated: Use protoregistry.GlobalTypes.RegisterEnum instead.

func RegisterExtension(d *ExtensionDesc)

RegisterExtension is called from the generated code to register the extension descriptor.

Deprecated: Use protoregistry.GlobalTypes.RegisterExtension instead.

func RegisterFile(s filePath, d fileDescGZIP)

RegisterFile is called from generated code to register the compressed FileDescriptorProto with the file path for a proto source file.

Deprecated: Use protoregistry.GlobalFiles.RegisterFile instead.

func RegisterMapType(m interface{}, s messageName)

RegisterMapType is called from generated code to register the Go map type for a protobuf message representing a map entry.

Deprecated: Do not use.

func RegisterType(m Message, s messageName)

RegisterType is called from generated code to register the message Go type for a message of the given name.

Deprecated: Use protoregistry.GlobalTypes.RegisterMessage instead.

func RegisteredExtensions(m Message) extensionsByNumber

RegisteredExtensions returns a map of the registered extensions for the provided protobuf message, indexed by the extension field number.

Deprecated: Use protoregistry.GlobalTypes.RangeExtensionsByMessage instead.

func SetDefaults(m Message)

SetDefaults sets unpopulated scalar fields to their default values. Fields within a oneof are not set even if they have a default value. SetDefaults is recursively called upon any populated message fields.

func SetExtension(m Message, xt *ExtensionDesc, v interface{}) error

SetExtension sets an extension field in m to the provided value.

SetRawExtension inserts b into the unknown fields of m.

Deprecated: Use Message.ProtoReflect.SetUnknown instead.

Size returns the size in bytes of the wire-format encoding of m.

SizeVarint returns the length of the varint encoded bytes of v. This is equal to len(EncodeVarint(v)).

String stores v in a new string value and returns a pointer to it.

Uint32 stores v in a new uint32 value and returns a pointer to it.

Uint64 stores v in a new uint64 value and returns a pointer to it.

Unmarshal parses a wire-format message in b and places the decoded results in m.

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

UnmarshalMerge parses a wire-format message in b and places the decoded results in m.

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

Deprecated: Do not use.

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

Deprecated: Do not use.

UnmarshalText parses a proto text formatted string into m.

Buffer is a buffer for encoding and decoding the protobuf wire format. It may be reused between invocations to reduce memory usage.

func NewBuffer(buf []byte) *Buffer

NewBuffer allocates a new Buffer initialized with buf, where the contents of buf are considered the unread portion of the buffer.

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

Bytes returns the internal buffer.

DebugPrint dumps the encoded bytes of b with a header and footer including s to stdout. This is only intended for debugging.

DecodeFixed32 consumes a 32-bit little-endian integer from the buffer.

DecodeFixed64 consumes a 64-bit little-endian integer from the buffer.

func (b *Buffer) DecodeGroup(m Message) error

DecodeGroup consumes a message group from the buffer. It assumes that the start group marker has already been consumed and consumes all bytes until (and including the end group marker). It does not reset m before unmarshaling.

func (b *Buffer) DecodeMessage(m Message) error

DecodeMessage consumes a length-prefixed message from the buffer. It does not reset m before unmarshaling.

DecodeRawBytes consumes a length-prefixed raw bytes from the buffer. If alloc is specified, it returns a copy the raw bytes rather than a sub-slice of the buffer.

DecodeStringBytes consumes a length-prefixed raw bytes from the buffer. It does not validate whether the raw bytes contain valid UTF-8.

DecodeVarint consumes an encoded unsigned varint from the buffer.

DecodeZigzag32 consumes an encoded 32-bit zig-zag varint from the buffer.

DecodeZigzag64 consumes an encoded 64-bit zig-zag varint from the buffer.

EncodeFixed32 appends a 32-bit little-endian integer to the buffer.

EncodeFixed64 appends a 64-bit little-endian integer to the buffer.

func (b *Buffer) EncodeMessage(m Message) error

EncodeMessage appends a length-prefixed encoded message to the buffer.

EncodeRawBytes appends a length-prefixed raw bytes to the buffer.

EncodeStringBytes appends a length-prefixed raw bytes to the buffer. It does not validate whether v contains valid UTF-8.

EncodeVarint appends an unsigned varint encoding to the buffer.

EncodeZigzag32 appends a 32-bit zig-zag varint encoding to the buffer.

EncodeZigzag64 appends a 64-bit zig-zag varint encoding to the buffer.

Marshal appends the wire-format encoding of m to the buffer.

Reset clears the internal buffer of all written and unread data.

func (b *Buffer) SetBuf(buf []byte)

SetBuf sets buf as the internal buffer, where the contents of buf are considered the unread portion of the buffer.

func (b *Buffer) SetDeterministic(deterministic bool)

SetDeterministic specifies 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.

Unmarshal parses the wire-format message in the buffer and places the decoded results in m. It does not reset m before unmarshaling.

func (b *Buffer) Unread() []byte

Unread returns the unread portion of the buffer.

Deprecated: Do not use; this is an internal type.

ExtensionDesc represents an extension descriptor and is used to interact with an extension field in a message.

Variables of this type are generated in code by protoc-gen-go.

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

ExtensionDescs returns a list of extension descriptors found in m, containing descriptors for both populated extension fields in m and also unknown fields of m that are in the extension range. For the later case, an type incomplete descriptor is provided where only the ExtensionDesc.Field field is populated. The order of the extension descriptors is undefined.

ExtensionRange represents a range of message extensions. Used in code generated by protoc-gen-go.

type GeneratedEnum interface{}

GeneratedEnum is any enum type generated by protoc-gen-go which is a named int32 kind. This type exists for documentation purposes.

type GeneratedMessage interface{}

GeneratedMessage is any message type generated by protoc-gen-go which is a pointer to a named struct kind. This type exists for documentation purposes.

type InternalMessageInfo struct{}

Deprecated: Do not use; this type existed for intenal-use only.

func (*InternalMessageInfo) DiscardUnknown(m Message)

Deprecated: Do not use; this method existed for intenal-use only.

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

Deprecated: Do not use; this method existed for intenal-use only.

type Marshaler interface {

Marshal() ([][byte](/builtin#byte), [error](/builtin#error))

}

Marshaler is implemented by messages that can marshal themselves. This interface is used by the following functions: Size, Marshal, Buffer.Marshal, and Buffer.EncodeMessage.

Deprecated: Do not implement.

type Merger interface {

Merge(src [Message](#Message))

}

Merger is implemented by messages that can merge themselves. This interface is used by the following functions: Clone and Merge.

Deprecated: Do not implement.

Message is a protocol buffer message.

This is the v1 version of the message interface and is marginally better than an empty interface as it lacks any method to programatically interact with the contents of the message.

A v2 message is declared in "google.golang.org/protobuf/proto".Message and exposes protobuf reflection as a first-class feature of the interface.

To convert a v1 message to a v2 message, use the MessageV2 function. To convert a v2 message to a v1 message, use the MessageV1 function.

func Clone(src Message) Message

Clone returns a deep copy of src.

OneofProperties represents the type information for a protobuf oneof.

Deprecated: Do not use.

type ParseError struct { Message string

Line, Offset [int](/builtin#int)

}

ParseError is returned by UnmarshalText.

Properties represents the type information for a protobuf message field.

Deprecated: Do not use.

Init populates the properties from a protocol buffer struct tag.

Deprecated: Do not use.

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

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

type RequiredNotSetError struct {

}

RequiredNotSetError is an error type returned when marshaling or unmarshaling a message with missing required fields.

func (e *RequiredNotSetError) RequiredNotSet() bool

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

Deprecated: Do not use.

type StructProperties struct {

Prop []*[Properties](#Properties)


OneofTypes map[[string](/builtin#string)]*[OneofProperties](#OneofProperties)

}

StructProperties represents protocol buffer type information for a generated protobuf message in the open-struct API.

Deprecated: Do not use.

GetProperties returns the list of properties for the type represented by t, which must be a generated protocol buffer message in the open-struct API, where protobuf message fields are represented by exported Go struct fields.

Deprecated: Use protobuf reflection instead.

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

type TextMarshaler struct { Compact bool ExpandAny bool }

TextMarshaler is a configurable text format marshaler.

Marshal writes the proto text format of m to w.

Text returns a proto text formatted string of m.

type Unmarshaler interface {

Unmarshal([][byte](/builtin#byte)) [error](/builtin#error)

}

Unmarshaler is implemented by messages that can unmarshal themselves. This interface is used by the following functions: Unmarshal, UnmarshalMerge, Buffer.Unmarshal, Buffer.DecodeMessage, and Buffer.DecodeGroup.

Deprecated: Do not implement.

Deprecated: Do not use; this is an internal type.