dbus

package module
v0.0.0-...-072f331 Latest Latest
Warning

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

 Go to latest Published: Feb 4, 2025 License: BSD-3-Clause Imports: 25 Imported by: 0

README

DBus for Go

A work in progress. Very unstable, API and semantics still changing. I suggest looking, but not touching.

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func RegisterPropertyChangeType 

func RegisterPropertyChangeType[T any](interfaceName, propertyName string)

RegisterPropertyChangeType registers T as the type to use when reporting a property change for the given property.

Panics if the property already has a registered type.

func RegisterSignalType 

func RegisterSignalType[T any](interfaceName, signalName string)

RegisterSignalType registers T as the struct type to use when decoding the body of the given signal name.

Panics if the signal already has a registered type.

func WithContextAutostart 

func WithContextAutostart(ctx context.Context, allow bool) context.Context

WithContextAutostart returns a copy of the parent context with the DBus auto-start policy set according to allow.

Services that provide DBus APIs can elect to be "bus activated". Bus activated peers are present on the bus even when their underlying service isn't running, and the bus arranges to start them seamlessly when something communicates with them.

By default, method calls trigger bus activation, and clients don't need to be aware of this feature. If auto-starting services is undesirable, WithContextAutostart can be used to make calls fail with a CallError if they would trigger a bus activation.

func WithContextUserInteraction 

func WithContextUserInteraction(parent context.Context, allow bool) context.Context

WithContextUserInteraction returns a copy of the parent context with the DBus user interation policy set according to allow.

Allowing user interaction prompts the user for permission to proceed when a call is made to a privileged method, instead of returning an access denied error immediately.

Interaction is disabled by default because it can cause calls to block for an extended period of time, until the user responds to the authorization prompt, or indefinitely on servers where users aren't expected to be available for interactive prompting.

Types

type ActivatableServicesChanged 

type ActivatableServicesChanged struct{}

ActivatableServicesChanged signals that the list of activatable peers has changed. Use Conn.ActivatablePeers to obtain an updated list.

It corresponds to the org.freedesktop.DBus.ActivatableServicesChanged signal.

type ArgumentDescription 

type ArgumentDescription struct {
	Name string // optional
	Type Signature
}

ArgumentDescription describes a DBus method's input or output, or a signal's argument.

Property descriptions are provied by the DBus peer offering the corresponding API, and may not accurately reflect the actual argument.

func (ArgumentDescription) String 

func (a ArgumentDescription) String() string

type CallError 

type CallError struct {
	// Name is the error name provided by the remote peer.
	Name string
	// Detail is the human-readable explanation of what went wrong.
	Detail string
}

CallError is the error returned from failed DBus method calls.

func (CallError) Error 

func (e CallError) Error() string

type Claim 

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

Claim is a claim to ownership of a bus name.

Multiple DBus clients may claim ownership of the same name. The bus tracks a single current owner, as well as a queue of other claimants that are eligible to succeed the current owner.

The exact interaction of multiple different claims to a name depends on the ClaimOptions set by each claimant.

func (*Claim) Chan 

func (c *Claim) Chan() <-chan bool

Chan returns a channel that reports whether this claim is the current owner of the bus name.

func (*Claim) Close 

func (c *Claim) Close() error

Close abandons the claim.

If the claim is the current owner of the bus name, ownership is lost and may be passed on to another claimant.

func (*Claim) Name 

func (c *Claim) Name() string

Name returns the claim's bus name.

func (*Claim) Request 

func (c *Claim) Request(opts ClaimOptions) error

Request makes a new request to the bus for the claimed name.

If this Claim is the current owner, Request updates the AllowReplacement and NoQueue settings without relinquishing ownership (although setting AllowReplacement may enable another client to take over the claim).

If this claim is not the current owner, the bus considers this claim anew with the updated ClaimOptions, as if this client were making a claim for the first time.

Request only returns a non-nil error if sending the updated claim request fails. Failure to acquire ownership is not an error.

type ClaimOptions 

