Skip to main content

Crate rustsni

Crate rustsni 

Source
Expand description

A poll-friendly StatusNotifierItem host library built on rustbus.

This crate implements the host side of the StatusNotifierItem protocol (also known as the D-Bus system tray protocol). It acts as a StatusNotifierWatcher + StatusNotifierHost on the session bus, discovering tray items and providing their properties, icons, and menus — all without blocking.

§Architecture

The main entry point is TrayHost. It:

  1. Connects to the D-Bus session bus.
  2. Registers itself as org.kde.StatusNotifierWatcher (so tray items can register with it).
  3. Registers itself as org.freedesktop.StatusNotifierHost-{pid} (so items know a graphical shell is present).
  4. Scans for already-running items via ListNames and probes each unique bus name for SNI support (one per poll() call, non-blocking).

After construction, the caller hands the fd() to a poll/epoll loop. When the fd becomes readable, call poll() to process pending D-Bus messages and receive TrayEvents.

§Event flow

┌─────────────┐   poll()    ┌─────────────┐
│  TrayHost   │ ──────────► │  TrayEvent  │
│  (watcher)  │ ◄────────── │  Vec        │
└─────────────┘   events    └─────────────┘
       │
       │  methods (activate, context_menu, get_menu, scroll, …)
       ▼
┌─────────────┐
│  TrayItem   │
│  (on D-Bus) │
└─────────────┘

§Non-blocking / poll-friendly design

This library never spawns threads. All I/O is driven by the caller’s event loop:

  • fd() returns the D-Bus socket fd for poll/epoll.
  • poll() reads available messages without blocking and returns accumulated TrayEvents.
  • Item discovery probes are sent asynchronously (one per poll() call) with a 500 ms timeout and up to 3 retries.

§Interacting with tray items

Once an item is discovered (you receive TrayEvent::ItemAdded), you can:

§Platform

Linux only. Requires a running D-Bus session bus.

§Minimum supported Rust version

Rust 1.85 (edition 2024).

Structs§

IconPixmap
A decoded icon pixmap in native-endian ARGB32.
ItemId
A tray item’s unique identifier.
MenuItemProps
Properties for a single menu item as returned by TrayHost::get_menu_group_properties.
MenuNode
A node in the DBusMenu layout tree as returned by TrayHost::get_menu.
ToolTip
Tooltip data for a tray item.
TrayHost
A StatusNotifierWatcher + StatusNotifierHost on the D-Bus session bus.
TrayItem
Resolved properties of a StatusNotifierItem.

Enums§

Error
Errors returned by this library.
PropValue
An owned property value from the DBusMenu protocol.
TrayEvent
Events produced by TrayHost::poll().

Functions§

fire_menu_click
Fire a click event on a menu item using a standalone D-Bus connection.
from_tuples
Convert simple (width, height, &[u8]) tuples into IconPixmaps.

Type Aliases§

Result
Convenience alias for crate-level Result.