README
¶
zerobus
A small D-Bus client for Go that does not allocate once it is running.
go get github.com/bnema/zerobus # Go 1.27 or newer
- Zero allocations per message. After the first few messages warm up its buffers, a call, a reply or a signal costs no heap allocation.
- Zero-copy reads. Strings and byte arrays point straight into the receive buffer.
- Standard library only.
- Small. It connects over a Unix socket, authenticates with
EXTERNAL, calls methods, emits signals, answers calls, and adds match rules. Nothing else.
Status: v0.x. The API may change between minor versions.
Call a method
c, err := zerobus.SessionBus()
if err != nil {
log.Fatal(err)
}
defer c.Close()
e := c.NewCall("org.freedesktop.DBus", "/org/freedesktop/DBus",
"org.freedesktop.DBus", "GetNameOwner", "s")
e.Str("org.freedesktop.Notifications")
m, err := c.Call()
if err != nil {
log.Fatal(err) // a D-Bus error reply is a *zerobus.Error
}
owner := m.Body().Str()
Build a message with NewCall, NewSignal, NewReply or NewError, write its body in the order of its signature, then send it with Call (wait for the reply) or Send (do not wait). Before sending, zerobus reads the whole body back with its signature and checks names, paths and strings, so an invalid message returns ErrInvalid instead of getting the connection dropped by the bus.
Read values
Read values in the order of the signature. Errors are sticky: check Err() once at the end.
r := m.Body() // signature "a{sv}"
end := r.Array('{')
for r.More(end) {
r.Struct()
key := r.Str()
switch sig := r.Variant(); sig {
case "s":
fmt.Println(key, r.Str())
default:
r.Skip(sig) // skip values you do not need
}
}
if err := r.Err(); err != nil {
return err
}
A received message is valid only until the next ReadMessage or Call. The strings and byte slices it returns point into the receive buffer and are overwritten by the next message. Copy what you keep:
name := strings.Clone(r.Str())
icon := bytes.Clone(r.ByteArray())
Receive signals
c.AddMatch("type='signal',interface='org.kde.StatusNotifierItem'")
for {
m, err := c.ReadMessage()
if err != nil {
return err
}
if m.Type == zerobus.TypeSignal {
fmt.Println(m.Sender, m.Member)
}
}
Call reads messages until its reply arrives. Set Conn.Handle to receive the messages that arrive meanwhile; they are dropped otherwise. Handle may send (answer a call, emit a signal), but not wait: Call and ReadMessage return ErrNested inside it.
Answer calls
c.RequestName("org.example.Echo", zerobus.NameFlagDoNotQueue)
for {
m, err := c.ReadMessage()
if err != nil {
return err
}
if m.Type == zerobus.TypeMethodCall && m.Member == "Echo" {
c.NewReply(m, "s").Str(m.Body().Str())
c.Send()
}
}
Concurrency
A Conn is not safe for concurrent use. Use it from one goroutine, usually an event loop around ReadMessage. Close may be called from any goroutine: a blocked ReadMessage then returns ErrClosed.
Not supported
- Transports other than
unix:pathandunix:abstract(no TCP, nolaunchd, noautolaunch). - Passing file descriptors (
UNIX_FDvalues can be read, but no descriptors are received). - Authentication other than
EXTERNAL. - Reflection-based marshalling, introspection and code generation.
Example
examples/trayitems lists the system tray items on the session bus and prints their changes.
License
MIT
Documentation
¶
Overview ¶
Package zerobus is a small D-Bus client that does not allocate in steady state. It speaks the D-Bus wire protocol over a Unix socket and decodes messages in place, so strings and arrays point into the receive buffer and stay valid only until the next read.
Index ¶
- Constants
- Variables
- type ArrayMark
- type Conn
- func (c *Conn) AddMatch(rule string) error
- func (c *Conn) Call() (*Message, error)
- func (c *Conn) Close() error
- func (c *Conn) NewCall(dest, path, iface, member, sig string) *Encoder
- func (c *Conn) NewError(m *Message, name, sig string) *Encoder
- func (c *Conn) NewReply(m *Message, sig string) *Encoder
- func (c *Conn) NewSignal(path, iface, member, sig string) *Encoder
- func (c *Conn) ReadMessage() (*Message, error)
- func (c *Conn) RemoveMatch(rule string) error
- func (c *Conn) RequestName(name string, flags uint32) (uint32, error)
- func (c *Conn) Send() (uint32, error)
- func (c *Conn) UniqueName() string
- type Encoder
- func (e *Encoder) BeginArray(elem byte) ArrayMark
- func (e *Encoder) Bool(v bool)
- func (e *Encoder) Byte(v byte)
- func (e *Encoder) ByteArray(b []byte)
- func (e *Encoder) EndArray(a ArrayMark)
- func (e *Encoder) Float64(v float64)
- func (e *Encoder) Int16(v int16)
- func (e *Encoder) Int32(v int32)
- func (e *Encoder) Int64(v int64)
- func (e *Encoder) ObjectPath(p string)
- func (e *Encoder) SetFlags(f Flags)
- func (e *Encoder) Signature(sig string)
- func (e *Encoder) Str(s string)
- func (e *Encoder) Struct()
- func (e *Encoder) Uint16(v uint16)
- func (e *Encoder) Uint32(v uint32)
- func (e *Encoder) Uint64(v uint64)
- func (e *Encoder) Variant(sig string)
- type Error
- type Flags
- type Message
- type Reader
- func (r *Reader) Array(elem byte) int
- func (r *Reader) Bool() bool
- func (r *Reader) Byte() byte
- func (r *Reader) ByteArray() []byte
- func (r *Reader) Done() bool
- func (r *Reader) Err() error
- func (r *Reader) Float64() float64
- func (r *Reader) Int16() int16
- func (r *Reader) Int32() int32
- func (r *Reader) Int64() int64
- func (r *Reader) More(end int) bool
- func (r *Reader) ObjectPath() string
- func (r *Reader) Signature() string
- func (r *Reader) Skip(sig string)
- func (r *Reader) SkipTo(end int)
- func (r *Reader) Str() string
- func (r *Reader) Struct()
- func (r *Reader) Uint16() uint16
- func (r *Reader) Uint32() uint32
- func (r *Reader) Uint64() uint64
- func (r *Reader) UnixFD() uint32
- func (r *Reader) Variant() string
- type Type
Constants ¶
const ( NamePrimaryOwner = 1 NameInQueue = 2 NameExists = 3 NameAlreadyOwner = 4 )
Reply codes of RequestName.
const ( NameFlagAllowReplacement = 0x1 NameFlagReplaceExisting = 0x2 NameFlagDoNotQueue = 0x4 )
Flags of RequestName.
Variables ¶
var ( // ErrClosed reports a read or send on a closed or broken connection. ErrClosed = errors.New("zerobus: connection closed") // ErrNested reports a Call or ReadMessage made from inside Conn.Handle. ErrNested = errors.New("zerobus: Call or ReadMessage inside Handle") )
var ( // ErrMalformed reports bytes that do not follow the D-Bus wire format. ErrMalformed = errors.New("zerobus: malformed message") // ErrTooLarge reports a message or array over the D-Bus size limits. ErrTooLarge = errors.New("zerobus: message too large") // ErrInvalid reports an outgoing value D-Bus does not allow, such as a // string with a NUL byte or a body that does not match its signature. ErrInvalid = errors.New("zerobus: invalid value") )
Functions ¶
This section is empty.
Types ¶
type ArrayMark ¶
type ArrayMark struct {
// contains filtered or unexported fields
}
ArrayMark is an array being written; pass it to EndArray.
type Conn ¶
type Conn struct {
// Handle receives the messages that arrive while Call waits for its
// reply. It may be nil; those messages are then dropped.
//
// Handle may answer or emit messages with NewReply, NewError,
// NewSignal and Send. It may not wait: Call and ReadMessage return
// ErrNested inside it.
Handle func(*Message)
// contains filtered or unexported fields
}
Conn is a connection to a message bus.
A Conn is not safe for concurrent use: read and send from one goroutine, usually an event loop around ReadMessage. Close may be called from any goroutine to stop a blocked read.
func Dial ¶
Dial connects to a bus address such as "unix:path=/run/user/1000/bus", authenticates, and registers with the bus. Only unix:path and unix:abstract addresses are supported; with several addresses separated by ';', the first that connects is used.
func SessionBus ¶
SessionBus connects to the session bus named by DBUS_SESSION_BUS_ADDRESS, or $XDG_RUNTIME_DIR/bus when it is not set.
func SystemBus ¶
SystemBus connects to the system bus named by DBUS_SYSTEM_BUS_ADDRESS, or the standard socket when it is not set.
func (*Conn) AddMatch ¶
AddMatch asks the bus to send this connection the messages that match rule, such as "type='signal',interface='org.kde.StatusNotifierItem'".
func (*Conn) Call ¶
Call sends the method call being built and waits for its reply. Messages that arrive meanwhile go to Handle. An error reply returns an *Error. A call flagged FlagNoReplyExpected gets no reply: send it with Send.
The reply is valid until the next read, like ReadMessage's.
func (*Conn) NewCall ¶
NewCall starts a method call and returns the encoder for its body, which must match sig. Send it with Send or Call. Empty dest and iface are left out of the header.
The connection has one encoder: send a message before starting another.
func (*Conn) NewError ¶
NewError starts an error reply to the method call m. Write a message string as the body when sig is "s".
func (*Conn) NewReply ¶
NewReply starts the reply to the method call m and returns the encoder for its body.
func (*Conn) ReadMessage ¶
ReadMessage blocks until the next message arrives. The message and its strings are valid until the next call to ReadMessage or Call.
func (*Conn) RemoveMatch ¶
RemoveMatch removes a rule added by AddMatch.
func (*Conn) RequestName ¶
RequestName asks the bus for a well-known name and returns its reply code, such as NamePrimaryOwner.
func (*Conn) Send ¶
Send sends the message built since the last NewCall, NewSignal, NewReply or NewError and returns its serial.
func (*Conn) UniqueName ¶
UniqueName returns the name the bus gave this connection, such as ":1.42".
type Encoder ¶
type Encoder struct {
// contains filtered or unexported fields
}
Encoder appends D-Bus values to an outgoing message. Get one from Conn.NewCall, Conn.Signal, Conn.Reply or Conn.Error, write the body values in the order of the message signature, then call Conn.Send.
Errors are sticky and reported by Conn.Send.
func (*Encoder) BeginArray ¶
BeginArray starts an ARRAY whose element type starts with the signature byte elem. Write the elements, then call EndArray:
a := e.BeginArray('s')
e.Str("one")
e.Str("two")
e.EndArray(a)
func (*Encoder) ObjectPath ¶
ObjectPath writes an OBJECT_PATH (o).
type Error ¶
type Error struct {
Name string // such as org.freedesktop.DBus.Error.ServiceUnknown
Message string // the first string of the body, if any
}
Error is a D-Bus error reply.
type Flags ¶
type Flags byte
Flags are the header flags of a message.
const ( // FlagNoReplyExpected tells the receiver not to answer a method call. FlagNoReplyExpected Flags = 0x1 // FlagNoAutoStart tells the bus not to start the destination service. FlagNoAutoStart Flags = 0x2 // FlagAllowInteractiveAuth allows the receiver to prompt the user. FlagAllowInteractiveAuth Flags = 0x4 )
Message flags.
type Message ¶
type Message struct {
Type Type
Flags Flags
Serial uint32
ReplySerial uint32
Path string
Interface string
Member string
ErrorName string
Destination string
Sender string
Signature string // the signature of the body
// contains filtered or unexported fields
}
Message is a received message.
Its strings point into the connection's receive buffer: they and the message itself are valid only until the next read on the connection.
type Reader ¶
type Reader struct {
// contains filtered or unexported fields
}
Reader decodes D-Bus values in place.
Strings and byte slices it returns point into the message buffer: they are valid only until the next Conn.ReadMessage. Copy them (strings.Clone, bytes.Clone) to keep them longer.
Read values in the order of the message signature. Errors are sticky: after the first one, every read returns a zero value and Err reports it.
func (*Reader) Array ¶
Array reads the header of an ARRAY whose element type starts with the signature byte elem, and returns the offset where the array ends. Read the elements while More returns true:
end := r.Array('s')
for r.More(end) {
name := r.Str()
}
func (*Reader) ByteArray ¶
ByteArray reads an ARRAY of BYTE (ay). The result points into the message buffer.
func (*Reader) ObjectPath ¶
ObjectPath reads an OBJECT_PATH (o). The result points into the message buffer.
func (*Reader) Signature ¶
Signature reads a SIGNATURE (g). The result points into the message buffer.
func (*Reader) Skip ¶
Skip reads past values of the given signature. Arrays are skipped by their length, without reading their elements.
func (*Reader) SkipTo ¶
SkipTo moves to end, the value returned by Array. Use it to leave an array before its last element.
func (*Reader) Struct ¶
func (r *Reader) Struct()
Struct aligns the reader to the start of a STRUCT or DICT_ENTRY. Call it before reading the first field.
Source Files
Directories