proto.go 5.9 KB

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