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 protoiface contains types referenced or implemented by messages.
6//
7// WARNING: This package should only be imported by message implementations.
8// The functionality found in this package should be accessed through
9// higher-level abstractions provided by the proto package.
10package protoiface
11
12import (
13	"google.golang.org/protobuf/internal/pragma"
14	"google.golang.org/protobuf/reflect/protoreflect"
15)
16
17// Methods is a set of optional fast-path implementations of various operations.
18type Methods = struct {
19	pragma.NoUnkeyedLiterals
20
21	// Flags indicate support for optional features.
22	Flags SupportFlags
23
24	// Size returns the size in bytes of the wire-format encoding of a message.
25	// Marshal must be provided if a custom Size is provided.
26	Size func(SizeInput) SizeOutput
27
28	// Marshal formats a message in the wire-format encoding to the provided buffer.
29	// Size should be provided if a custom Marshal is provided.
30	// It must not return an error for a partial message.
31	Marshal func(MarshalInput) (MarshalOutput, error)
32
33	// Unmarshal parses the wire-format encoding and merges the result into a message.
34	// It must not reset the target message or return an error for a partial message.
35	Unmarshal func(UnmarshalInput) (UnmarshalOutput, error)
36
37	// Merge merges the contents of a source message into a destination message.
38	Merge func(MergeInput) MergeOutput
39
40	// CheckInitialized returns an error if any required fields in the message are not set.
41	CheckInitialized func(CheckInitializedInput) (CheckInitializedOutput, error)
42}
43
44// SupportFlags indicate support for optional features.
45type SupportFlags = uint64
46
47const (
48	// SupportMarshalDeterministic reports whether MarshalOptions.Deterministic is supported.
49	SupportMarshalDeterministic SupportFlags = 1 << iota
50
51	// SupportUnmarshalDiscardUnknown reports whether UnmarshalOptions.DiscardUnknown is supported.
52	SupportUnmarshalDiscardUnknown
53)
54
55// SizeInput is input to the Size method.
56type SizeInput = struct {
57	pragma.NoUnkeyedLiterals
58
59	Message protoreflect.Message
60	Flags   MarshalInputFlags
61}
62
63// SizeOutput is output from the Size method.
64type SizeOutput = struct {
65	pragma.NoUnkeyedLiterals
66
67	Size int
68}
69
70// MarshalInput is input to the Marshal method.
71type MarshalInput = struct {
72	pragma.NoUnkeyedLiterals
73
74	Message protoreflect.Message
75	Buf     []byte // output is appended to this buffer
76	Flags   MarshalInputFlags
77}
78
79// MarshalOutput is output from the Marshal method.
80type MarshalOutput = struct {
81	pragma.NoUnkeyedLiterals
82
83	Buf []byte // contains marshaled message
84}
85
86// MarshalInputFlags configure the marshaler.
87// Most flags correspond to fields in proto.MarshalOptions.
88type MarshalInputFlags = uint8
89
90const (
91	MarshalDeterministic MarshalInputFlags = 1 << iota
92	MarshalUseCachedSize
93)
94
95// UnmarshalInput is input to the Unmarshal method.
96type UnmarshalInput = struct {
97	pragma.NoUnkeyedLiterals
98
99	Message  protoreflect.Message
100	Buf      []byte // input buffer
101	Flags    UnmarshalInputFlags
102	Resolver interface {
103		FindExtensionByName(field protoreflect.FullName) (protoreflect.ExtensionType, error)
104		FindExtensionByNumber(message protoreflect.FullName, field protoreflect.FieldNumber) (protoreflect.ExtensionType, error)
105	}
106}
107
108// UnmarshalOutput is output from the Unmarshal method.
109type UnmarshalOutput = struct {
110	pragma.NoUnkeyedLiterals
111
112	Flags UnmarshalOutputFlags
113}
114
115// UnmarshalInputFlags configure the unmarshaler.
116// Most flags correspond to fields in proto.UnmarshalOptions.
117type UnmarshalInputFlags = uint8
118
119const (
120	UnmarshalDiscardUnknown UnmarshalInputFlags = 1 << iota
121)
122
123// UnmarshalOutputFlags are output from the Unmarshal method.
124type UnmarshalOutputFlags = uint8
125
126const (
127	// UnmarshalInitialized may be set on return if all required fields are known to be set.
128	// If unset, then it does not necessarily indicate that the message is uninitialized,
129	// only that its status could not be confirmed.
130	UnmarshalInitialized UnmarshalOutputFlags = 1 << iota
131)
132
133// MergeInput is input to the Merge method.
134type MergeInput = struct {
135	pragma.NoUnkeyedLiterals
136
137	Source      protoreflect.Message
138	Destination protoreflect.Message
139}
140
141// MergeOutput is output from the Merge method.
142type MergeOutput = struct {
143	pragma.NoUnkeyedLiterals
144
145	Flags MergeOutputFlags
146}
147
148// MergeOutputFlags are output from the Merge method.
149type MergeOutputFlags = uint8
150
151const (
152	// MergeComplete reports whether the merge was performed.
153	// If unset, the merger must have made no changes to the destination.
154	MergeComplete MergeOutputFlags = 1 << iota
155)
156
157// CheckInitializedInput is input to the CheckInitialized method.
158type CheckInitializedInput = struct {
159	pragma.NoUnkeyedLiterals
160
161	Message protoreflect.Message
162}
163
164// CheckInitializedOutput is output from the CheckInitialized method.
165type CheckInitializedOutput = struct {
166	pragma.NoUnkeyedLiterals
167}
168