1 // 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. 13 package proto 14 15 import ( 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 22 const ( 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. 32 type 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. 37 type 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. 50 type 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. 54 func 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. 60 func 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. 66 func 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. 75 type 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. 87 type 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. 98 type 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. 107 type RequiredNotSetError struct { 108 err error 109 } 110 111 func (e *RequiredNotSetError) Error() string { 112 if e.err != nil { 113 return e.err.Error() 114 } 115 return "proto: required field not set" 116 } 117 func (e *RequiredNotSetError) RequiredNotSet() bool { 118 return true 119 } 120 121 func 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. 129 func 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. 141 func 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. 160 func Equal(x, y Message) bool { 161 return protoV2.Equal(MessageV2(x), MessageV2(y)) 162 } 163 164 func isMessageSet(md protoreflect.MessageDescriptor) bool { 165 ms, ok := md.(interface{ IsMessageSet() bool }) 166 return ok && ms.IsMessageSet() 167 } 168