dbus

Documentation

Overview

Package dbus provides watchers that notify when dbus name owners or object properties change, and infrastructure for testing code that uses them.

Index

• type BusType
• type Fetcher
• type NameOwnerChange
• type NameOwnerWatcher
  • func WatchNameOwner(busType BusType, name string) *NameOwnerWatcher
  • func WatchNameOwners(busType BusType, pattern string) *NameOwnerWatcher
  • func (n *NameOwnerWatcher) GetOwner() string
  • func (n *NameOwnerWatcher) GetOwners() map[string]string
  • func (n *NameOwnerWatcher) Unsubscribe()
• type PropertiesChange
• type PropertiesWatcher
  • func WatchProperties(busType BusType, service string, object string, iface string) *PropertiesWatcher
  • func (p *PropertiesWatcher) Add(props ...string) *PropertiesWatcher
  • func (p *PropertiesWatcher) AddSignalHandler(name string, handler func(*Signal, Fetcher) map[string]interface{}) *PropertiesWatcher
  • func (p *PropertiesWatcher) Call(name string, args ...interface{}) ([]interface{}, error)
  • func (p *PropertiesWatcher) Fetch(props ...string) *PropertiesWatcher
  • func (p *PropertiesWatcher) FetchOnSignal(props ...string) *PropertiesWatcher
  • func (p *PropertiesWatcher) Get() map[string]interface{}
  • func (p *PropertiesWatcher) Unsubscribe()
• type Signal
• type SignalType
• type TestBus
  • func SetupTestBus() *TestBus
  • func (t *TestBus) BusObject() *TestBusObject
  • func (t *TestBus) Object(dest string, path dbus.ObjectPath) *TestBusObject
  • func (t *TestBus) RegisterService(names ...string) *TestBusService
• type TestBusObject
  • func (t *TestBusObject) AddMatchSignal(iface, member string, options ...dbus.MatchOption) *dbus.Call
  • func (t *TestBusObject) Call(method string, flags dbus.Flags, args ...interface{}) *dbus.Call
  • func (t *TestBusObject) CallWithContext(ctx context.Context, method string, flags dbus.Flags, args ...interface{}) *dbus.Call
  • func (t *TestBusObject) Destination() string
  • func (t *TestBusObject) Emit(name string, args ...interface{})
  • func (t *TestBusObject) GetProperty(p string) (dbus.Variant, error)
  • func (t *TestBusObject) Go(method string, flags dbus.Flags, ch chan *dbus.Call, args ...interface{}) *dbus.Call
  • func (t *TestBusObject) GoWithContext(ctx context.Context, method string, flags dbus.Flags, ch chan *dbus.Call, ...) *dbus.Call
  • func (t *TestBusObject) On(method string, do func(...interface{}) ([]interface{}, error))
  • func (t *TestBusObject) OnElse(do func(string, ...interface{}) ([]interface{}, error))
  • func (t *TestBusObject) Path() dbus.ObjectPath
  • func (t *TestBusObject) RemoveMatchSignal(iface, member string, options ...dbus.MatchOption) *dbus.Call
  • func (t *TestBusObject) SetProperties(props map[string]interface{}, signalType SignalType)
  • func (t *TestBusObject) SetProperty(prop string, value interface{}) error
  • func (t *TestBusObject) SetPropertyForTest(prop string, value interface{}, signalType SignalType)
  • func (t *TestBusObject) StoreProperty(p string, dest interface{}) error
• type TestBusService
  • func (t *TestBusService) AddName(name string)
  • func (t *TestBusService) Object(path dbus.ObjectPath, dest string) *TestBusObject
  • func (t *TestBusService) RemoveName(name string)
  • func (t *TestBusService) Unregister()

Types

type BusType

type BusType func() dbusConn

BusType represents a type of DBus connection: system, session, or test.

var (
	// Session connects to the current user's session DBus instance.
	Session BusType = sessionBus
	// System connects to the system-wide DBus instance.
	System BusType = systemBus
	// Test connects to a test bus. Use SetupTestBus() to set up a linked
	// controller for manipulating the test bus.
	Test BusType = testBus
)

type Fetcher

type Fetcher func(string) (interface{}, error)

Fetcher represents a function that returns the current value of a property and any error that ocurred while fetching it.

type NameOwnerChange

type NameOwnerChange struct {
	Name, Owner string
}

NameOwnerChange is emitted on NameOwnerWatcher.Updates whenever any name is acquired or released. The Owner is the new owner of the name, and is empty if the name was released.

type NameOwnerWatcher

type NameOwnerWatcher struct {
	Updates <-chan NameOwnerChange
	// contains filtered or unexported fields
}

NameOwnerWatcher is a watcher for a single or wildcard service name owner. It notifies on any changes to names of interest, and provides methods to get the current owner(s) of those names.

