barista.run: barista.run/base/watchers/dbus Index | Files

package dbus

import "barista.run/base/watchers/dbus"

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

Index

Package Files

dbus.go nameowner.go properties.go testbus.go testobject.go testservice.go

type BusType Uses

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 Uses

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 Uses

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 Uses

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 Uses

func WatchNameOwner(busType BusType, name string) *NameOwnerWatcher

WatchNameOwner creates a watcher for exactly the name given.

func WatchNameOwners Uses

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 Uses

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 Uses

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 Uses

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 Uses

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 Uses

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 Uses

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 Uses

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

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

func (*PropertiesWatcher) AddSignalHandler Uses

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 Uses

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 Uses

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 Uses

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 Uses

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

Get returns the latest snapshot of all registered properties.

func (*PropertiesWatcher) Unsubscribe Uses

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 Uses

type Signal = dbus.Signal

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

type SignalType Uses

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 Uses

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

TestBus represents a mock DBus interface for testing.

func SetupTestBus Uses

func SetupTestBus() *TestBus

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

func (*TestBus) BusObject Uses

func (t *TestBus) BusObject() *TestBusObject

BusObject returns an object representing the bus itself.

func (*TestBus) Object Uses

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 Uses

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 Uses

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

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

func (*TestBusObject) AddMatchSignal Uses

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 Uses

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 Uses

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 Uses

func (t *TestBusObject) Destination() string

Destination returns the destination that calls on are sent to.

func (*TestBusObject) Emit Uses

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

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

func (*TestBusObject) GetProperty Uses

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

GetProperty returns the value of a named property.

func (*TestBusObject) Go Uses

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 Uses

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 Uses

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 Uses

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 Uses

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

Path returns the path that calls are sent to.

func (*TestBusObject) RemoveMatchSignal Uses

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 Uses

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 Uses

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

SetProperty sets a property of the test object.

func (*TestBusObject) SetPropertyForTest Uses

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 Uses

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

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

type TestBusService Uses

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

TestBusService represents a test service on the bus.

func (*TestBusService) AddName Uses

func (t *TestBusService) AddName(name string)

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

func (*TestBusService) Object Uses

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 Uses

func (t *TestBusService) RemoveName(name string)

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

func (*TestBusService) Unregister Uses

func (t *TestBusService) Unregister()

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

Package dbus imports 11 packages (graph) and is imported by 3 packages. Updated 2020-07-15. Refresh now. Tools for package owners.