dbus

package
v0.0.0-...-c936f35 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Apr 18, 2024 License: Apache-2.0 Imports: 11 Imported by: 3

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

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

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.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.