func WatchNameOwner

func WatchNameOwner(busType BusType, name string) *NameOwnerWatcher

WatchNameOwner creates a watcher for exactly the name given.

func WatchNameOwners

func WatchNameOwners(busType BusType, pattern string) *NameOwnerWatcher

WatchNameOwners creates a watcher for any names within the 'namespace' given. For example, 'com.example.backend1' will notify for 'com.example.backend1.foo', 'com.example.backend1.foo.bar', and 'com.example.backend1' itself. All matching names and their owners can be retrieved using GetOwners().

func (*NameOwnerWatcher) GetOwner

func (n *NameOwnerWatcher) GetOwner() string

GetOwner gets an owner of a service name of interest. For an exact watcher, this returns the owner of the service name (or empty if no owner), for a wildcard watcher it returns a random owner from all that match. Even with wildcard watcher, this method can be used to get the name of the lone owner of the service name.

func (*NameOwnerWatcher) GetOwners

func (n *NameOwnerWatcher) GetOwners() map[string]string

GetOwners returns a map of service names to owners for all services that match the watcher criterion.

func (*NameOwnerWatcher) Unsubscribe

func (n *NameOwnerWatcher) Unsubscribe()

Unsubscribe clears all subscriptions and internal state. The watcher cannot be used after calling this method. Usually `defer`d when creating a watcher.

type PropertiesChange

type PropertiesChange map[string][2]interface{}

PropertiesChange is emitted on PropertiesWatcher.Updates whenever any properties change. The key is the name of the property changed, and the value is a pair of interface{} values: {oldValue, newValue}.

type PropertiesWatcher

type PropertiesWatcher struct {
	Updates <-chan PropertiesChange
	// contains filtered or unexported fields
}

PropertiesWatcher is a watcher for the properties of a DBus object. It provides update notifications and the ability to map custom signals to property changes.

func WatchProperties

func WatchProperties(busType BusType, service string, object string, iface string) *PropertiesWatcher

WatchProperties constructs a DBus properties watcher for the given object and interface, using a specified bus and service name. The list of properties is further used to filter events, as well as to fetch initial data when the watcher is constructed. Watchers must be cleaned up by calling Unsubscribe.

func (*PropertiesWatcher) Add

func (p *PropertiesWatcher) Add(props ...string) *PropertiesWatcher

Add specifies properties to watch, relying on the PropertiesChanged signal to update their value.

func (*PropertiesWatcher) AddSignalHandler

func (p *PropertiesWatcher) AddSignalHandler(
	name string,
	handler func(*Signal, Fetcher) map[string]interface{},
) *PropertiesWatcher

AddSignalHandler adds a signal handler for a signal emitted by the interface being watched that updates properties without emitting a PropertiesChanged signal (e.g. mpris 'Seeked'). The handler function should return a map of all properties that have changed.

func (*PropertiesWatcher) Call

func (p *PropertiesWatcher) Call(name string, args ...interface{}) ([]interface{}, error)

Call calls a DBus method on the object being watched and returns the result. This method will deadlock if called from within a signal handler.

func (*PropertiesWatcher) Fetch

func (p *PropertiesWatcher) Fetch(props ...string) *PropertiesWatcher

Fetch specifies additional properties to fetch each time the full set of properties is requested via Get().

func (*PropertiesWatcher) FetchOnSignal

func (p *PropertiesWatcher) FetchOnSignal(props ...string) *PropertiesWatcher

FetchOnSignal specifies additional properties to fetch when the object emits PropertiesChanged. This can be useful for tracking computed properties if their value only changes when other properties also change. These properties will be included in emitted PropertiesChange values.

func (*PropertiesWatcher) Get

func (p *PropertiesWatcher) Get() map[string]interface{}

Get returns the latest snapshot of all registered properties.

func (*PropertiesWatcher) Unsubscribe

func (p *PropertiesWatcher) Unsubscribe()

Unsubscribe clears all subscriptions and internal state. The watcher cannot be used after calling this method. Usually `defer`d when creating a watcher.

type Signal

type Signal = dbus.Signal

Signal re-exports dbus.Signal to avoid namespace clashes for consumers.

type SignalType

type SignalType byte

SignalType controls the type of signal sent on properties change

const (
	// SignalTypeNone does not emit any signal on properties change.
	SignalTypeNone SignalType = iota
	// SignalTypeChanged emits a PropertiesChanged signal with values for each
	// modified property in changed_properties.
	SignalTypeChanged
	// SignalTypeInvalidated emits a PropertiesChanged signal with only the
	// property names in invalidated_properties.
	SignalTypeInvalidated
)

type TestBus

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

TestBus represents a mock DBus interface for testing.

