1 // Go support for Protocol Buffers - Google's data interchange format
3 // Copyright 2010 Google Inc. All rights reserved.
4 // http://code.google.com/p/goprotobuf/
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.
33 The proto package converts data structures to and from the
34 wire format of protocol buffers. It works in concert with the
35 Go source code generated for .proto files by the protocol compiler.
37 A summary of the properties of the protocol buffer interface
38 for a protocol buffer variable v:
40 - Names are turned from camel_case to CamelCase for export.
41 - There are no methods on v to set and get fields; just treat
42 them as structure fields.
43 - The zero value for a struct is its correct initialization state.
44 All desired fields must be set before marshaling.
45 - A Reset() method will restore a protobuf struct to its zero state.
46 - Non-repeated fields are pointers to the values; nil means unset.
47 That is, optional or required field int32 f becomes F *int32.
48 - Repeated fields are slices.
49 - Helper functions are available to simplify the getting and setting of fields:
50 foo.String = proto.String("hello") // set field
51 s := proto.GetString(foo.String) // get field
52 - Constants are defined to hold the default values of all fields that
53 have them. They have the form Default_StructName_FieldName.
54 - Enums are given type names and maps between names to values,
55 plus a helper function to create values. Enum values are prefixed
56 with the enum's type name. Enum types have a String method.
57 - Nested groups and enums have type names prefixed with the name of
58 the surrounding message type.
59 - Extensions are given descriptor names that start with E_,
60 followed by an underscore-delimited list of the nested messages
61 that contain it (if any) followed by the CamelCased name of the
62 extension field itself. HasExtension, ClearExtension, GetExtension
63 and SetExtension are functions for manipulating extensions.
64 - Marshal and Unmarshal are functions to encode and decode the wire format.
66 The simplest way to describe this is to see an example.
67 Given file test.proto, containing
74 required string label = 1;
75 optional int32 type = 2 [default=77];
76 repeated int64 reps = 3;
77 optional group OptionalGroup = 4 {
78 required string RequiredField = 5;
82 The resulting file, test.pb.go, is:
86 import "goprotobuf.googlecode.com/hg/proto"
92 var FOO_name = map[int32] string {
95 var FOO_value = map[string] int32 {
98 func NewFOO(x int32) *FOO {
102 func (x FOO) String() string {
103 return proto.EnumName(FOO_name, int32(x))
107 Label *string `protobuf:"bytes,1,req,name=label"`
108 Type *int32 `protobuf:"varint,2,opt,name=type,def=77"`
109 Reps []int64 `protobuf:"varint,3,rep,name=reps"`
110 Optionalgroup *Test_OptionalGroup `protobuf:"group,4,opt,name=optionalgroup"`
111 XXX_unrecognized []byte
113 func (this *Test) Reset() {
116 const Default_Test_Type int32 = 77
118 type Test_OptionalGroup struct {
119 RequiredField *string `protobuf:"bytes,5,req"`
120 XXX_unrecognized []byte
122 func (this *Test_OptionalGroup) Reset() {
123 *this = Test_OptionalGroup{}
127 proto.RegisterEnum("example.FOO", FOO_name, FOO_value)
130 To create and play with a Test object:
137 "goprotobuf.googlecode.com/hg/proto"
142 test := &example.Test{
143 Label: proto.String("hello"),
144 Type: proto.Int32(17),
145 Optionalgroup: &example.Test_OptionalGroup{
146 RequiredField: proto.String("good bye"),
149 data, err := proto.Marshal(test)
151 log.Fatal("marshaling error: ", err)
153 newTest := new(example.Test)
154 err = proto.Unmarshal(data, newTest)
156 log.Fatal("unmarshaling error: ", err)
158 // Now test and newTest contain the same data.
159 if proto.GetString(test.Label) != proto.GetString(newTest.Label) {
160 log.Fatalf("data mismatch %q != %q", proto.GetString(test.Label), proto.GetString(newTest.Label))
175 // Stats records allocation details about the protocol buffer encoders
176 // and decoders. Useful for tuning the library itself.
178 Emalloc uint64 // mallocs in encode
179 Dmalloc uint64 // mallocs in decode
180 Encode uint64 // number of encodes
181 Decode uint64 // number of decodes
182 Chit uint64 // number of cache hits
183 Cmiss uint64 // number of cache misses
188 // GetStats returns a copy of the global Stats structure.
189 func GetStats() Stats { return stats }
191 // A Buffer is a buffer manager for marshaling and unmarshaling
192 // protocol buffers. It may be reused between invocations to
193 // reduce memory usage. It is not necessary to use a Buffer;
194 // the global functions Marshal and Unmarshal create a
195 // temporary Buffer and are fine for most applications.
197 buf []byte // encode/decode byte stream
198 index int // write point
199 freelist [10][]byte // list of available buffers
200 nfreelist int // number of free buffers
201 ptr uintptr // scratch area for pointers
204 // NewBuffer allocates a new Buffer and initializes its internal data to
205 // the contents of the argument slice.
206 func NewBuffer(e []byte) *Buffer {
216 // Reset resets the Buffer, ready for marshaling a new protocol buffer.
217 func (p *Buffer) Reset() {
221 p.buf = p.buf[0:0] // for reading/writing
222 p.index = 0 // for reading
225 // SetBuf replaces the internal buffer with the slice,
226 // ready for unmarshaling the contents of the slice.
227 func (p *Buffer) SetBuf(s []byte) {
232 // Bytes returns the contents of the Buffer.
233 func (p *Buffer) Bytes() []byte { return p.buf }
235 // Allocate a buffer for the Buffer.
236 func (p *Buffer) bufalloc() []byte {
240 s := p.freelist[p.nfreelist]
244 s := make([]byte, 0, 16)
248 // Free (and remember in freelist) a byte buffer for the Buffer.
249 func (p *Buffer) buffree(s []byte) {
250 if p.nfreelist < len(p.freelist) {
252 p.freelist[p.nfreelist] = s
257 // Find the smallest.
260 for i, b := range p.freelist {
267 // Overwrite the smallest.
269 p.freelist[besti] = s
274 * Helper routines for simplifying the creation of optional fields of basic type.
277 // Bool is a helper routine that allocates a new bool value
278 // to store v and returns a pointer to it.
279 func Bool(v bool) *bool {
285 // Int32 is a helper routine that allocates a new int32 value
286 // to store v and returns a pointer to it.
287 func Int32(v int32) *int32 {
293 // Int is a helper routine that allocates a new int32 value
294 // to store v and returns a pointer to it, but unlike Int32
295 // its argument value is an int.
296 func Int(v int) *int32 {
302 // Int64 is a helper routine that allocates a new int64 value
303 // to store v and returns a pointer to it.
304 func Int64(v int64) *int64 {
310 // Float32 is a helper routine that allocates a new float32 value
311 // to store v and returns a pointer to it.
312 func Float32(v float32) *float32 {
318 // Float64 is a helper routine that allocates a new float64 value
319 // to store v and returns a pointer to it.
320 func Float64(v float64) *float64 {
326 // Uint32 is a helper routine that allocates a new uint32 value
327 // to store v and returns a pointer to it.
328 func Uint32(v uint32) *uint32 {
334 // Uint64 is a helper routine that allocates a new uint64 value
335 // to store v and returns a pointer to it.
336 func Uint64(v uint64) *uint64 {
342 // String is a helper routine that allocates a new string value
343 // to store v and returns a pointer to it.
344 func String(v string) *string {
351 * Helper routines for simplifying the fetching of optional fields of basic type.
352 * If the field is missing, they return the zero for the type.
355 // GetBool is a helper routine that returns an optional bool value.
356 func GetBool(p *bool) bool {
363 // GetInt32 is a helper routine that returns an optional int32 value.
364 func GetInt32(p *int32) int32 {
371 // GetInt64 is a helper routine that returns an optional int64 value.
372 func GetInt64(p *int64) int64 {
379 // GetFloat32 is a helper routine that returns an optional float32 value.
380 func GetFloat32(p *float32) float32 {
387 // GetFloat64 is a helper routine that returns an optional float64 value.
388 func GetFloat64(p *float64) float64 {
395 // GetUint32 is a helper routine that returns an optional uint32 value.
396 func GetUint32(p *uint32) uint32 {
403 // GetUint64 is a helper routine that returns an optional uint64 value.
404 func GetUint64(p *uint64) uint64 {
411 // GetString is a helper routine that returns an optional string value.
412 func GetString(p *string) string {
419 // EnumName is a helper function to simplify printing protocol buffer enums
420 // by name. Given an enum map and a value, it returns a useful string.
421 func EnumName(m map[int32]string, v int32) string {
426 return "unknown_enum_" + strconv.Itoa(int(v))
429 // DebugPrint dumps the encoded data in b in a debugging format with a header
430 // including the string s. Used in testing but made available for general debugging.
431 func (o *Buffer) DebugPrint(s string, b []byte) {
440 fmt.Printf("\n--- %s ---\n", s)
444 for i := 0; i < depth; i++ {
449 if index == len(o.buf) {
453 op, err := o.DecodeVarint()
455 fmt.Printf("%3d: fetching op err %v\n", index, err)
463 fmt.Printf("%3d: t=%3d unknown wire=%d\n",
470 r, err = o.DecodeRawBytes(false)
474 fmt.Printf("%3d: t=%3d bytes [%d]", index, tag, len(r))
476 for i := 0; i < len(r); i++ {
477 fmt.Printf(" %.2x", r[i])
480 for i := 0; i < 3; i++ {
481 fmt.Printf(" %.2x", r[i])
484 for i := len(r) - 3; i < len(r); i++ {
485 fmt.Printf(" %.2x", r[i])
491 u, err = o.DecodeFixed32()
493 fmt.Printf("%3d: t=%3d fix32 err %v\n", index, tag, err)
496 fmt.Printf("%3d: t=%3d fix32 %d\n", index, tag, u)
499 u, err = o.DecodeFixed64()
501 fmt.Printf("%3d: t=%3d fix64 err %v\n", index, tag, err)
504 fmt.Printf("%3d: t=%3d fix64 %d\n", index, tag, u)
508 u, err = o.DecodeVarint()
510 fmt.Printf("%3d: t=%3d varint err %v\n", index, tag, err)
513 fmt.Printf("%3d: t=%3d varint %d\n", index, tag, u)
517 fmt.Printf("%3d: t=%3d start err %v\n", index, tag, err)
520 fmt.Printf("%3d: t=%3d start\n", index, tag)
526 fmt.Printf("%3d: t=%3d end err %v\n", index, tag, err)
529 fmt.Printf("%3d: t=%3d end\n", index, tag)
534 fmt.Printf("%3d: start-end not balanced %d\n", o.index, depth)
542 // SetDefaults sets unset protocol buffer fields to their default values.
543 // It only modifies fields that are both unset and have defined defaults.
544 // It recursively sets default values in any non-nil sub-messages.
545 func SetDefaults(pb interface{}) {
546 v := reflect.ValueOf(pb)
547 if v.Kind() != reflect.Ptr || v.Elem().Kind() != reflect.Struct {
548 log.Printf("proto: hit non-pointer-to-struct %v", v)
550 setDefaults(v, true, false)
553 // v is a pointer to a struct.
554 func setDefaults(v reflect.Value, recur, zeros bool) {
558 dm, ok := defaults[v.Type()]
561 dm = buildDefaultMessage(v.Type())
563 defaults[v.Type()] = dm
567 for _, sf := range dm.scalars {
568 f := v.Field(sf.index)
574 if dv == nil && !zeros {
575 // no explicit default, and don't want to set zeros
578 fptr := f.Addr().Interface() // **T
579 // TODO: Consider batching the allocations we do here.
587 case reflect.Float32:
592 *(fptr.(**float32)) = f
593 case reflect.Float64:
598 *(fptr.(**float64)) = f
601 if ft := f.Type(); ft != int32PtrType {
603 f.Set(reflect.New(ft.Elem()))
605 f.Elem().SetInt(int64(dv.(int32)))
613 *(fptr.(**int32)) = i
620 *(fptr.(**int64)) = i
626 *(fptr.(**string)) = s
628 // exceptional case: []byte
632 b = make([]byte, len(db))
637 *(fptr.(*[]byte)) = b
643 *(fptr.(**uint32)) = u
649 *(fptr.(**uint64)) = u
651 log.Printf("proto: can't set default for field %v (sf.kind=%v)", f, sf.kind)
655 for _, ni := range dm.nested {
656 setDefaults(v.Field(ni), recur, zeros)
661 // defaults maps a protocol buffer struct type to a slice of the fields,
662 // with its scalar fields set to their proto-declared non-zero default values.
664 defaults = make(map[reflect.Type]defaultMessage)
666 int32PtrType = reflect.TypeOf((*int32)(nil))
669 // defaultMessage represents information about the default values of a message.
670 type defaultMessage struct {
671 scalars []scalarField
672 nested []int // struct field index of nested messages
675 type scalarField struct {
676 index int // struct field index
677 kind reflect.Kind // element type (the T in *T or []T)
678 value interface{} // the proto-declared default value, or nil
681 // t is a struct type.
682 func buildDefaultMessage(t reflect.Type) (dm defaultMessage) {
683 sprop := GetProperties(t)
684 for _, prop := range sprop.Prop {
685 fi := sprop.tags[prop.Tag]
686 ft := t.Field(fi).Type
689 if ft.Kind() == reflect.Ptr && ft.Elem().Kind() == reflect.Struct {
690 dm.nested = append(dm.nested, fi)
696 kind: ft.Elem().Kind(),
699 // scalar fields without defaults
700 if prop.Default == "" {
701 dm.scalars = append(dm.scalars, sf)
705 // a scalar field: either *T or []byte
706 switch ft.Elem().Kind() {
708 x, err := strconv.Atob(prop.Default)
710 log.Printf("proto: bad default bool %q: %v", prop.Default, err)
714 case reflect.Float32:
715 x, err := strconv.Atof32(prop.Default)
717 log.Printf("proto: bad default float32 %q: %v", prop.Default, err)
721 case reflect.Float64:
722 x, err := strconv.Atof64(prop.Default)
724 log.Printf("proto: bad default float64 %q: %v", prop.Default, err)
729 x, err := strconv.Atoi64(prop.Default)
731 log.Printf("proto: bad default int32 %q: %v", prop.Default, err)
736 x, err := strconv.Atoi64(prop.Default)
738 log.Printf("proto: bad default int64 %q: %v", prop.Default, err)
743 sf.value = prop.Default
745 // []byte (not *uint8)
746 sf.value = []byte(prop.Default)
748 x, err := strconv.Atoui64(prop.Default)
750 log.Printf("proto: bad default uint32 %q: %v", prop.Default, err)
755 x, err := strconv.Atoui64(prop.Default)
757 log.Printf("proto: bad default uint64 %q: %v", prop.Default, err)
762 log.Printf("proto: unhandled def kind %v", ft.Elem().Kind())
766 dm.scalars = append(dm.scalars, sf)