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: aStatusNotifierItemwith itscom.canonical.dbusmenumenu, the tray icon that GNOME (through the AppIndicator extension), KDE, and most panels show.launcher: the UnityLauncherEntrysignal 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
LauncherEntryprotocol: 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 theUpdatesignal and match it to the app by its desktop id. - sni
- A
StatusNotifierItemserver with itscom.canonical.dbusmenumenu: 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.
- Method
Call - A method call delivered to an exported object.
- Method
Error - A D-Bus error a handler answers with.
- Signal
Filter - Which signals a callback registered with
Connection::on_signalreceives. Unset fields match anything. This filters locally; the bus only sends signals a match rule asked for (Connection::add_match). - Subscription
Id - Identifies a signal subscription for
Connection::remove_signal_handler.
Enums§
- Error
- What can go wrong talking to the bus.
- Message
Type - 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::callwaits 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 RequestNameflag: let another connection take the name over.- NAME_
FLAG_ DO_ NOT_ QUEUE RequestNameflag: fail instead of waiting in the queue for the name.- NAME_
FLAG_ REPLACE_ EXISTING RequestNameflag: take the name over from an owner that allows replacement.- NAME_
REPLY_ ALREADY_ OWNER RequestNamereply: the caller already owned the name.- NAME_
REPLY_ EXISTS RequestNamereply: someone else owns the name and the caller did not queue.- NAME_
REPLY_ IN_ QUEUE RequestNamereply: the caller waits in the queue for the name.- NAME_
REPLY_ PRIMARY_ OWNER RequestNamereply: 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
PeerandIntrospectableinterfaces, theninterfaces(raw<interface>elements), then a<node>per child name. - is_
valid_ object_ path - Whether
pis a valid object path:/, or/-separated non-empty[A-Za-z0-9_]segments. - marshal
- Marshals
valuesas a little-endian body (offsets relative to an 8-aligned start). - unmarshal
- Unmarshals a body with signature
signaturefrombytes(little-endian unlessbig_endian), requiring every byte to be consumed.