type ClaimOptions struct {
	// AllowReplacement is whether to allow another request that sets
	// TryReplace to take over ownership.
	//
	// A claim that gets replaced as the current owner gets moved to
	// the head of the backup queue, or gets dropped from the line of
	// succession entirely if NoQueue is set.
	AllowReplacement bool
	// TryReplace is whether to attempt to replace the current owner,
	// if the name already has an owner.
	//
	// Replacement is only permitted if the current owner made its
	// claim with the AllowReplacement option set. Otherwise, the
	// request for ownership joins the backup queue or returns an
	// error, depending on the NoQueue setting.
	//
	// TryReplace only takes effect at the moment the request is
	// made. If the replacement attempt fails and later on the owner
	// changes its settings to allow replacement, this queued claim
	// must explicitly request replacement again to take advantage of
	// the change.
	TryReplace bool
	// NoQueue, if set, causes this claim to never join the backup
	// queue for any reason.
	//
	// If ownership of the name cannot be secured when the initial
	// claim is made, or if ownership is later lost due to the effect
	// of AllowReplacement/TryReplace, the claim becomes inactive
	// until a new request is explicitly made with Claim.Request.
	NoQueue bool
}

ClaimOptions are the options for a Claim to a bus name.

type Conn 

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

Conn is a DBus connection.

func Dial 

func Dial(ctx context.Context, path string) (*Conn, error)

Dial connects to the bus using the Unix domain socket at the given path.

This is intended for connecting to testing busses during development. Most users should use SessionBus or SystemBus instead.

func SessionBus 

func SessionBus(ctx context.Context) (*Conn, error)

SessionBus connects to the current user's session bus.

func SystemBus 

func SystemBus(ctx context.Context) (*Conn, error)

SystemBus connects to the system bus.

func (*Conn) ActivatablePeers 

func (c *Conn) ActivatablePeers(ctx context.Context) ([]Peer, error)

ActivatablePeers returns a list of activatable peers.

An activatable Peer is started automatically when a request is sent to it, and may shut down when idle.

func (*Conn) BusID 

func (c *Conn) BusID(ctx context.Context) (string, error)

BusID returns the globally unique ID of the bus to which the Conn is connected.

func (*Conn) Claim 

func (c *Conn) Claim(name string, opts ClaimOptions) (*Claim, error)

Claim requests ownership of a bus name.

Bus names may have multiple active claims by different clients, but only one active owner at a time. The ClaimOptions set by each claimant determines the owner and rules of succession.

Claiming a name does not guarantee ownership of the name. Callers must monitor Claim.Chan to find out if and when the name gets assigned to them.

func (*Conn) Close 

func (c *Conn) Close() error

Close closes the DBus connection.

func (*Conn) EmitSignal 

func (c *Conn) EmitSignal(ctx context.Context, obj ObjectPath, signal any) error

EmitSignal broadcasts signal from obj.

The signal's type must be registered in advance with RegisterSignalType.

func (*Conn) Features 

func (c *Conn) Features(ctx context.Context) ([]string, error)

Features returns a list of strings describing the optional features that the bus supports.

func (*Conn) Handle 

func (c *Conn) Handle(interfaceName, methodName string, fn any)

Handle calls fn to handle incoming method calls to methodName on interfaceName.

fn must have one of the following type signatures, where ReqType and RetType determine the method's Signature. 

func(context.Context, dbus.ObjectPath) error
func(context.Context, dbus.ObjectPath) (RetType, error)
func(context.Context, dbus.ObjectPath, ReqType) error
func(context.Context, dbus.ObjectPath, ReqType) (RetType, error)

Handle panics if fn is not one of the above type signatures.

func (*Conn) LocalName 

func (c *Conn) LocalName() string

LocalName returns the connection's unique bus name.

func (*Conn) Peer 

func (c *Conn) Peer(name string) Peer

Peer returns a Peer for the given bus name.

The returned value is a local handle only. It does not indicate that the requested peer exists, or that it is currently reachable.

