blob: 5aee89c323e0ad4b166ad6e409456c43c16862ea [file] [log] [blame]
mpagenkoaf801632020-07-03 10:00:42 +00001// Copyright 2019 The Go Authors. All rights reserved.
2// Use of this source code is governed by a BSD-style
3// license that can be found in the LICENSE file.
4
5// Package proto provides functionality for handling protocol buffer messages.
6// In particular, it provides marshaling and unmarshaling between a protobuf
7// message and the binary wire format.
8//
9// See https://developers.google.com/protocol-buffers/docs/gotutorial for
10// more information.
11//
12// Deprecated: Use the "google.golang.org/protobuf/proto" package instead.
13package proto
14
15import (
16 protoV2 "google.golang.org/protobuf/proto"
17 "google.golang.org/protobuf/reflect/protoreflect"
18 "google.golang.org/protobuf/runtime/protoiface"
19 "google.golang.org/protobuf/runtime/protoimpl"
20)
21
22const (
23 ProtoPackageIsVersion1 = true
24 ProtoPackageIsVersion2 = true
25 ProtoPackageIsVersion3 = true
26 ProtoPackageIsVersion4 = true
27)
28
29// GeneratedEnum is any enum type generated by protoc-gen-go
30// which is a named int32 kind.
31// This type exists for documentation purposes.
32type GeneratedEnum interface{}
33
34// GeneratedMessage is any message type generated by protoc-gen-go
35// which is a pointer to a named struct kind.
36// This type exists for documentation purposes.
37type GeneratedMessage interface{}
38
39// Message is a protocol buffer message.
40//
41// This is the v1 version of the message interface and is marginally better
42// than an empty interface as it lacks any method to programatically interact
43// with the contents of the message.
44//
45// A v2 message is declared in "google.golang.org/protobuf/proto".Message and
46// exposes protobuf reflection as a first-class feature of the interface.
47//
48// To convert a v1 message to a v2 message, use the MessageV2 function.
49// To convert a v2 message to a v1 message, use the MessageV1 function.
50type Message = protoiface.MessageV1
51
52// MessageV1 converts either a v1 or v2 message to a v1 message.
53// It returns nil if m is nil.
54func MessageV1(m GeneratedMessage) protoiface.MessageV1 {
55 return protoimpl.X.ProtoMessageV1Of(m)
56}
57
58// MessageV2 converts either a v1 or v2 message to a v2 message.
59// It returns nil if m is nil.
60func MessageV2(m GeneratedMessage) protoV2.Message {
61 return protoimpl.X.ProtoMessageV2Of(m)
62}
63
64// MessageReflect returns a reflective view for a message.
65// It returns nil if m is nil.
66func MessageReflect(m Message) protoreflect.Message {
67 return protoimpl.X.MessageOf(m)
68}
69
70// Marshaler is implemented by messages that can marshal themselves.
71// This interface is used by the following functions: Size, Marshal,
72// Buffer.Marshal, and Buffer.EncodeMessage.
73//
74// Deprecated: Do not implement.
75type Marshaler interface {
76 // Marshal formats the encoded bytes of the message.
77 // It should be deterministic and emit valid protobuf wire data.
78 // The caller takes ownership of the returned buffer.
79 Marshal() ([]byte, error)
80}
81
82// Unmarshaler is implemented by messages that can unmarshal themselves.
83// This interface is used by the following functions: Unmarshal, UnmarshalMerge,
84// Buffer.Unmarshal, Buffer.DecodeMessage, and Buffer.DecodeGroup.
85//
86// Deprecated: Do not implement.
87type Unmarshaler interface {
88 // Unmarshal parses the encoded bytes of the protobuf wire input.
89 // The provided buffer is only valid for during method call.
90 // It should not reset the receiver message.
91 Unmarshal([]byte) error
92}
93
94// Merger is implemented by messages that can merge themselves.
95// This interface is used by the following functions: Clone and Merge.
96//
97// Deprecated: Do not implement.
98type Merger interface {
99 // Merge merges the contents of src into the receiver message.
100 // It clones all data structures in src such that it aliases no mutable
101 // memory referenced by src.
102 Merge(src Message)
103}
104
105// RequiredNotSetError is an error type returned when
106// marshaling or unmarshaling a message with missing required fields.
107type RequiredNotSetError struct {
108 err error
109}
110
111func (e *RequiredNotSetError) Error() string {
112 if e.err != nil {
113 return e.err.Error()
114 }
115 return "proto: required field not set"
116}
117func (e *RequiredNotSetError) RequiredNotSet() bool {
118 return true
119}
120
121func checkRequiredNotSet(m protoV2.Message) error {
122 if err := protoV2.CheckInitialized(m); err != nil {
123 return &RequiredNotSetError{err: err}
124 }
125 return nil
126}
127
128// Clone returns a deep copy of src.
129func Clone(src Message) Message {
130 return MessageV1(protoV2.Clone(MessageV2(src)))
131}
132
133// Merge merges src into dst, which must be messages of the same type.
134//
135// Populated scalar fields in src are copied to dst, while populated
136// singular messages in src are merged into dst by recursively calling Merge.
137// The elements of every list field in src is appended to the corresponded
138// list fields in dst. The entries of every map field in src is copied into
139// the corresponding map field in dst, possibly replacing existing entries.
140// The unknown fields of src are appended to the unknown fields of dst.
141func Merge(dst, src Message) {
142 protoV2.Merge(MessageV2(dst), MessageV2(src))
143}
144
145// Equal reports whether two messages are equal.
146// If two messages marshal to the same bytes under deterministic serialization,
147// then Equal is guaranteed to report true.
148//
149// Two messages are equal if they are the same protobuf message type,
150// have the same set of populated known and extension field values,
151// and the same set of unknown fields values.
152//
153// Scalar values are compared with the equivalent of the == operator in Go,
154// except bytes values which are compared using bytes.Equal and
155// floating point values which specially treat NaNs as equal.
156// Message values are compared by recursively calling Equal.
157// Lists are equal if each element value is also equal.
158// Maps are equal if they have the same set of keys, where the pair of values
159// for each key is also equal.
160func Equal(x, y Message) bool {
161 return protoV2.Equal(MessageV2(x), MessageV2(y))
162}
163
164func isMessageSet(md protoreflect.MessageDescriptor) bool {
165 ms, ok := md.(interface{ IsMessageSet() bool })
166 return ok && ms.IsMessageSet()
167}