Documentation
¶
Overview ¶
package fragments provides low-level encoding and decoding helpers to construct and parse DBus message.
The provided encoder and decoder are low level tools, and do not ensure that all outputs are valid DBus messages.
You should not need to use this package at all, unless you are writing your own codeberg.org/dbus-go/dbus.Marshaler or codeberg.org/dbus-go/dbus.Unmarshaler, in which case your code will be handed an Encoder or Decoder and expected to produce correct DBus wire data with it.
Index ¶
- Variables
- type ByteOrder
- type Decoder
- func (d *Decoder) Array(containsStructs bool, readElement func(int) error) (int, error)
- func (d *Decoder) ByteOrderFlag() error
- func (d *Decoder) Bytes() ([]byte, error)
- func (d *Decoder) Pad(align int) error
- func (d *Decoder) Read(n int) ([]byte, error)
- func (d *Decoder) Signature() (string, error)
- func (d *Decoder) String() (string, error)
- func (d *Decoder) Struct(fields func() error) error
- func (d *Decoder) Uint16() (uint16, error)
- func (d *Decoder) Uint32() (uint32, error)
- func (d *Decoder) Uint64() (uint64, error)
- func (d *Decoder) Uint8() (uint8, error)
- func (d *Decoder) Value(ctx context.Context, v any) error
- type DecoderFunc
- type Encoder
- func (e *Encoder) Array(containsStructs bool, elements func() error) error
- func (e *Encoder) ByteOrderFlag()
- func (e *Encoder) Bytes(bs []byte)
- func (e *Encoder) Pad(align int)
- func (e *Encoder) Signature(s string)
- func (e *Encoder) String(s string)
- func (e *Encoder) Struct(elements func() error) error
- func (e *Encoder) Uint16(u16 uint16)
- func (e *Encoder) Uint32(u32 uint32)
- func (e *Encoder) Uint64(u64 uint64)
- func (e *Encoder) Uint8(u8 uint8)
- func (e *Encoder) Value(ctx context.Context, v any) error
- func (e *Encoder) Write(bs []byte)
- type EncoderFunc
Constants ¶
This section is empty.
Variables ¶
var ( BigEndian = wrapStd{binary.BigEndian} LittleEndian = wrapStd{binary.LittleEndian} NativeEndian = wrapStd{binary.NativeEndian} )
Functions ¶
This section is empty.
Types ¶
type Decoder ¶
type Decoder struct {
// Order is the initial byte order to use when reading multi-byte
// values. It can be changed during decoding by
// [Decoder.ByteOrderFlag].
Order ByteOrder
// Mapper provides DecoderFuncs for types given to
// Decoder.Value. If mapper is nil, the Decoder functions
// normally except that Decoder.Value always returns an error.
Mapper func(reflect.Type) (DecoderFunc, error)
// In is the input stream to read.
In io.Reader
// contains filtered or unexported fields
}
A Decoder provides utilities to read a DBus wire format message from an io.Reader.
Methods advance the read cursor as needed to account for the padding required by DBus alignment rules, except for Decoder.Read which reads bytes verbatim.
func (*Decoder) Array ¶
Array reads an array.
readElement is called repeatedly while there is array data remaining to process, passing in the array index of the element to be decoded. readElement must completely consume all array bytes from the input, and must not read beyond the end of the array data.
Array returns the total number of array elements that were processed.
containsStructs indicates whether the array's elements are structs, so that the decoder consumes array header padding appropriately even if the array contains no elements.
containsStructs only affects the size and alignment of the struct header. When reading an array of structs, the caller must also use Decoder.Struct appropriately to align the reads of each element.
func (*Decoder) ByteOrderFlag ¶
ByteOrderFlag reads a DBus byte order flag byte, and sets the decoder's Order to match it.
func (*Decoder) Pad ¶
Pad consumes padding bytes as needed to make the next read happen at a multiple of align bytes. If the decoder is already correctly aligned, no bytes are consumed.
type DecoderFunc ¶
A DecoderFunc reads a value into val.
type Encoder ¶
type Encoder struct {
// Order is the byte order to use when encoding multi-byte values.
Order ByteOrder
// Mapper provides EncoderFuncs for types given to
// Encoder.Value. If mapper is nil, the Encoder functions normally
// except that Encoder.Value always returns an error.
Mapper func(reflect.Type) (EncoderFunc, error)
// Out is the encoded output.
Out []byte
}
An Encoder provides utilities to write a DBus wire format message to a byte slice.
Methods insert padding as needed to conform to DBus alignment rules, except for Encoder.Write which outputs bytes verbatim.
func (*Encoder) Array ¶
Array writes an array to the output.
Array elements must be added within the provided elements function. The elements function is responsible for padding each array element to the correct alignment for the element type.
containsStructs indicates whether the array's elements are structs, so that the array header can be padded accordingly.
func (*Encoder) ByteOrderFlag ¶
func (e *Encoder) ByteOrderFlag()
ByteOrderFlag writes the DBus byte order flag byte ('l' or 'B') that matches [Encoder.Order].
func (*Encoder) Pad ¶
Pad inserts padding bytes as needed to make the next write start at a multiple of align bytes. If the message is already correctly aligned, no padding is inserted.
func (*Encoder) Struct ¶
Struct writes a struct to the output.
Struct fields must be added within the provided elements function.
func (*Encoder) Value ¶
Value writes v to the output, using the EncoderFunc provided by the encoder's Mapper.
Source Files