func (*Conn) Peers 

func (c *Conn) Peers(ctx context.Context) ([]Peer, error)

Peers returns a list of peers currently connected to the bus.

func (*Conn) Watch 

func (c *Conn) Watch() (*Watcher, error)

Watch watches the bus for notifications from other bus participants.

A newly created Watcher delivers no notifications. The caller must use Watcher.Match to specify which signals and property changes the Watcher should provide.

type InlineLayout 

type InlineLayout struct{}

InlineLayout marks a struct as being inlined. A struct with a field of type InlineLayout will be laid out in DBus messages without the initial 8-byte alignment that DBus structs normally enforce.

By convention, InlineLayout should be used as the type of a field named "_", placed at the beginning of the struct type definition.

type Interface 

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

Interface is a set of methods, properties and signals offered by an Object.

func ContextEmitter 

func ContextEmitter(ctx context.Context) (Interface, bool)

ContextEmitter returns the notification's emitter value from ctx, and reports whether an emitter was found.

Emitter information is only available in the context of Unmarshaler's UnmarshalDBus method, when unmarshaling a signal or property change type.

func (Interface) Call 

func (f Interface) Call(ctx context.Context, method string, body any, response any) error

Call calls method on the interface with the given request body, and writes the response into response.

This is a low-level calling API. It is the caller's responsibility to match the body and response types to the signature of the method being invoked. Body may be nil for methods that accept no parameters. Response may be nil for methods that return no values.

func (Interface) Compare 

func (f Interface) Compare(other Interface) int

Compare compares two interfaces, with the same convention as cmp.Compare.

func (Interface) Conn 

func (f Interface) Conn() *Conn

Conn returns the DBus connection associated with the interface.

func (Interface) GetAllProperties 

func (f Interface) GetAllProperties(ctx context.Context) (map[string]any, error)

GetAllProperties returns all the properties exported by the interface.

func (Interface) GetProperty 

func (f Interface) GetProperty(ctx context.Context, name string, val any) error

GetProperty reads the value of the given property into val.

It is the caller's responsibility to match the value's type to the type offered by the interface. val may also be of type *any to retrieve a property without knowing its type.

func (Interface) Name 

func (f Interface) Name() string

Name returns the name of the interface.

func (Interface) Object 

func (f Interface) Object() Object

Object returns the Object that implements the interface.

func (Interface) OneWay 

func (f Interface) OneWay(ctx context.Context, method string, body any) error

OneWay calls method on the interface with the given request body, and tells the peer not to send a reply.

OneWay returns after the method call is successfully sent. Since the response is suppressed at the bus level, there is no way to know whether the call was delivered to anyone, or acted upon.

This is a low-level calling API. It is the caller's responsibility to match the body to the signature of the method being invoked. Body may be nil for methods that accept no parameters.

func (Interface) Peer 

func (f Interface) Peer() Peer

Peer returns the Peer that is offering the interface.

func (Interface) SetProperty 

func (f Interface) SetProperty(ctx context.Context, name string, value any) error

SetProperty sets the given property to value.

It is the caller's responsibility to match the value's type to the type offered by the interface.

func (Interface) String 

func (f Interface) String() string

type InterfaceDescription 

type InterfaceDescription struct {
	Name       string                 `xml:"name,attr"`
	Methods    []*MethodDescription   `xml:"method"`
	Signals    []*SignalDescription   `xml:"signal"`
	Properties []*PropertyDescription `xml:"property"`
}

InterfaceDescription describes a DBus interface.

Interface descriptions are provided by the DBus peer offering the interface, and may not accurately reflect the actual exposed API.

func (InterfaceDescription) String 

func (d InterfaceDescription) String() string

type InterfacesAdded 

type InterfacesAdded struct {
	Object     Object
	Interfaces []Interface
}

InterfacesAdded signals that an object is offering new interfaces for use.

It corresponds to the org.freedesktop.DBus.ObjectManager.InterfacesAdded signal.

