Skip to main content

Module dbus

Module dbus 

Source
Expand description

Session bus transport, status items, launchers, and single-instance coordination. day-platform-linux: a std-only client for the freedesktop session bus.

The crate speaks the D-Bus wire protocol directly: little-endian marshaling (and reading of both byte orders), SASL EXTERNAL authentication over a unix socket, Hello, and one background reader thread per Connection that routes replies to blocked callers, signals to subscribers and method calls to exported objects. There is no async runtime, no libdbus and no zbus; everything is std.

On top of the connection sit two small servers the Linux backends share:

  • sni: a StatusNotifierItem with its com.canonical.dbusmenu menu, the tray icon that GNOME (through the AppIndicator extension), KDE, and most panels show.
  • launcher: the Unity LauncherEntry signal that docks read for a badge count, progress, and urgency.

Only unix transports exist (unix:path= and, on Linux, unix:abstract=). Elsewhere the crate still compiles, and Connection::session returns Error::Unsupported.

§Threads

Exported handlers and signal callbacks run on the connection’s reader thread. A blocking Connection::call made from that thread would wait for a reply only that thread can read, so it returns Error::ReaderThread instead; use Connection::call_no_reply or hand the work to another thread.

Modules§

instance
Single-instance apps over the session bus, for backends whose toolkit does not provide it (GTK has GApplication; Qt has nothing).
launcher
The Unity LauncherEntry protocol: a badge count, a progress bar and an urgency flag on the app’s dock or launcher icon. Docks (Ubuntu Dock, Dash to Dock, Plasma’s task manager, Latte, Plank) listen for the Update signal and match it to the app by its desktop id.
sni
A StatusNotifierItem server with its com.canonical.dbusmenu menu: the Linux status item (“tray icon”) that KDE Plasma, GNOME with the AppIndicator extension, Xfce, LXQt, Budgie, Cinnamon and the wlroots bars (waybar, …) display.

Structs§

Connection
A connection to a message bus. Cloning is cheap and every clone shares the socket and the reader thread; the socket closes when the last clone drops (or on close).
Message
One D-Bus message: the header fields this crate understands plus the body. The body’s signature is the concatenation of its values’ signatures.
MethodCall
A method call delivered to an exported object.
MethodError
A D-Bus error a handler answers with.
SignalFilter
Which signals a callback registered with Connection::on_signal receives. Unset fields match anything. This filters locally; the bus only sends signals a match rule asked for (Connection::add_match).
SubscriptionId
Identifies a signal subscription for Connection::remove_signal_handler.

Enums§

Error
What can go wrong talking to the bus.
MessageType
The four kinds of D-Bus message.
Value
One D-Bus value. Containers carry enough type information to marshal even when empty: an array names its element signature.

Constants§

BUS_INTERFACE
The bus daemon’s interface (Hello, RequestName, AddMatch, …).
BUS_NAME
The bus daemon’s own name, object path and interface.
BUS_PATH
The bus daemon’s object path.
DEFAULT_TIMEOUT
How long Connection::call waits for a reply.
FLAG_NO_AUTO_START
Message flag: the bus must not start a service to deliver the message.
FLAG_NO_REPLY_EXPECTED
Message flag: the sender does not want a reply.
INTROSPECTABLE_INTERFACE
The standard introspection interface (Introspect).
NAME_FLAG_ALLOW_REPLACEMENT
RequestName flag: let another connection take the name over.
NAME_FLAG_DO_NOT_QUEUE
RequestName flag: fail instead of waiting in the queue for the name.
NAME_FLAG_REPLACE_EXISTING
RequestName flag: take the name over from an owner that allows replacement.
NAME_REPLY_ALREADY_OWNER
RequestName reply: the caller already owned the name.
NAME_REPLY_EXISTS
RequestName reply: someone else owns the name and the caller did not queue.
NAME_REPLY_IN_QUEUE
RequestName reply: the caller waits in the queue for the name.
NAME_REPLY_PRIMARY_OWNER
RequestName reply: the caller now owns the name.
PEER_INTERFACE
The standard peer interface (Ping, GetMachineId), answered by every connection.
PROPERTIES_INTERFACE
The standard properties interface (Get, GetAll, Set).

Functions§

introspection_xml
An introspection document: the standard Peer and Introspectable interfaces, then interfaces (raw <interface> elements), then a <node> per child name.
is_valid_object_path
Whether p is a valid object path: /, or /-separated non-empty [A-Za-z0-9_] segments.
marshal
Marshals values as a little-endian body (offsets relative to an 8-aligned start).
unmarshal
Unmarshals a body with signature signature from bytes (little-endian unless big_endian), requiring every byte to be consumed.