func SetupTestBus

func SetupTestBus() *TestBus

SetupTestBus sets up a test bus instance for testing, and returns a linked controller to manipulate the instance.

func (*TestBus) BusObject

func (t *TestBus) BusObject() *TestBusObject

BusObject returns an object representing the bus itself.

func (*TestBus) Object

func (t *TestBus) Object(dest string, path dbus.ObjectPath) *TestBusObject

Object returns the object at a given path of the specified service.

func (*TestBus) RegisterService

func (t *TestBus) RegisterService(names ...string) *TestBusService

RegisterService returns a new test service and optionally registers it for one or more well-known names.

type TestBusObject

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

TestBusObject represents a connection to an object on the test bus.

func (*TestBusObject) AddMatchSignal

func (t *TestBusObject) AddMatchSignal(iface, member string, options ...dbus.MatchOption) *dbus.Call

AddMatchSignal subscribes BusObject to signals from specified interface and method with the given filters.

func (*TestBusObject) Call

func (t *TestBusObject) Call(method string, flags dbus.Flags, args ...interface{}) *dbus.Call

Call calls a method with and waits for its reply.

func (*TestBusObject) CallWithContext

func (t *TestBusObject) CallWithContext(ctx context.Context, method string, flags dbus.Flags, args ...interface{}) *dbus.Call

CallWithContext acts like Call but takes a context.

func (*TestBusObject) Destination

func (t *TestBusObject) Destination() string

Destination returns the destination that calls on are sent to.

func (*TestBusObject) Emit

func (t *TestBusObject) Emit(name string, args ...interface{})

Emit emits a signal on the test bus, dispatching it to relevant listeners.

func (*TestBusObject) GetProperty

func (t *TestBusObject) GetProperty(p string) (dbus.Variant, error)

GetProperty returns the value of a named property.

func (*TestBusObject) Go

func (t *TestBusObject) Go(method string, flags dbus.Flags, ch chan *dbus.Call, args ...interface{}) *dbus.Call

Go calls a method with the given arguments asynchronously.

func (*TestBusObject) GoWithContext

func (t *TestBusObject) GoWithContext(ctx context.Context, method string, flags dbus.Flags, ch chan *dbus.Call, args ...interface{}) *dbus.Call

GoWithContext acts like Go but takes a context.

func (*TestBusObject) On

func (t *TestBusObject) On(method string, do func(...interface{}) ([]interface{}, error))

On sets up a function to be called when the given named method is invoked, and returns the result of the function to the method caller.

func (*TestBusObject) OnElse

func (t *TestBusObject) OnElse(do func(string, ...interface{}) ([]interface{}, error))

OnElse sets the function to be called for all methods that don't have a separate On(method, ...) definition.

func (*TestBusObject) Path

func (t *TestBusObject) Path() dbus.ObjectPath

Path returns the path that calls are sent to.

func (*TestBusObject) RemoveMatchSignal

func (t *TestBusObject) RemoveMatchSignal(iface, member string, options ...dbus.MatchOption) *dbus.Call

RemoveMatchSignal unsubscribes BusObject from signals from specified interface and method with the given filters.

func (*TestBusObject) SetProperties

func (t *TestBusObject) SetProperties(props map[string]interface{}, signalType SignalType)

SetProperties sets multiple properties of the test object. The signal type controls whether a "PropertiesChanged" signal is automatically emitted, and what form the emitted signal takes.

func (*TestBusObject) SetProperty

func (t *TestBusObject) SetProperty(prop string, value interface{}) error

SetProperty sets a property of the test object.

func (*TestBusObject) SetPropertyForTest

func (t *TestBusObject) SetPropertyForTest(prop string, value interface{}, signalType SignalType)

SetPropertyForTest sets a property of the test object. The signal type parameter controls whether a "PropertiesChanged" signal is automatically emitted, and what form the emitted signal takes.

func (*TestBusObject) StoreProperty

func (t *TestBusObject) StoreProperty(p string, dest interface{}) error

StoreProperty stores the value of a named property into a given pointer.

type TestBusService

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

TestBusService represents a test service on the bus.

func (*TestBusService) AddName

func (t *TestBusService) AddName(name string)

AddName registers the service for the given well-known name.

func (*TestBusService) Object

func (t *TestBusService) Object(path dbus.ObjectPath, dest string) *TestBusObject

Object returns a test object on the service at the given path. If non-empty, dest is used to override the destination interface for the object.

func (*TestBusService) RemoveName

func (t *TestBusService) RemoveName(name string)

RemoveName unregisters the service for the given well-known name.

func (*TestBusService) Unregister

func (t *TestBusService) Unregister()

Unregister unregisters the service from the bus completely. The service and all associated objects are unusable after this.