func (*InterfacesAdded) SignatureDBus 

func (s *InterfacesAdded) SignatureDBus() Signature

func (*InterfacesAdded) UnmarshalDBus 

func (s *InterfacesAdded) UnmarshalDBus(ctx context.Context, d *fragments.Decoder) error

type InterfacesRemoved 

type InterfacesRemoved struct {
	Object     Object
	Interfaces []Interface
}

InterfacesAdded signals that an object has ceased to offer one or more interfaces for use.

It corresponds to the org.freedesktop.DBus.ObjectManager.InterfacesRemoved signal.

func (*InterfacesRemoved) SignatureDBus 

func (s *InterfacesRemoved) SignatureDBus() Signature

func (*InterfacesRemoved) UnmarshalDBus 

func (s *InterfacesRemoved) UnmarshalDBus(ctx context.Context, d *fragments.Decoder) error

type Marshaler 

type Marshaler interface {
	SignatureDBus() Signature
	MarshalDBus(ctx context.Context, e *fragments.Encoder) error
}

Marshaler is the interface implemented by types that can marshal themselves to the DBus wire format.

SignatureDBus is invoked on a zero value of the Marshaler, and must return a constant.

MarshalDBus is responsible for inserting padding appropriate to the values being encoded, and for producing output that matches the structure declared by SignatureDBus.

type Match 

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

Match is a filter that matches DBus signals.

func MatchAllSignals 

func MatchAllSignals() *Match

MatchAllSignals returns a Match for all signals.

func MatchNotification 

func MatchNotification[NotificationT any]() *Match

MatchNotification returns a match for the given notification.

The provided notification type must be registered with RegisterSignalType or RegisterPropertyChangeType prior to calling MatchNotification.

func (*Match) Arg0Namespace 

func (m *Match) Arg0Namespace(val string) *Match

Arg0Namespace restricts the Match to signals whose first body field is a peer or interface name with the given dot-separated prefix.

Arg0Namespace can only be used on signal matches, not property matches.

func (*Match) ArgPathPrefix 

func (m *Match) ArgPathPrefix(i int, val ObjectPath) *Match

ArgPathPrefix restricts the Match to signals whose i-th body field is a string or ObjectPath with the given prefix.

ArgPathPrefix can only be used on signal matches, not property matches.

func (*Match) ArgStr 

func (m *Match) ArgStr(i int, val string) *Match

ArgStr restricts the match to signals whose i-th body field is a string equal to val.

ArgStr can only be used on signal matches, not property matches.

func (*Match) Object 

func (m *Match) Object(o ObjectPath) *Match

Object restricts the match to a single source path.

func (*Match) ObjectPrefix 

func (m *Match) ObjectPrefix(o ObjectPath) *Match

ObjectPrefix restricts the match to sending Objects rooted at the given path prefix.

For example, ObjectPrefix("/mascots/gopher") matches signals emitted by /mascots/gopher, /mascots/gopher/plushie, /mascots/gopher/art/renee-french, but not /mascots/glenda.

func (*Match) Peer 

func (m *Match) Peer(p Peer) *Match

Sender restricts the match to a single source Peer.

type MethodDescription 

type MethodDescription struct {
	Name string
	In   []ArgumentDescription
	Out  []ArgumentDescription
	// Deprecated, if true, indicates that the method should be
	// avoided in new code.
	Deprecated bool
	// If true, NoReply indicates that the caller is expected to use
	// Interface.OneWay to invoke this method, not Interface.Call.
	NoReply bool
}

MethodDescription describes a DBus method.

Method descriptions are provided by the DBus peer offering the method, and may not accurately reflect the actual exposed API.

func (MethodDescription) String 

func (m MethodDescription) String() string

func (*MethodDescription) UnmarshalXML 

func (m *MethodDescription) UnmarshalXML(d *xml.Decoder, start xml.StartElement) error

type NameAcquired 

type NameAcquired struct {
	Name string
}

NameAcquired signals to the receiving client that it has gained ownership of a bus name.

