xdr

Documentation

Overview

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
[]<type> <-> XDR Variable-Length Array
[#]<type> <-> 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.

Index

• func Marshal(w io.Writer, v interface{}) (int, error)
• func Unmarshal(r io.Reader, v interface{}) (int, error)
• type Decoder
  • func NewDecoder(r io.Reader) *Decoder
  • func (d *Decoder) Decode(v interface{}) (int, error)
  • func (d *Decoder) DecodeBool() (bool, int, error)
  • func (d *Decoder) DecodeDouble() (float64, int, error)
  • func (d *Decoder) DecodeEnum(validEnums map[int32]bool) (int32, int, error)
  • func (d *Decoder) DecodeFixedOpaque(size int32) ([]byte, int, error)
  • func (d *Decoder) DecodeFloat() (float32, int, error)
  • func (d *Decoder) DecodeHyper() (int64, int, error)
  • func (d *Decoder) DecodeInt() (int32, int, error)
  • func (d *Decoder) DecodeOpaque(maxSize int) ([]byte, int, error)
  • func (d *Decoder) DecodeString(maxSize int) (string, int, error)
  • func (d *Decoder) DecodeUhyper() (uint64, int, error)
  • func (d *Decoder) DecodeUint() (uint32, int, error)
• type Encoder
  • func NewEncoder(w io.Writer) *Encoder
  • func (enc *Encoder) Encode(v interface{}) (int, error)
  • func (enc *Encoder) EncodeBool(v bool) (int, error)
  • func (enc *Encoder) EncodeDouble(v float64) (int, error)
  • func (enc *Encoder) EncodeEnum(v int32, validEnums map[int32]bool) (int, error)
  • func (enc *Encoder) EncodeFixedOpaque(v []byte) (int, error)
  • func (enc *Encoder) EncodeFloat(v float32) (int, error)
  • func (enc *Encoder) EncodeHyper(v int64) (int, error)
  • func (enc *Encoder) EncodeInt(v int32) (int, error)
  • func (enc *Encoder) EncodeOpaque(v []byte) (int, error)
  • func (enc *Encoder) EncodeString(v string) (int, error)
  • func (enc *Encoder) EncodeUhyper(v uint64) (int, error)
  • func (enc *Encoder) EncodeUint(v uint32) (int, error)
• type Enum
• type ErrorCode
  • func (e ErrorCode) String() string
• type MarshalError
  • func (e *MarshalError) Error() string
• type Sized
• type Union
• type UnmarshalError
  • func (e *UnmarshalError) Error() string

Examples

• Marshal
• NewDecoder
• NewEncoder
• Unmarshal

Functions

func Marshal

func Marshal(w io.Writer, v interface{}) (int, error)

Marshal writes the XDR encoding of v to writer w and returns the number of bytes written. It traverses v recursively and automatically indirects pointers through arbitrary depth to encode the actual value pointed to.

Marshal uses reflection to determine the type of the concrete value contained by v and performs a mapping of Go types to the underlying XDR types as follows:

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
[]<type> -> XDR Variable-Length Array
[#]<type> -> 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 of variable and fixed-length arrays of uint8s requires 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 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

If any issues are encountered during the marshalling process, a MarshalError is returned with a human readable description as well as an ErrorCode value for further inspection from sophisticated callers. Some potential issues are unsupported Go types, attempting to encode more opaque data than can be represented by a single opaque XDR entry, and exceeding max slice limitations.

Example

This example demonstrates how to use Marshal to automatically XDR encode data using reflection.

// Hypothetical image header format.
type ImageHeader struct {
	Signature   [3]byte
	Version     uint32
	IsGrayscale bool
	NumSections uint32
}

// Sample image header data.
h := ImageHeader{[3]byte{0xAB, 0xCD, 0xEF}, 2, true, 10}

// Use marshal to automatically determine the appropriate underlying XDR
// types and encode.
var w bytes.Buffer
bytesWritten, err := xdr.Marshal(&w, &h)
if err != nil {
	fmt.Println(err)
	return
}

fmt.Println("bytes written:", bytesWritten)
fmt.Println("encoded data:", w.Bytes())

Output:

bytes written: 16
encoded data: [171 205 239 0 0 0 0 2 0 0 0 1 0 0 0 10]

func Unmarshal

func Unmarshal(r io.Reader, v interface{}) (int, error)

Unmarshal parses XDR-encoded data into the value pointed to by v reading from reader r and returning the total number of bytes read. An addressable pointer must be provided since Unmarshal needs to both store the result of the decode as well as obtain target type information. Unmarhsal traverses v recursively and automatically indirects pointers through arbitrary depth, allocating them as necessary, to decode the data into the underlying value pointed to.

Unmarshal uses reflection to determine the type of the concrete value contained by v and performs a mapping of underlying XDR types to Go types as follows:

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
[]<type> <- XDR Variable-Length Array
[#]<type> <- 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 unmarshalling of variable and fixed-length arrays of uint8s requires 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
• Cyclic data structures are not supported and will result in infinite loops

If any issues are encountered during the unmarshalling process, an UnmarshalError is returned with a human readable description as well as an ErrorCode value for further inspection from sophisticated callers. Some potential issues are unsupported Go types, attempting to decode a value which is too large to fit into a specified Go type, and exceeding max slice limitations.

Example

This example demonstrates how to use Unmarshal to decode XDR encoded data from a byte slice into a struct.

// Hypothetical image header format.
type ImageHeader struct {
	Signature   [3]byte
	Version     uint32
	IsGrayscale bool
	NumSections uint32
}

// XDR encoded data described by the above structure.  Typically this
// would be read from a file or across the network, but use a manual
// byte array here as an example.
encodedData := []byte{
	0xAB, 0xCD, 0xEF, 0x00, // Signature
	0x00, 0x00, 0x00, 0x02, // Version
	0x00, 0x00, 0x00, 0x01, // IsGrayscale
	0x00, 0x00, 0x00, 0x0A, // NumSections
}

// Declare a variable to provide Unmarshal with a concrete type and
// instance to decode into.
var h ImageHeader
bytesRead, err := xdr.Unmarshal(bytes.NewReader(encodedData), &h)
if err != nil {
	fmt.Println(err)
	return
}

fmt.Println("bytes read:", bytesRead)
fmt.Printf("h: %+v", h)

Output:

bytes read: 16
h: {Signature:[171 205 239] Version:2 IsGrayscale:true NumSections:10}

Types

type Decoder

type Decoder struct {
	// contains filtered or unexported fields
}

A Decoder wraps an io.Reader that is expected to provide an XDR-encoded byte stream and provides several exposed methods to manually decode various XDR primitives without relying on reflection. The NewDecoder function can be used to get a new Decoder directly.

Typically, Unmarshal should be used instead of manual decoding. A Decoder is exposed so it is possible to perform manual decoding should it be necessary in complex scenarios where automatic reflection-based decoding won't work.

func NewDecoder

func NewDecoder(r io.Reader) *Decoder

NewDecoder returns a Decoder that can be used to manually decode XDR data from a provided reader. Typically, Unmarshal should be used instead of manually creating a Decoder.

Example

This example demonstrates how to manually decode XDR encoded data from a reader. Compare this example with the Unmarshal example which performs the same task automatically by utilizing a struct type definition and reflection.

// XDR encoded data for a hypothetical ImageHeader struct as follows:
// type ImageHeader struct {
// 		Signature	[3]byte
// 		Version		uint32
// 		IsGrayscale	bool
// 		NumSections	uint32
// }
encodedData := []byte{
	0xAB, 0xCD, 0xEF, 0x00, // Signature
	0x00, 0x00, 0x00, 0x02, // Version
	0x00, 0x00, 0x00, 0x01, // IsGrayscale
	0x00, 0x00, 0x00, 0x0A, // NumSections
}

// Get a new decoder for manual decoding.
dec := xdr.NewDecoder(bytes.NewReader(encodedData))

signature, _, err := dec.DecodeFixedOpaque(3)
if err != nil {
	fmt.Println(err)
	return
}

version, _, err := dec.DecodeUint()
if err != nil {
	fmt.Println(err)
	return
}

isGrayscale, _, err := dec.DecodeBool()
if err != nil {
	fmt.Println(err)
	return
}

numSections, _, err := dec.DecodeUint()
if err != nil {
	fmt.Println(err)
	return
}

fmt.Println("signature:", signature)
fmt.Println("version:", version)
fmt.Println("isGrayscale:", isGrayscale)
fmt.Println("numSections:", numSections)

Output:

signature: [171 205 239]
version: 2
isGrayscale: true
numSections: 10

func (*Decoder) Decode

func (d *Decoder) Decode(v interface{}) (int, error)

Decode operates identically to the Unmarshal function with the exception of using the reader associated with the Decoder as the source of XDR-encoded data instead of a user-supplied reader. See the Unmarhsal documentation for specifics.

func (*Decoder) DecodeBool

func (d *Decoder) DecodeBool() (bool, int, error)

DecodeBool treats the next 4 bytes as an XDR encoded boolean value and returns the result as a bool along with the number of bytes actually read.

An UnmarshalError is returned if there are insufficient bytes remaining or the parsed value is not a 0 or 1.

Reference:

RFC Section 4.4 - Boolean
Represented as an XDR encoded enumeration where 0 is false and 1 is true

func (*Decoder) DecodeDouble

func (d *Decoder) DecodeDouble() (float64, int, error)

DecodeDouble treats the next 8 bytes as an XDR encoded double-precision floating point and returns the result as a float64 along with the number of bytes actually read.

An UnmarshalError is returned if there are insufficient bytes remaining.

Reference:

RFC Section 4.7 -  Double-Precision Floating Point
64-bit double-precision IEEE 754 floating point

func (*Decoder) DecodeEnum

func (d *Decoder) DecodeEnum(validEnums map[int32]bool) (int32, int, error)

DecodeEnum treats the next 4 bytes as an XDR encoded enumeration value and returns the result as an int32 after verifying that the value is in the provided map of valid values. It also returns the number of bytes actually read.

An UnmarshalError is returned if there are insufficient bytes remaining or the parsed enumeration value is not one of the provided valid values.

Reference:

RFC Section 4.3 - Enumeration
Represented as an XDR encoded signed integer

func (*Decoder) DecodeFixedOpaque

func (d *Decoder) DecodeFixedOpaque(size int32) ([]byte, int, error)

DecodeFixedOpaque treats the next 'size' bytes as XDR encoded opaque data and returns the result as a byte slice along with the number of bytes actually read.

An UnmarshalError is returned if there are insufficient bytes remaining to satisfy the passed size, including the necessary padding to make it a multiple of 4.

Reference:

RFC Section 4.9 - Fixed-Length Opaque Data
Fixed-length uninterpreted data zero-padded to a multiple of four

func (*Decoder) DecodeFloat

func (d *Decoder) DecodeFloat() (float32, int, error)

DecodeFloat treats the next 4 bytes as an XDR encoded floating point and returns the result as a float32 along with the number of bytes actually read.

An UnmarshalError is returned if there are insufficient bytes remaining.

Reference:

RFC Section 4.6 - Floating Point
32-bit single-precision IEEE 754 floating point

func (*Decoder) DecodeHyper

func (d *Decoder) DecodeHyper() (int64, int, error)

DecodeHyper treats the next 8 bytes as an XDR encoded hyper value and returns the result as an int64 along with the number of bytes actually read.

An UnmarshalError is returned if there are insufficient bytes remaining.

Reference:

RFC Section 4.5 - Hyper Integer
64-bit big-endian signed integer in range [-9223372036854775808, 9223372036854775807]

func (*Decoder) DecodeInt

func (d *Decoder) DecodeInt() (int32, int, error)

DecodeInt treats the next 4 bytes as an XDR encoded integer and returns the result as an int32 along with the number of bytes actually read.

An UnmarshalError is returned if there are insufficient bytes remaining.

Reference:

RFC Section 4.1 - Integer
32-bit big-endian signed integer in range [-2147483648, 2147483647]

func (*Decoder) DecodeOpaque

func (d *Decoder) DecodeOpaque(maxSize int) ([]byte, int, error)

DecodeOpaque treats the next bytes as variable length XDR encoded opaque data and returns the result as a byte slice along with the number of bytes actually read.

An UnmarshalError is returned if there are insufficient bytes remaining or the opaque data is larger than the max length of a Go slice.

Reference:

RFC Section 4.10 - Variable-Length Opaque Data
Unsigned integer length followed by fixed opaque data of that length

func (*Decoder) DecodeString

func (d *Decoder) DecodeString(maxSize int) (string, int, error)

DecodeString treats the next bytes as a variable length XDR encoded string and returns the result as a string along with the number of bytes actually read. Character encoding is assumed to be UTF-8 and therefore ASCII compatible. If the underlying character encoding is not compatibile with this assumption, the data can instead be read as variable-length opaque data (DecodeOpaque) and manually converted as needed.

An UnmarshalError is returned if there are insufficient bytes remaining or the string data is larger than the max length of a Go slice.

Reference:

RFC Section 4.11 - String
Unsigned integer length followed by bytes zero-padded to a multiple of
four

func (*Decoder) DecodeUhyper

func (d *Decoder) DecodeUhyper() (uint64, int, error)

DecodeUhyper treats the next 8 bytes as an XDR encoded unsigned hyper value and returns the result as a uint64 along with the number of bytes actually read.

An UnmarshalError is returned if there are insufficient bytes remaining.

Reference:

RFC Section 4.5 - Unsigned Hyper Integer
64-bit big-endian unsigned integer in range [0, 18446744073709551615]

func (*Decoder) DecodeUint

func (d *Decoder) DecodeUint() (uint32, int, error)

DecodeUint treats the next 4 bytes as an XDR encoded unsigned integer and returns the result as a uint32 along with the number of bytes actually read.

An UnmarshalError is returned if there are insufficient bytes remaining.

Reference:

RFC Section 4.2 - Unsigned Integer
32-bit big-endian unsigned integer in range [0, 4294967295]

type Encoder

type Encoder struct {
	// contains filtered or unexported fields
}

An Encoder wraps an io.Writer that will receive the XDR encoded byte stream. See NewEncoder.

func NewEncoder

func NewEncoder(w io.Writer) *Encoder

NewEncoder returns an object that can be used to manually choose fields to XDR encode to the passed writer w. Typically, Marshal should be used instead of manually creating an Encoder. An Encoder, along with several of its methods to encode XDR primitives, is exposed so it is possible to perform manual encoding of data without relying on reflection should it be necessary in complex scenarios where automatic reflection-based encoding won't work.

Example

This example demonstrates how to manually encode XDR data from Go variables. Compare this example with the Marshal example which performs the same task automatically by utilizing a struct type definition and reflection.

// Data for a hypothetical ImageHeader struct as follows:
// type ImageHeader struct {
// 		Signature	[3]byte
//		Version		uint32
//		IsGrayscale	bool
//		NumSections	uint32
// }
signature := []byte{0xAB, 0xCD, 0xEF}
version := uint32(2)
isGrayscale := true
numSections := uint32(10)

// Get a new encoder for manual encoding.
var w bytes.Buffer
enc := xdr.NewEncoder(&w)

_, err := enc.EncodeFixedOpaque(signature)
if err != nil {
	fmt.Println(err)
	return
}

_, err = enc.EncodeUint(version)
if err != nil {
	fmt.Println(err)
	return
}

_, err = enc.EncodeBool(isGrayscale)
if err != nil {
	fmt.Println(err)
	return
}

_, err = enc.EncodeUint(numSections)
if err != nil {
	fmt.Println(err)
	return
}

fmt.Println("encoded data:", w.Bytes())

Output:

encoded data: [171 205 239 0 0 0 0 2 0 0 0 1 0 0 0 10]

func (*Encoder) Encode

func (enc *Encoder) Encode(v interface{}) (int, error)

Encode operates identically to the Marshal function with the exception of using the writer associated with the Encoder for the destination of the XDR-encoded data instead of a user-supplied writer. See the Marshal documentation for specifics.

func (*Encoder) EncodeBool

func (enc *Encoder) EncodeBool(v bool) (int, error)

EncodeBool writes the XDR encoded representation of the passed boolean to the encapsulated writer and returns the number of bytes written.

A MarshalError with an error code of ErrIO is returned if writing the data fails.

Reference:

RFC Section 4.4 - Boolean
Represented as an XDR encoded enumeration where 0 is false and 1 is true

func (*Encoder) EncodeDouble

func (enc *Encoder) EncodeDouble(v float64) (int, error)

EncodeDouble writes the XDR encoded representation of the passed 64-bit (double-precision) floating point to the encapsulated writer and returns the number of bytes written.

A MarshalError with an error code of ErrIO is returned if writing the data fails.

Reference:

RFC Section 4.7 -  Double-Precision Floating Point
64-bit double-precision IEEE 754 floating point

func (*Encoder) EncodeEnum

func (enc *Encoder) EncodeEnum(v int32, validEnums map[int32]bool) (int, error)

EncodeEnum treats the passed 32-bit signed integer as an enumeration value and, if it is in the list of passed valid enumeration values, writes the XDR encoded representation of it to the encapsulated writer. It returns the number of bytes written.

A MarshalError is returned if the enumeration value is not one of the provided valid values or if writing the data fails.

Reference:

RFC Section 4.3 - Enumeration
Represented as an XDR encoded signed integer

func (*Encoder) EncodeFixedOpaque

func (enc *Encoder) EncodeFixedOpaque(v []byte) (int, error)

EncodeFixedOpaque treats the passed byte slice as opaque data of a fixed size and writes the XDR encoded representation of it to the encapsulated writer. It returns the number of bytes written.

A MarshalError with an error code of ErrIO is returned if writing the data fails.

Reference:

RFC Section 4.9 - Fixed-Length Opaque Data
Fixed-length uninterpreted data zero-padded to a multiple of four

func (*Encoder) EncodeFloat

func (enc *Encoder) EncodeFloat(v float32) (int, error)

EncodeFloat writes the XDR encoded representation of the passed 32-bit (single-precision) floating point to the encapsulated writer and returns the number of bytes written.

A MarshalError with an error code of ErrIO is returned if writing the data fails.

Reference:

RFC Section 4.6 - Floating Point
32-bit single-precision IEEE 754 floating point

func (*Encoder) EncodeHyper

func (enc *Encoder) EncodeHyper(v int64) (int, error)

EncodeHyper writes the XDR encoded representation of the passed 64-bit signed integer to the encapsulated writer and returns the number of bytes written.

A MarshalError with an error code of ErrIO is returned if writing the data fails.

Reference:

RFC Section 4.5 - Hyper Integer
64-bit big-endian signed integer in range [-9223372036854775808, 9223372036854775807]

func (*Encoder) EncodeInt

func (enc *Encoder) EncodeInt(v int32) (int, error)

EncodeInt writes the XDR encoded representation of the passed 32-bit signed integer to the encapsulated writer and returns the number of bytes written.

A MarshalError with an error code of ErrIO is returned if writing the data fails.

Reference:

RFC Section 4.1 - Integer
32-bit big-endian signed integer in range [-2147483648, 2147483647]

func (*Encoder) EncodeOpaque

func (enc *Encoder) EncodeOpaque(v []byte) (int, error)

EncodeOpaque treats the passed byte slice as opaque data of a variable size and writes the XDR encoded representation of it to the encapsulated writer. It returns the number of bytes written.

A MarshalError with an error code of ErrIO is returned if writing the data fails.

Reference:

RFC Section 4.10 - Variable-Length Opaque Data
Unsigned integer length followed by fixed opaque data of that length

func (*Encoder) EncodeString

func (enc *Encoder) EncodeString(v string) (int, error)

EncodeString writes the XDR encoded representation of the passed string to the encapsulated writer and returns the number of bytes written. Character encoding is assumed to be UTF-8 and therefore ASCII compatible. If the underlying character encoding is not compatible with this assumption, the data can instead be written as variable-length opaque data (EncodeOpaque) and manually converted as needed.

A MarshalError with an error code of ErrIO is returned if writing the data fails.

Reference:

RFC Section 4.11 - String
Unsigned integer length followed by bytes zero-padded to a multiple of four

func (*Encoder) EncodeUhyper

func (enc *Encoder) EncodeUhyper(v uint64) (int, error)

EncodeUhyper writes the XDR encoded representation of the passed 64-bit unsigned integer to the encapsulated writer and returns the number of bytes written.

A MarshalError with an error code of ErrIO is returned if writing the data fails.

Reference:

RFC Section 4.5 - Unsigned Hyper Integer
64-bit big-endian unsigned integer in range [0, 18446744073709551615]

func (*Encoder) EncodeUint

func (enc *Encoder) EncodeUint(v uint32) (int, error)

EncodeUint writes the XDR encoded representation of the passed 32-bit unsigned integer to the encapsulated writer and returns the number of bytes written.

A MarshalError with an error code of ErrIO is returned if writing the data fails.

Reference:

RFC Section 4.2 - Unsigned Integer
32-bit big-endian unsigned integer in range [0, 4294967295]

type Enum

type Enum interface {
	ValidEnum(int32) bool
}

Enum indicates this implementing type should be serialized/deserialized as an XDR Enum. Implement ValidEnum to specify what values are valid for this enum.

type ErrorCode

type ErrorCode int

ErrorCode identifies a kind of error.

const (
	// ErrBadArguments indicates arguments passed to the function are not
	// what was expected.
	ErrBadArguments ErrorCode = iota

	// ErrUnsupportedType indicates the Go type is not a supported type for
	// marshalling and unmarshalling XDR data.
	ErrUnsupportedType

	// ErrBadEnumValue indicates an enumeration value is not in the list of
	// valid values.
	ErrBadEnumValue

	// ErrNotSettable indicates an interface value cannot be written to.
	// This usually means the interface value was not passed with the &
	// operator, but it can also happen if automatic pointer allocation
	// fails.
	ErrNotSettable

	// ErrOverflow indicates that the data in question is too large to fit
	// into the corresponding Go or XDR data type.  For example, an integer
	// decoded from XDR that is too large to fit into a target type of int8,
	// or opaque data that exceeds the max length of a Go slice.
	ErrOverflow

	// ErrNilInterface indicates an interface with no concrete type
	// information was encountered.  Type information is necessary to
	// perform mapping between XDR and Go types.
	ErrNilInterface

	// ErrIO indicates an error was encountered while reading or writing to
	// an io.Reader or io.Writer, respectively.  The actual underlying error
	// will be available via the Err field of the MarshalError or
	// UnmarshalError struct.
	ErrIO

	// ErrParseTime indicates an error was encountered while parsing an
	// RFC3339 formatted time value.  The actual underlying error will be
	// available via the Err field of the UnmarshalError struct.
	ErrParseTime

	// ErrBadUnionSwitch indicates a union's disciminant is invalid
	ErrBadUnionSwitch

	// ErrBadUnionValue indicates a union's value is not populated when it should
	// be
	ErrBadUnionValue
)

func (ErrorCode) String

func (e ErrorCode) String() string

String returns the ErrorCode as a human-readable name.

type MarshalError

type MarshalError struct {
	ErrorCode   ErrorCode   // Describes the kind of error
	Func        string      // Function name
	Value       interface{} // Value actually parsed where appropriate
	Description string      // Human readable description of the issue
	Err         error       // The underlying error for IO errors
}

MarshalError describes a problem encountered while marshaling data. Some potential issues are unsupported Go types, attempting to encode more opaque data than can be represented by a single opaque XDR entry, and exceeding max slice limitations.

func (*MarshalError) Error

func (e *MarshalError) Error() string

Error satisfies the error interface and prints human-readable errors.

type Sized

type Sized interface {
	XDRMaxSize() int
}

Sized types are types that have an explicit maximum size. By default, the variable length XDR types (VarArray, VarOpaque and String) have a maximum byte size of a 2^32-1, but an implementor of this type may reduce that maximum to an appropriate value for the XDR schema in use.

type Union

type Union interface {
	ArmForSwitch(int32) (string, bool)
	SwitchFieldName() string
}

Union indicates the implementing type should be serialized/deserialized as an XDR Union. The implementer must provide public fields, one for the union's disciminant, whose name must be returned by ArmForSwitch(), and one per potential value of the union, which must be a pointer. For example:

type Result struct {
  Type ResultType  // this is the union's disciminant, may be 0 to indicate success, 1 to indicate error
  Msg  *string // this field will be populated when Type == 1
}

type UnmarshalError

type UnmarshalError struct {
	ErrorCode   ErrorCode   // Describes the kind of error
	Func        string      // Function name
	Value       interface{} // Value actually parsed where appropriate
	Description string      // Human readable description of the issue
	Err         error       // The underlying error for IO errors
}

UnmarshalError describes a problem encountered while unmarshaling data. Some potential issues are unsupported Go types, attempting to decode a value which is too large to fit into a specified Go type, and exceeding max slice limitations.

func (*UnmarshalError) Error

func (e *UnmarshalError) Error() string

Error satisfies the error interface and prints human-readable errors.