Documentation
¶
Overview ¶
Package ttlv implements the TTLV serialization and deserialization as defined in the Oasis KMIP 1.4 specification, section 9.1. It also supports other encoding format like
- XML as defined in KMIP 1.4 Profiles, section 5.4
- JSON as defined in KMIP 1.4 Profiles, section 5.5
- Non standard "human friendly" textual format
This package is the low level part of KMIP protocol serialization and should mostly never be used directly except to extend the kmip protocol implementation or to perform testing or optimizing stuff.
Index ¶
- Variables
- func BitmaskStr[T ~int32](value T, sep string) string
- func CompareVersions[A, B Version](a A, b B) int
- func EnumStr[T ~uint32](value T) string
- func EnumValues[T ~uint32]() iter.Seq2[T, string]
- func Errorf(format string, args ...any) error
- func IsErrEncoding(err error) bool
- func MarshalJSON(data any) []byte
- func MarshalTTLV(data any) []byte
- func MarshalText(data any) []byte
- func MarshalXML(data any) []byte
- func RegisterBitmask[T ~int32](tag int, names ...string)
- func RegisterEnum[T ~uint32](tag int, names map[T]string)
- func RegisterTag(name string, value int, ty ...reflect.Type)
- func TagString(tag int) string
- func UnmarshalJSON(data []byte, ptr any) error
- func UnmarshalTTLV(data []byte, ptr any) error
- func UnmarshalXML(data []byte, ptr any) error
- type Decodable
- type Decoder
- func (dec *Decoder) Any(value any) error
- func (dec *Decoder) BigInteger(tag int) (*big.Int, error)
- func (dec *Decoder) Bitmask(realtag, tag int) (int32, error)
- func (dec *Decoder) Bool(tag int) (bool, error)
- func (dec *Decoder) ByteString(tag int) ([]byte, error)
- func (dec *Decoder) DateTime(tag int) (time.Time, error)
- func (dec *Decoder) Enum(realtag, tag int) (uint32, error)
- func (dec *Decoder) Integer(tag int) (int32, error)
- func (dec *Decoder) Interval(tag int) (time.Duration, error)
- func (dec *Decoder) LongInteger(tag int) (int64, error)
- func (dec *Decoder) Next() error
- func (dec *Decoder) Opt(tag int, value any) error
- func (dec *Decoder) Struct(tag int, f func(*Decoder) error) error
- func (dec *Decoder) Tag() int
- func (dec *Decoder) TagAny(tag int, value any) (err error)
- func (dec *Decoder) TextString(tag int) (string, error)
- func (dec *Decoder) Type() Type
- type Encodable
- type Encoder
- func (enc *Encoder) Any(value any)
- func (enc *Encoder) BigInteger(tag int, value *big.Int)
- func (enc *Encoder) Bitmask(realtag, tag int, value int32)
- func (enc *Encoder) Bool(tag int, value bool)
- func (enc *Encoder) ByteString(tag int, str []byte)
- func (enc *Encoder) Bytes() []byte
- func (enc *Encoder) Clear()
- func (enc *Encoder) DateTime(tag int, date time.Time)
- func (enc *Encoder) Enum(realtag, tag int, value uint32)
- func (enc *Encoder) Integer(tag int, value int32)
- func (enc *Encoder) Interval(tag int, interval time.Duration)
- func (enc *Encoder) LongInteger(tag int, value int64)
- func (enc *Encoder) Struct(tag int, f func(*Encoder))
- func (enc *Encoder) TagAny(tag int, value any)
- func (enc *Encoder) TextString(tag int, str string)
- type Enum
- type ErrEncoding
- type Stream
- type Struct
- type TagDecodable
- type TagEncodable
- type Type
- type Value
- type Version
Constants ¶
This section is empty.
Variables ¶
var ErrEOF = Errorf("unexpected end of data")
ErrEOF is an ErrEncoding instance returned whensome data are missing while decoding.
Functions ¶
func BitmaskStr ¶
BitmaskStr returns the string representation of a bitmask value, consisting of a concatenation of all the flags values separated by `sep`. If it's known, the flag string value is the normalized name, otherwise it's the 0x prefixed hex value.
func CompareVersions ¶
CompareVersions compare 2 protocol version and returns
-1 if a is less than b, 0 if a equals b, +1 if a is greater than b.
func EnumStr ¶
EnumStr returns the string representation of an enum. If it's known, the string is the normalized name, otherwise it's the 0x prefixed hex value.
func EnumValues ¶
EnumValues returns an iterator over registered enum values and names for the given type T. If T is not a known enum, then the iterator will yield an empty result set.
func IsErrEncoding ¶
IsErrEncoding returns true if err is of type or wraps and error of type ErrEncoding.
func MarshalJSON ¶
MarshalJSON serializes `data` into a json TTLV encoded byte string.
func MarshalTTLV ¶
MarshalTTLV serializes `data` into a binary TTLV encoded byte array.
func MarshalText ¶
MarshalText serializes `data` into a textual and human-friendly form of TTLV. Useful mainly for debugging.
func MarshalXML ¶
MarshalXML serializes `data` into an xml TTLV encoded byte string.
func RegisterBitmask ¶
RegisterBitmask registers a bitmask types with it's tag and string values.
func RegisterEnum ¶
RegisterEnum registers an enum tag with its tag and all its string values.
func RegisterTag ¶
RegisterTag registers a new named tag and save the mapping between name and interger value for later usage by encoder and decoders. An optional list of types can be provided to also register a mapping between the types and the default tag used for serializing/deserializing them.
func UnmarshalJSON ¶
UnmarshalJSON deserializes the json TTLV byte string into the object pointed by `ptr`.
`ptr` must be a pointer.
func UnmarshalTTLV ¶
UnmarshalTTLV deserializes the binary TTLV byte string into the object pointed by `ptr`.
`ptr` must be a pointer.
func UnmarshalXML ¶
UnmarshalXML deserializes the xml TTLV byte string into the object pointed by `ptr`.
`ptr` must be a pointer.
Types ¶
type Decoder ¶
type Decoder struct {
// contains filtered or unexported fields
}
Decoder exposes methods to read TTLV tagged values to an internal buffer. It supports multiple formats like binary TTLV or xml TTLV.
func NewJSONDecoder ¶
NewJSONDecoder create a new Decoder to decode values from the json TTLV format.
func NewTTLVDecoder ¶
NewTTLVDecoder create a new Decoder to decode values from the binary TTLV format.
func NewXMLDecoder ¶
NewXMLDecoder create a new Decoder to decode values from the xml TTLV format.
func NewXMLFromDecoder ¶
NewXMLDecoder create a new Decoder to decode xml TTLV values from the given encoding/xml.Decoder.
func (*Decoder) Any ¶
Any decodes `value` by deserializing it from the buffer using value's type default tag. It panics if no tag can be found for `value` or if value does not implement Encodable. `value` must be a pointer.
func (*Decoder) BigInteger ¶
BigInteger decodes a big integer and advance to the next value.
func (*Decoder) Bitmask ¶
Bitmaks reads a bitmask value from the internal buffer. While `tag` is the tag to write with the value, which may differ from the bitmask's default tag, `realtag` can optionally be set to non-zero to identify the real default tag associated to the bitmask type. It's useful for deserializing the bitmask value from its text representation.
func (*Decoder) ByteString ¶
ByteString reads a byte array and advance to the next value.
func (*Decoder) Enum ¶
Enum reads an enum from the internal buffer. While `tag` is the tag to write with the value, which may differ from the enum's default tag, `realtag` can optionally be set to non-zero to identify the real default tag associated to the enum type. It's useful for deserializing the enum value from its text representation.
func (*Decoder) LongInteger ¶
LongInteger decodes a long integer and advance to the next value.
func (*Decoder) Opt ¶
Opt optionally decodes a value if the current tag match the one given in parameter. If not, the deserialization is skipped.
gotcha: When skipped, the passed value is not zeroed.
func (*Decoder) Struct ¶
Struct reads a structure to the internal buffer. It calls the provided callback `f` with a Decoder to use for reading struct's fields.
func (*Decoder) Tag ¶
Tag returns the tag of the current TTLV value being decoded. It returns 0 in case of EOF.
func (*Decoder) TagAny ¶
TagAny decodes `value` by deserializing it from the buffer with the given tag instead of value's type default one. It panics if value's type cannot be encoded or if it's not a pointer.
func (*Decoder) TextString ¶
TextString reads a string and advance to the next value.
type Encoder ¶
type Encoder struct {
// contains filtered or unexported fields
}
Encoder exposes methods to write TTLV tagged values to an internal buffer. It supports multiple formats like binary TTLV or xml TTLV.
func NewJSONEncoder ¶
func NewJSONEncoder() Encoder
NewJSONEncoder create a new Encoder to encode values to the json TTLV format.
func NewTTLVEncoder ¶
func NewTTLVEncoder() Encoder
NewTTLVEncoder create a new Encoder to encode values to the binary TTLV format.
func NewTextEncoder ¶
func NewTextEncoder() Encoder
NewTextEncoder create a new Encoder to print TTLV values into a textual and human-friendly form. Mainly useful for debugging.
func NewXMLEncoder ¶
func NewXMLEncoder() Encoder
NewXMLEncoder create a new Encoder to encode values to the xml TTLV format.
func (*Encoder) Any ¶
Any encodes `value` and writes it to the internal buffer using value's type default tag. It panics if no tag can be found for `value` or if value does not implement Encodable.
func (*Encoder) BigInteger ¶
BigInteger writes a big integer to the internal buffer.
func (*Encoder) Bitmask ¶
Bitmaks writes a bitmask value to the internal buffer. While `tag` is the tag to write with the value, which may differ from the bitmask's default tag, `realtag` can optionally be set to non-zero to identify the real default tag associated to the bitmask type. It's useful for serializing the bitmask value to its text representation.
func (*Encoder) ByteString ¶
ByteString writes a byte array to the internal buffer.
func (*Encoder) Clear ¶
func (enc *Encoder) Clear()
Clear clears the internal buffer without deallocating it, making the encoder reusable for encoding another value.
func (*Encoder) Enum ¶
Enum writes an enum to the internal buffer. While `tag` is the tag to write with the value, which may differ from the enum's default tag, `realtag` can optionally be set to non-zero to identify the real default tag associated to the enum type. It's useful for serializing the enum value to its text representation.
func (*Encoder) LongInteger ¶
LongInteger writes a long integer to the internal buffer.
func (*Encoder) Struct ¶
Struct writes a structure to the internal buffer. It calls the provided callback `f` with an Encoder to use for writing struct's fields.
func (*Encoder) TagAny ¶
TagAny encodes `value` and writes it to the internal buffer with the given tag instead of value's type default one. It panics if value's type cannot be encoded.
func (*Encoder) TextString ¶
TextString writes a string to the internal buffer.
type ErrEncoding ¶
type ErrEncoding struct {
// contains filtered or unexported fields
}
ErrEncoding is the error type returned when decoding data fails.
func (ErrEncoding) Error ¶
func (err ErrEncoding) Error() string
func (ErrEncoding) Unwrap ¶
func (err ErrEncoding) Unwrap() error
type Stream ¶
type Stream struct {
// contains filtered or unexported fields
}
Stream is a helper type to wrap io.ReadWrite stream to serialize and deserialize binary TTLV encoded golang types to / from the stream.
func NewStream ¶
func NewStream(inner io.ReadWriteCloser, maxSize int) Stream
NewStream creates a new TTLV stream around the given I/O stream. If maxSize is greater than 0, then it will limit the maximum allowed size in bytes for a message to receive.
func (*Stream) Recv ¶
Recv reads the next TTLV binary payload from the inner stream, then deserialize it into the value pointed by `msg`. Note that `msg` must be a pointer.
type Struct ¶
type Struct []Value
Struct is a generic TTLV struct container.
func (Struct) TagEncodeTTLV ¶
type TagDecodable ¶
TagEncodable is implemented by types implementing a custom deserialization logic, instead of relying on reflection.
type TagEncodable ¶
TagEncodable is implemented by types implementing a custom serialization logic, instead of relying on reflection.
type Type ¶
type Type uint8
Type is a TTLV encoding type as defined in the KMIP 1.4 specification, section 9.1.1.2 for TTLV encoding.
type Value ¶
Value is a generic TTLV tagged value.
Source Files