It corresponds to the org.freedesktop.DBus.NameAcquired signal.

type NameLost 

type NameLost struct {
	Name string
}

NameLost signals to the receiving client that it has lost ownership of a bus name.

It corresponds to the org.freedesktop.DBus.NameLost signal.

type NameOwnerChanged 

type NameOwnerChanged struct {
	// Name is the bus name whose ownership has changed.
	Name string
	// Prev is the previous owner of Name, or nil if Name has just
	// been created.
	Prev *Peer
	// New is the current owner of Name, or nil if Name is defunct.
	New *Peer
}

NameOwnerChanged signals that a name has changed owners.

It corresponds to the org.freedesktop.DBus.NameOwnerChanged signal.

func (*NameOwnerChanged) SignatureDBus 

func (s *NameOwnerChanged) SignatureDBus() Signature

func (*NameOwnerChanged) UnmarshalDBus 

func (s *NameOwnerChanged) UnmarshalDBus(ctx context.Context, d *fragments.Decoder) error

type Notification 

type Notification struct {
	// Sender is the originator of the notification.
	Sender Interface
	// Name is the name of the signal or changed property.
	Name string
	// Body is the signal payload or property value.
	//
	// For signals, Body a pointer to the struct type that was
	// associated with the signal name using RegisterSignalType, or
	// a pointer to an anonymous struct if no type was registered for
	// the signal.
	//
	// For property changes, Body is a pointer to the struct type that
	// was associated with the property using
	// RegisterPropertyChangeType, or a pointer to an anonymous struct
	// if no type was registered for the property.
	Body any
	// Overflow reports that the watcher discarded some notifications
	// that followed this one, due to the caller not processing
	// delivered notifications fast enough.
	Overflow bool
}

Notification is a signal or property change received from a bus peer.

type Object 

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

Object is an object exposed by a Peer.

func (Object) Child 

func (o Object) Child(path string) Object

Child returns the named object at the given relative path from the current object.

func (Object) Compare 

func (o Object) Compare(other Object) int

func (Object) Conn 

func (o Object) Conn() *Conn

Conn returns the DBus connection associated with the object.

func (Object) Interface 

func (o Object) Interface(name string) Interface

Interface returns a named interface on the object.

The returned value is a local handle only. It does not indicate that the object supports the requested interface.

func (Object) Introspect 

func (o Object) Introspect(ctx context.Context) (*ObjectDescription, error)

Introspect returns the object's description of the interfaces it implements.

Note that while DBus objects are generally well behaved, this description is not verified or enforced by the bus, and may not accurately reflect the object's implementation.

Introspect returns a CallError if the queried object does not implement the org.freedesktop.DBus.Introspectable interface.

func (Object) ManagedObjects 

func (o Object) ManagedObjects(ctx context.Context) (map[Object][]Interface, error)

ManagedObjects returns the children of the current Object, and the interfaces they implement.

ManagedObjects returns a CallError if the queried object does not implement the org.freedesktop.DBus.ObjectManager interface.

func (Object) Path 

func (o Object) Path() ObjectPath

Path returns the object's path.

func (Object) Peer 

func (o Object) Peer() Peer

Peer returns the peer that is exposing the object.

func (Object) String 

func (o Object) String() string

type ObjectDescription 

type ObjectDescription struct {
	// Interfaces maps an interface name to a description of its API.
	Interfaces map[string]*InterfaceDescription
	// Children is the relative paths to child objects under this
	// object. The relative paths may contain multiple path
	// components.
	Children []string
}

ObjectDescription describes a DBus object's exported interfaces and child objects.

Interface and child descriptions are provided by the DBus peer hosting the object, and may not accurately reflect the actual exposed API or object structure.

func (*ObjectDescription) UnmarshalXML 

func (o *ObjectDescription) UnmarshalXML(d *xml.Decoder, start xml.StartElement) error

type ObjectPath 

type ObjectPath string

An ObjectPath is a filesystem-like path for an Object exposed on over DBus.

