1 // Go support for Protocol Buffers - Google's data interchange format
3 // Copyright 2010 The Go Authors. All rights reserved.
4 // https://github.com/golang/protobuf
6 // Redistribution and use in source and binary forms, with or without
7 // modification, are permitted provided that the following conditions are
10 // * Redistributions of source code must retain the above copyright
11 // notice, this list of conditions and the following disclaimer.
12 // * Redistributions in binary form must reproduce the above
13 // copyright notice, this list of conditions and the following disclaimer
14 // in the documentation and/or other materials provided with the
16 // * Neither the name of Google Inc. nor the names of its
17 // contributors may be used to endorse or promote products derived from
18 // this software without specific prior written permission.
20 // THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
21 // "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
22 // LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
23 // A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
24 // OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
25 // SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
26 // LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
27 // DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
28 // THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
29 // (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
30 // OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
35 * Types and routines for supporting protocol buffer extensions.
46 // ErrMissingExtension is the error returned by GetExtension if the named extension is not in the message.
47 var ErrMissingExtension = errors.New("proto: missing extension")
49 // ExtensionRange represents a range of message extensions for a protocol buffer.
50 // Used in code generated by the protocol compiler.
51 type ExtensionRange struct {
52 Start, End int32 // both inclusive
55 // extendableProto is an interface implemented by any protocol buffer generated by the current
56 // proto compiler that may be extended.
57 type extendableProto interface {
59 ExtensionRangeArray() []ExtensionRange
60 extensionsWrite() map[int32]Extension
61 extensionsRead() (map[int32]Extension, sync.Locker)
64 // extendableProtoV1 is an interface implemented by a protocol buffer generated by the previous
65 // version of the proto compiler that may be extended.
66 type extendableProtoV1 interface {
68 ExtensionRangeArray() []ExtensionRange
69 ExtensionMap() map[int32]Extension
72 // extensionAdapter is a wrapper around extendableProtoV1 that implements extendableProto.
73 type extensionAdapter struct {
77 func (e extensionAdapter) extensionsWrite() map[int32]Extension {
78 return e.ExtensionMap()
81 func (e extensionAdapter) extensionsRead() (map[int32]Extension, sync.Locker) {
82 return e.ExtensionMap(), notLocker{}
85 // notLocker is a sync.Locker whose Lock and Unlock methods are nops.
86 type notLocker struct{}
88 func (n notLocker) Lock() {}
89 func (n notLocker) Unlock() {}
91 // extendable returns the extendableProto interface for the given generated proto message.
92 // If the proto message has the old extension format, it returns a wrapper that implements
93 // the extendableProto interface.
94 func extendable(p interface{}) (extendableProto, bool) {
95 if ep, ok := p.(extendableProto); ok {
98 if ep, ok := p.(extendableProtoV1); ok {
99 return extensionAdapter{ep}, ok
104 // XXX_InternalExtensions is an internal representation of proto extensions.
106 // Each generated message struct type embeds an anonymous XXX_InternalExtensions field,
107 // thus gaining the unexported 'extensions' method, which can be called only from the proto package.
109 // The methods of XXX_InternalExtensions are not concurrency safe in general,
110 // but calls to logically read-only methods such as has and get may be executed concurrently.
111 type XXX_InternalExtensions struct {
112 // The struct must be indirect so that if a user inadvertently copies a
113 // generated message and its embedded XXX_InternalExtensions, they
114 // avoid the mayhem of a copied mutex.
116 // The mutex serializes all logically read-only operations to p.extensionMap.
117 // It is up to the client to ensure that write operations to p.extensionMap are
118 // mutually exclusive with other accesses.
121 extensionMap map[int32]Extension
125 // extensionsWrite returns the extension map, creating it on first use.
126 func (e *XXX_InternalExtensions) extensionsWrite() map[int32]Extension {
130 extensionMap map[int32]Extension
132 e.p.extensionMap = make(map[int32]Extension)
134 return e.p.extensionMap
137 // extensionsRead returns the extensions map for read-only use. It may be nil.
138 // The caller must hold the returned mutex's lock when accessing Elements within the map.
139 func (e *XXX_InternalExtensions) extensionsRead() (map[int32]Extension, sync.Locker) {
143 return e.p.extensionMap, &e.p.mu
146 var extendableProtoType = reflect.TypeOf((*extendableProto)(nil)).Elem()
147 var extendableProtoV1Type = reflect.TypeOf((*extendableProtoV1)(nil)).Elem()
149 // ExtensionDesc represents an extension specification.
150 // Used in generated code from the protocol compiler.
151 type ExtensionDesc struct {
152 ExtendedType Message // nil pointer to the type that is being extended
153 ExtensionType interface{} // nil pointer to the extension type
154 Field int32 // field number
155 Name string // fully-qualified name of extension, for text formatting
156 Tag string // protobuf tag style
157 Filename string // name of the file in which the extension is defined
160 func (ed *ExtensionDesc) repeated() bool {
161 t := reflect.TypeOf(ed.ExtensionType)
162 return t.Kind() == reflect.Slice && t.Elem().Kind() != reflect.Uint8
165 // Extension represents an extension in a message.
166 type Extension struct {
167 // When an extension is stored in a message using SetExtension
168 // only desc and value are set. When the message is marshaled
169 // enc will be set to the encoded form of the message.
171 // When a message is unmarshaled and contains extensions, each
172 // extension will have only enc set. When such an extension is
173 // accessed using GetExtension (or GetExtensions) desc and value
180 // SetRawExtension is for testing only.
181 func SetRawExtension(base Message, id int32, b []byte) {
182 epb, ok := extendable(base)
186 extmap := epb.extensionsWrite()
187 extmap[id] = Extension{enc: b}
190 // isExtensionField returns true iff the given field number is in an extension range.
191 func isExtensionField(pb extendableProto, field int32) bool {
192 for _, er := range pb.ExtensionRangeArray() {
193 if er.Start <= field && field <= er.End {
200 // checkExtensionTypes checks that the given extension is valid for pb.
201 func checkExtensionTypes(pb extendableProto, extension *ExtensionDesc) error {
202 var pbi interface{} = pb
203 // Check the extended type.
204 if ea, ok := pbi.(extensionAdapter); ok {
205 pbi = ea.extendableProtoV1
207 if a, b := reflect.TypeOf(pbi), reflect.TypeOf(extension.ExtendedType); a != b {
208 return errors.New("proto: bad extended type; " + b.String() + " does not extend " + a.String())
211 if !isExtensionField(pb, extension.Field) {
212 return errors.New("proto: bad extension number; not in declared ranges")
217 // extPropKey is sufficient to uniquely identify an extension.
218 type extPropKey struct {
223 var extProp = struct {
225 m map[extPropKey]*Properties
227 m: make(map[extPropKey]*Properties),
230 func extensionProperties(ed *ExtensionDesc) *Properties {
231 key := extPropKey{base: reflect.TypeOf(ed.ExtendedType), field: ed.Field}
234 if prop, ok := extProp.m[key]; ok {
241 defer extProp.Unlock()
243 if prop, ok := extProp.m[key]; ok {
247 prop := new(Properties)
248 prop.Init(reflect.TypeOf(ed.ExtensionType), "unknown_name", ed.Tag, nil)
249 extProp.m[key] = prop
253 // encode encodes any unmarshaled (unencoded) extensions in e.
254 func encodeExtensions(e *XXX_InternalExtensions) error {
255 m, mu := e.extensionsRead()
257 return nil // fast path
261 return encodeExtensionsMap(m)
264 // encode encodes any unmarshaled (unencoded) extensions in e.
265 func encodeExtensionsMap(m map[int32]Extension) error {
266 for k, e := range m {
267 if e.value == nil || e.desc == nil {
268 // Extension is only in its encoded form.
272 // We don't skip extensions that have an encoded form set,
273 // because the extension value may have been mutated after
274 // the last time this function was called.
276 et := reflect.TypeOf(e.desc.ExtensionType)
277 props := extensionProperties(e.desc)
280 // If e.value has type T, the encoder expects a *struct{ X T }.
281 // Pass a *T with a zero field and hope it all works out.
283 x.Elem().Set(reflect.ValueOf(e.value))
284 if err := props.enc(p, props, toStructPointer(x)); err != nil {
293 func extensionsSize(e *XXX_InternalExtensions) (n int) {
294 m, mu := e.extensionsRead()
300 return extensionsMapSize(m)
303 func extensionsMapSize(m map[int32]Extension) (n int) {
304 for _, e := range m {
305 if e.value == nil || e.desc == nil {
306 // Extension is only in its encoded form.
311 // We don't skip extensions that have an encoded form set,
312 // because the extension value may have been mutated after
313 // the last time this function was called.
315 et := reflect.TypeOf(e.desc.ExtensionType)
316 props := extensionProperties(e.desc)
318 // If e.value has type T, the encoder expects a *struct{ X T }.
319 // Pass a *T with a zero field and hope it all works out.
321 x.Elem().Set(reflect.ValueOf(e.value))
322 n += props.size(props, toStructPointer(x))
327 // HasExtension returns whether the given extension is present in pb.
328 func HasExtension(pb Message, extension *ExtensionDesc) bool {
329 // TODO: Check types, field numbers, etc.?
330 epb, ok := extendable(pb)
334 extmap, mu := epb.extensionsRead()
339 _, ok = extmap[extension.Field]
344 // ClearExtension removes the given extension from pb.
345 func ClearExtension(pb Message, extension *ExtensionDesc) {
346 epb, ok := extendable(pb)
350 // TODO: Check types, field numbers, etc.?
351 extmap := epb.extensionsWrite()
352 delete(extmap, extension.Field)
355 // GetExtension parses and returns the given extension of pb.
356 // If the extension is not present and has no default value it returns ErrMissingExtension.
357 func GetExtension(pb Message, extension *ExtensionDesc) (interface{}, error) {
358 epb, ok := extendable(pb)
360 return nil, errors.New("proto: not an extendable proto")
363 if err := checkExtensionTypes(epb, extension); err != nil {
367 emap, mu := epb.extensionsRead()
369 return defaultExtensionValue(extension)
373 e, ok := emap[extension.Field]
375 // defaultExtensionValue returns the default value or
376 // ErrMissingExtension if there is no default.
377 return defaultExtensionValue(extension)
381 // Already decoded. Check the descriptor, though.
382 if e.desc != extension {
383 // This shouldn't happen. If it does, it means that
384 // GetExtension was called twice with two different
385 // descriptors with the same field number.
386 return nil, errors.New("proto: descriptor conflict")
391 v, err := decodeExtension(e.enc, extension)
396 // Remember the decoded version and drop the encoded version.
397 // That way it is safe to mutate what we return.
401 emap[extension.Field] = e
405 // defaultExtensionValue returns the default value for extension.
406 // If no default for an extension is defined ErrMissingExtension is returned.
407 func defaultExtensionValue(extension *ExtensionDesc) (interface{}, error) {
408 t := reflect.TypeOf(extension.ExtensionType)
409 props := extensionProperties(extension)
411 sf, _, err := fieldDefault(t, props)
416 if sf == nil || sf.value == nil {
417 // There is no default value.
418 return nil, ErrMissingExtension
421 if t.Kind() != reflect.Ptr {
422 // We do not need to return a Ptr, we can directly return sf.value.
426 // We need to return an interface{} that is a pointer to sf.value.
427 value := reflect.New(t).Elem()
428 value.Set(reflect.New(value.Type().Elem()))
429 if sf.kind == reflect.Int32 {
430 // We may have an int32 or an enum, but the underlying data is int32.
431 // Since we can't set an int32 into a non int32 reflect.value directly
432 // set it as a int32.
433 value.Elem().SetInt(int64(sf.value.(int32)))
435 value.Elem().Set(reflect.ValueOf(sf.value))
437 return value.Interface(), nil
440 // decodeExtension decodes an extension encoded in b.
441 func decodeExtension(b []byte, extension *ExtensionDesc) (interface{}, error) {
444 t := reflect.TypeOf(extension.ExtensionType)
446 props := extensionProperties(extension)
448 // t is a pointer to a struct, pointer to basic type or a slice.
449 // Allocate a "field" to store the pointer/slice itself; the
450 // pointer/slice will be stored here. We pass
451 // the address of this field to props.dec.
452 // This passes a zero field and a *t and lets props.dec
453 // interpret it as a *struct{ x t }.
454 value := reflect.New(t).Elem()
457 // Discard wire type and field number varint. It isn't needed.
458 if _, err := o.DecodeVarint(); err != nil {
462 if err := props.dec(o, props, toStructPointer(value.Addr())); err != nil {
466 if o.index >= len(o.buf) {
470 return value.Interface(), nil
473 // GetExtensions returns a slice of the extensions present in pb that are also listed in es.
474 // The returned slice has the same length as es; missing extensions will appear as nil elements.
475 func GetExtensions(pb Message, es []*ExtensionDesc) (extensions []interface{}, err error) {
476 epb, ok := extendable(pb)
478 return nil, errors.New("proto: not an extendable proto")
480 extensions = make([]interface{}, len(es))
481 for i, e := range es {
482 extensions[i], err = GetExtension(epb, e)
483 if err == ErrMissingExtension {
493 // ExtensionDescs returns a new slice containing pb's extension descriptors, in undefined order.
494 // For non-registered extensions, ExtensionDescs returns an incomplete descriptor containing
495 // just the Field field, which defines the extension's field number.
496 func ExtensionDescs(pb Message) ([]*ExtensionDesc, error) {
497 epb, ok := extendable(pb)
499 return nil, fmt.Errorf("proto: %T is not an extendable proto.Message", pb)
501 registeredExtensions := RegisteredExtensions(pb)
503 emap, mu := epb.extensionsRead()
509 extensions := make([]*ExtensionDesc, 0, len(emap))
510 for extid, e := range emap {
513 desc = registeredExtensions[extid]
515 desc = &ExtensionDesc{Field: extid}
519 extensions = append(extensions, desc)
521 return extensions, nil
524 // SetExtension sets the specified extension of pb to the specified value.
525 func SetExtension(pb Message, extension *ExtensionDesc, value interface{}) error {
526 epb, ok := extendable(pb)
528 return errors.New("proto: not an extendable proto")
530 if err := checkExtensionTypes(epb, extension); err != nil {
533 typ := reflect.TypeOf(extension.ExtensionType)
534 if typ != reflect.TypeOf(value) {
535 return errors.New("proto: bad extension value type")
537 // nil extension values need to be caught early, because the
538 // encoder can't distinguish an ErrNil due to a nil extension
539 // from an ErrNil due to a missing field. Extensions are
540 // always optional, so the encoder would just swallow the error
541 // and drop all the extensions from the encoded message.
542 if reflect.ValueOf(value).IsNil() {
543 return fmt.Errorf("proto: SetExtension called with nil value of type %T", value)
546 extmap := epb.extensionsWrite()
547 extmap[extension.Field] = Extension{desc: extension, value: value}
551 // ClearAllExtensions clears all extensions from pb.
552 func ClearAllExtensions(pb Message) {
553 epb, ok := extendable(pb)
557 m := epb.extensionsWrite()
563 // A global registry of extensions.
564 // The generated code will register the generated descriptors by calling RegisterExtension.
566 var extensionMaps = make(map[reflect.Type]map[int32]*ExtensionDesc)
568 // RegisterExtension is called from the generated code.
569 func RegisterExtension(desc *ExtensionDesc) {
570 st := reflect.TypeOf(desc.ExtendedType).Elem()
571 m := extensionMaps[st]
573 m = make(map[int32]*ExtensionDesc)
574 extensionMaps[st] = m
576 if _, ok := m[desc.Field]; ok {
577 panic("proto: duplicate extension registered: " + st.String() + " " + strconv.Itoa(int(desc.Field)))
582 // RegisteredExtensions returns a map of the registered extensions of a
583 // protocol buffer struct, indexed by the extension number.
584 // The argument pb should be a nil pointer to the struct type.
585 func RegisteredExtensions(pb Message) map[int32]*ExtensionDesc {
586 return extensionMaps[reflect.TypeOf(pb).Elem()]