/* * Copyright (c) 2012-2014 Dave Collins * * Permission to use, copy, modify, and distribute this software for any * purpose with or without fee is hereby granted, provided that the above * copyright notice and this permission notice appear in all copies. * * THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES * WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF * MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR * ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES * WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN * ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. */ /* Package xdr implements the data representation portion of the External Data Representation (XDR) standard protocol as specified in RFC 4506 (obsoletes RFC 1832 and RFC 1014). The XDR RFC defines both a data specification language and a data representation standard. This package implements methods to encode and decode XDR data per the data representation standard with the exception of 128-bit quadruple-precision floating points. It does not currently implement parsing of the data specification language. In other words, the ability to automatically generate Go code by parsing an XDR data specification file (typically .x extension) is not supported. In practice, this limitation of the package is fairly minor since it is largely unnecessary due to the reflection capabilities of Go as described below. This package provides two approaches for encoding and decoding XDR data: 1) Marshal/Unmarshal functions which automatically map between XDR and Go types 2) Individual Encoder/Decoder objects to manually work with XDR primitives For the Marshal/Unmarshal functions, Go reflection capabilities are used to choose the type of the underlying XDR data based upon the Go type to encode or the target Go type to decode into. A description of how each type is mapped is provided below, however one important type worth reviewing is Go structs. In the case of structs, each exported field (first letter capitalized) is reflected and mapped in order. As a result, this means a Go struct with exported fields of the appropriate types listed in the expected order can be used to automatically encode / decode the XDR data thereby eliminating the need to write a lot of boilerplate code to encode/decode and error check each piece of XDR data as is typically required with C based XDR libraries. Go Type to XDR Type Mappings The following chart shows an overview of how Go types are mapped to XDR types for automatic marshalling and unmarshalling. The documentation for the Marshal and Unmarshal functions has specific details of how the mapping proceeds. Go Type <-> XDR Type -------------------- int8, int16, int32, int <-> XDR Integer uint8, uint16, uint32, uint <-> XDR Unsigned Integer int64 <-> XDR Hyper Integer uint64 <-> XDR Unsigned Hyper Integer bool <-> XDR Boolean float32 <-> XDR Floating-Point float64 <-> XDR Double-Precision Floating-Point string <-> XDR String byte <-> XDR Integer []byte <-> XDR Variable-Length Opaque Data [#]byte <-> XDR Fixed-Length Opaque Data [] <-> XDR Variable-Length Array [#] <-> XDR Fixed-Length Array struct <-> XDR Structure map <-> XDR Variable-Length Array of two-element XDR Structures time.Time <-> XDR String encoded with RFC3339 nanosecond precision Notes and Limitations: * Automatic marshalling and unmarshalling of variable and fixed-length arrays of uint8s require a special struct tag `xdropaque:"false"` since byte slices and byte arrays are assumed to be opaque data and byte is a Go alias for uint8 thus indistinguishable under reflection * Channel, complex, and function types cannot be encoded * Interfaces without a concrete value cannot be encoded * Cyclic data structures are not supported and will result in infinite loops * Strings are marshalled and unmarshalled with UTF-8 character encoding which differs from the XDR specification of ASCII, however UTF-8 is backwards compatible with ASCII so this should rarely cause issues Encoding To encode XDR data, use the Marshal function. func Marshal(w io.Writer, v interface{}) (int, error) For example, given the following code snippet: type ImageHeader struct { Signature [3]byte Version uint32 IsGrayscale bool NumSections uint32 } h := ImageHeader{[3]byte{0xAB, 0xCD, 0xEF}, 2, true, 10} var w bytes.Buffer bytesWritten, err := xdr.Marshal(&w, &h) // Error check elided The result, encodedData, will then contain the following XDR encoded byte sequence: 0xAB, 0xCD, 0xEF, 0x00, 0x00, 0x00, 0x00, 0x02, 0x00, 0x00, 0x00, 0x01, 0x00, 0x00, 0x00, 0x0A In addition, while the automatic marshalling discussed above will work for the vast majority of cases, an Encoder object is provided that can be used to manually encode XDR primitives for complex scenarios where automatic reflection-based encoding won't work. The included examples provide a sample of manual usage via an Encoder. Decoding To decode XDR data, use the Unmarshal function. func Unmarshal(r io.Reader, v interface{}) (int, error) For example, given the following code snippet: type ImageHeader struct { Signature [3]byte Version uint32 IsGrayscale bool NumSections uint32 } // Using output from the Encoding section above. encodedData := []byte{ 0xAB, 0xCD, 0xEF, 0x00, 0x00, 0x00, 0x00, 0x02, 0x00, 0x00, 0x00, 0x01, 0x00, 0x00, 0x00, 0x0A, } var h ImageHeader bytesRead, err := xdr.Unmarshal(bytes.NewReader(encodedData), &h) // Error check elided The struct instance, h, will then contain the following values: h.Signature = [3]byte{0xAB, 0xCD, 0xEF} h.Version = 2 h.IsGrayscale = true h.NumSections = 10 In addition, while the automatic unmarshalling discussed above will work for the vast majority of cases, a Decoder object is provided that can be used to manually decode XDR primitives for complex scenarios where automatic reflection-based decoding won't work. The included examples provide a sample of manual usage via a Decoder. Errors All errors are either of type UnmarshalError or MarshalError. Both provide human-readable output as well as an ErrorCode field which can be inspected by sophisticated callers if necessary. See the documentation of UnmarshalError, MarshalError, and ErrorCode for further details. */ package xdr