func (ObjectPath) Child 

func (p ObjectPath) Child(relPath string) ObjectPath

Child returns the object path at the given relative path from the current object.

func (ObjectPath) Clean 

func (p ObjectPath) Clean() ObjectPath

Clean returns the result of applying path.Clean to the object path.

func (ObjectPath) IsChildOf 

func (p ObjectPath) IsChildOf(parent ObjectPath) bool

IsChildOf reports whether p is a child of the given parent.

func (ObjectPath) String 

func (p ObjectPath) String() string

func (ObjectPath) Valid 

func (p ObjectPath) Valid() bool

Valid reports whether p is a valid object path.

type Peer 

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

Peer is a named bus endpoint.

A Peer may provide access to Object and Interface values, emit [Signal] notifications, or make method calls to other bus participants.

func ContextDestination 

func ContextDestination(ctx context.Context) (Peer, bool)

ContextDestination returns the destination found in ctx, and reports whether a destination was found.

Destination information is available in the context of Marshaler's MarshalDBus method when sending method calls, and in the context of Unmarshaler's UnmarshalDBus method when receiving method calls.

func ContextSender 

func ContextSender(ctx context.Context) (Peer, bool)

ContextSender returns the sender found in ctx, and reports whether a sender was found.

Sender information is available in the context of Unmarshaler's UnmarshalDBus method.

func (Peer) Compare 

func (p Peer) Compare(other Peer) int

func (Peer) Conn 

func (p Peer) Conn() *Conn

Conn returns the DBus connection associated with the peer.

func (Peer) Exists 

func (p Peer) Exists(ctx context.Context) (bool, error)

Exists reports whether the peer is currently present on the bus.

Exists does not take activatable services into account. This means that Exists may report false for a Peer that is started on demand when communicated with.

Exists is intended for debugging only. In particular, you should not use Exists to see if a peer exists before communicating with it. Instead, verify the existence of the peer and the objects and interfaces you need by attempting to use them, and handling errors appropriately.

func (Peer) Identity 

func (p Peer) Identity(ctx context.Context) (PeerIdentity, error)

Identity returns the peer's identity descriptor.

The returned identity is provided by the bus itself, and guaranteed to be accurate (bugs in the bus implementation notwithstanding).

func (Peer) IsUniqueName 

func (p Peer) IsUniqueName() bool

IsUniqueName reports whether the peer name is a unique bus name for a client connection.

func (Peer) Name 

func (p Peer) Name() string

Name returns the name of the peer.

func (Peer) Object 

func (p Peer) Object(path ObjectPath) Object

Object returns a named object on the peer.

The returned value is a local handle only. It does not indicate that the peer is providing an object at the requested path.

func (Peer) Owner 

func (p Peer) Owner(ctx context.Context) (Peer, error)

Owner returns the current owner of this peer's name.

If the Peer is a handle to a peer's unique connection name (like ":1.42"), Owner returns the same Peer. If the Peer is a well-known bus name (like "org.freedesktop.DBus"), Owner returns the Peer for the current owner's unique connection name.

func (Peer) PID deprecated 

func (p Peer) PID(ctx context.Context) (uint32, error)

PID returns the Unix process ID for the peer, if available.

PIDs are vulnerable to time-of-check/time-of-use attacks, and should not be used to make authentication or authorization decisions.

Deprecated: use Peer.Identity instead, which returns more complete identity information. In particular, when available, the PIDFD field of PeerIdentity provides a more robust handle for the peer's process that is not vulnerable to time-of-check/time-of-use attacks.

func (Peer) Ping 

func (p Peer) Ping(ctx context.Context) error

Ping checks that the peer is reachable.

Ping returns a CallError if the queried peer does not implement the org.freedesktop.DBus.Peer interface on its root object. In practice, all DBus client implementations implement this interface, although they are not strictly required to.

func (Peer) QueuedOwners 

func (p Peer) QueuedOwners(ctx context.Context) ([]Peer, error)

QueuedOwners returns the list of peers that have requested ownership of this peer's name.

The returned list begins with the current owner, followed by other claimants in the order of succession. If you only need the current owner, use Peer.Owner instead.

func (Peer) String 

func (p Peer) String() string

func (Peer) UID deprecated 

func (p Peer) UID(ctx context.Context) (uint32, error)

UID returns the Unix user ID for the peer, if available.

Deprecated: use Peer.Identity instead, which returns more complete identity information.

type PeerIdentity 

type PeerIdentity struct {
	// UID is the Unix user ID of the peer, or nil if uid information is
	// not available.
	UID *uint32 `dbus:"key=UnixUserID"`
	// GIDs are the Unix group IDs of the peer.
	GIDs []uint32 `dbus:"key=UnixGroupIDs"`
	// PIDFD is a file handle that represents the Peer's
	// process. PIDFD should be preferred over PID, as it is not
	// vulnerable to time-of-check/time-of-use vulnerabilities.
	PIDFD *os.File `dbus:"key=ProcessFD"`
	// PID is the Unix process ID of the peer, or nil if pid
	// information is not available. Note that PIDs are not unique
	// identities, and therefore are vulnerable to
	// time-of-check/time-of-use attacks.
	PID *uint32 `dbus:"key=ProcessID"`
	// SecurityLabel is the peer's Linux security label, as returned
	// by the SO_PEERSEC Unix socket option.
	//
	// The security label's format is specific to the running "major"
	// LSM (Linux Security Module). DBus does not provide a means to
	// discover which LSM provided this value.
	//
	// On SELinux systems, SecurityLabel is the peer's SELinux
	// context.
	//
	// On Smack systems, SecurityLabel is the Smack label.
	//
	// On AppArmor systems, SecurityLabel is the AppArmor profile name
	// and enforcement mode.
	SecurityLabel []byte `dbus:"key=LinuxSecurityLabel"`

	// Unknown collects identity values provided by the bus that are
	// not known to this library.
	Unknown map[string]any `dbus:"vardict"`
}

PeerIdentity describes the identity of a Peer.

type PropertiesChanged 

type PropertiesChanged struct {
	// Interface is the DBus interface whose properties have changed.
	Interface Interface
	// Changed lists changed property values, keyed by property name.
	Changed map[string]any
	// Invalidated lists the names of properties that have changed,
	// but whose updated value was not broadcast. If desired,
	// [Interface.GetProperty] may be used to read the updated value.
	Invalidated mapset.Set[string]
}

PropertiesChanged signals that some of the sender's properties have changed.

It corresponds to the org.freedesktop.DBus.Properties.PropertiesChanged signal.

func (*PropertiesChanged) SignatureDBus 

func (s *PropertiesChanged) SignatureDBus() Signature

func (*PropertiesChanged) UnmarshalDBus 

func (s *PropertiesChanged) UnmarshalDBus(ctx context.Context, d *fragments.Decoder) error

type PropertyDescription 

type PropertyDescription struct {
	Name string
	Type Signature

	// If true, Constant indicates that the property's value never
	// changes, and thus can safely be cached locally.
	Constant bool
	// Readable is whether the property value can be read using
	// Interface.GetProperty.
	Readable bool
	// Writable is whether the property value can be set using
	// Interface.SetProperty
	Writable bool

	// EmitsSignal is whether the property emits a PropertiesChanged
	// signal when updated.
	EmitsSignal bool
	// SignalIncludesValue is whether the PropertiesChanged signal
	// emitted when this property changes includes the new value. If
	// false, the signal merely reports that the property's value has
	// been invalidated, and the recipient must use
	// Interface.GetProperty to retrieve the updated value.
	SignalIncludesValue bool

	// Deprecated, if true, indicates that the property should be
	// avoided in new code.
	Deprecated bool
}

PropertyDescription describes a DBus property.

Property descriptions are provied by the DBus peer offering the property, and may not accurately reflect the actual property.

func (PropertyDescription) String 

func (p PropertyDescription) String() string

func (*PropertyDescription) UnmarshalXML 

func (p *PropertyDescription) UnmarshalXML(d *xml.Decoder, start xml.StartElement) error

type SignalDescription 

type SignalDescription struct {
	Name string
	Args []ArgumentDescription
	// Deprecated, if true, indicates that the signal should be
	// avoided in new code.
	Deprecated bool
}

SignalDescription describes a DBus signal.

Signal descriptions are provided by the DBus peer emitting the signal, and may not accurately reflect the received signal.

func (SignalDescription) String 

func (s SignalDescription) String() string

func (*SignalDescription) UnmarshalXML 

func (s *SignalDescription) UnmarshalXML(d *xml.Decoder, start xml.StartElement) error

type Signature 

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

A Signature describes the type of a DBus value.

func ParseSignature 

func ParseSignature(sig string) (Signature, error)

ParseSignature parses a DBus type signature string.

func SignatureFor 

func SignatureFor[T any]() (Signature, error)

SignatureFor returns the Signature for the given type.

func SignatureOf 

func SignatureOf(v any) (Signature, error)

SignatureOf returns the Signature of the given value.

func (Signature) IsZero 

func (s Signature) IsZero() bool

IsZero reports whether the signature is the zero value. A zero Signature describes a void value.

func (Signature) String 

func (s Signature) String() string

String returns the string encoding of the Signature, as described in the DBus specification.

func (Signature) Type 

func (s Signature) Type() reflect.Type

Type returns the reflect.Type the Signature represents.

If Signature.IsZero is true, Type returns nil.

type TypeError 

type TypeError struct {
	// Type is the name of the type that caused the error.
	Type string
	// Reason is an explanation of why the type isn't representable by
	// DBus.
	Reason error
}

TypeError is the error returned when a type cannot be represented in the DBus wire format.

func (TypeError) Error 

func (e TypeError) Error() string

func (TypeError) Unwrap 

func (e TypeError) Unwrap() error

type Unmarshaler 

type Unmarshaler interface {
	SignatureDBus() Signature
	UnmarshalDBus(ctx context.Context, d *fragments.Decoder) error
}

Unmarshaler is the interface implemented by types that can unmarshal themselves.

SignatureDBus is invoked on a zero value of the Unmarshaler, and must return a constant.

UnmarshalDBus must have a pointer receiver. If Unmarshal encounters an Unmarshaler whose UnmarshalDBus method takes a value receiver, it will return a TypeError.

UnmarshalDBus is responsible for consuming padding appropriate to the values being encoded, and for consuming input in a way that agrees with the output of SignatureDBus.

type Watcher 

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

A Watcher delivers notifications received from the bus that match its filters.

func (*Watcher) Chan 

func (w *Watcher) Chan() <-chan *Notification

Chan returns the channel on which notifications are delivered.

The caller must drain this channel of new notifications promptly, to avoid overflowing the Watcher's receive queue and losing notifications. Missing notifications due to an overflow are indicated by the Overflow field of the Notification that immediately precedes the discarded signal(s).

func (*Watcher) Close 

func (w *Watcher) Close()

Close shuts down the Watcher.

func (*Watcher) Match 

func (w *Watcher) Match(m *Match) (remove func() error, err error)

Match requests delivery of notifications that match the specification m.

Matches are additive: a notification is delivered if it matches any of the Watcher's match specifications.

If the match is added successfully, the returned remove function may be used to remove thee match without affecting other matches. Use of remove is optional, and may be ignored if the set of matches doesn't need to change for the lifetime of the Watcher.

Source Files

View all Source files

Directories

Path Synopsis
cmd
dbus
Package dbustest provides a helper to run an isolated bus instance in tests.
 Package dbustest provides a helper to run an isolated bus instance in tests.
package fragments provides low-level encoding and decoding helpers to construct and parse DBus message.
 package fragments provides low-level encoding and decoding helpers to construct and parse DBus message.
internal
dbusgen
transport

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.