vasilito
9f2de2a0b1
Docs:
- Baseline was stated as 0.3.1 across the canonical set while the branch,
Cat 0/1 crates and every Cat 2 fork are 0.3.2. AGENTS.md also cited a
sources/redbear-0.3.1/ archive that does not exist; the only archive
present is sources/redbear-0.1.0/. Versioning examples now match the
forks as they actually stand (redoxfs/syscall 0.9.1, libredox 0.1.19).
- Repaired 18 instances of 'immutable archived' across 8 documents, where
a global find/replace had turned sync/synced/archived into that phrase
and produced ungrammatical text ('never auto-immutable archived',
'### Source immutable archived').
- Settled the apply-patches.sh contradiction empirically. Both sides were
wrong: the GROSS WARNING blocks (x5) described it as routine
patch-linking, and SCRIPT-BEHAVIOR-MATRIX.md said build-redbear.sh
'never invokes' it. It is invoked at build-redbear.sh:487, but only to
auto-repair a failed verify-overlay-integrity.sh check.
- Dropped the dangling reference to a local/AGENTS.md section
'NO OVERLAY-STYLE PATCHES — SCOPED POLICY' that does not exist.
Build system:
- mk/prefix.mk hardcoded 13.2.0 in the limits.h removal, which silently
no-ops after a toolchain upgrade and leaves the conflicting header.
Version-globbed.
- Parameterized GCC_RECIPE so the from-source toolchain path is not
pinned to gcc13.
- The three cstdlib strtold seds were not idempotent -- the shipped GCC
13 toolchain carried that comment block 17 times from repeated
'make prefix' runs. Each is now guarded.
68 lines
4.1 KiB
Markdown
68 lines
4.1 KiB
Markdown
# redbear-statusnotifierwatcher — D-Bus Interface
|
|
|
|
**Bus:** session
|
|
**Well-known name:** `org.kde.StatusNotifierWatcher`
|
|
**Object paths:**
|
|
- `/StatusNotifierWatcher` — Watcher object
|
|
|
|
## Interface: `org.kde.StatusNotifierWatcher`
|
|
|
|
### Methods
|
|
|
|
| Method | Signature | Description |
|
|
|--------|-----------|-------------|
|
|
| `RegisterStatusNotifierItem` | `(item: s) → ()` | Register a status notifier item. The `item` parameter is either a full object path (e.g. `/org/example/Item`) or a bus name (e.g. `:1.42` or `org.example.App`). Object paths from different senders are deduplicated by prepending the sender's unique bus name. Emits `StatusNotifierItemRegistered`. |
|
|
| `UnregisterStatusNotifierItem` | `(item: s) → ()` | Unregister a previously-registered item. Only the original owning sender can unregister. Emits `StatusNotifierItemUnregistered`. |
|
|
| `RegisterStatusNotifierHost` | `(host: s) → ()` | Register a status notifier host (typically the system tray panel). Emits `StatusNotifierHostRegistered`. |
|
|
| `UnregisterStatusNotifierHost` | `(host: s) → ()` | Unregister a status notifier host. Only the original owning sender can unregister. |
|
|
|
|
### Properties
|
|
|
|
| Property | Type | Description |
|
|
|----------|------|-------------|
|
|
| `RegisteredStatusNotifierItems` | `as` | Read-only list of registered item bus names/paths |
|
|
| `IsStatusNotifierHostRegistered` | `b` | Read-only: true if at least one host is registered |
|
|
| `ProtocolVersion` | `i` | Always `0` (per KDE spec) |
|
|
|
|
### Signals
|
|
|
|
| Signal | Signature | Description |
|
|
|--------|-----------|-------------|
|
|
| `StatusNotifierItemRegistered` | `(service: s)` | A new status notifier item was registered |
|
|
| `StatusNotifierItemUnregistered` | `(service: s)` | A status notifier item was unregistered |
|
|
| `StatusNotifierHostRegistered` | `() → ()` | A new status notifier host was registered |
|
|
| `StatusNotifierHostUnregistered` | `() → ()` | A status notifier host was unregistered |
|
|
|
|
## Ownership and Deduplication
|
|
|
|
- Each registration is owned by the caller's unique bus name (from the D-Bus message header).
|
|
- Object paths (values starting with `/`) are namespaced by sender: `:1.42/StatusNotifierItem` is distinct from `:1.99/StatusNotifierItem`. The display value (via `RegisteredStatusNotifierItems` property and signals) strips the owner prefix.
|
|
- Bus names (values not starting with `/`) are treated as-is — the first registration wins.
|
|
- Only the owning sender can unregister its own entries. Calling `Unregister` with the wrong sender is a silent no-op.
|
|
- Maximum 1024 entries per registry (items and hosts independently bounded). Oldest-first eviction when full.
|
|
|
|
## NameOwnerChanged Listener
|
|
|
|
A background task subscribes to `org.freedesktop.DBus.NameOwnerChanged` signals on the session bus. When a unique bus name (starting with `:`) releases its bus name (new owner is empty), all items and hosts owned by that sender are purged and the appropriate unregistration signals are emitted.
|
|
|
|
Well-known name releases (e.g. `org.example.App` losing its bus name) do NOT trigger automatic purge — only unique name (`:1.N`) releases do. This matches KDE spec behavior.
|
|
|
|
## Input Validation
|
|
|
|
All registration values are validated:
|
|
- Must be non-empty
|
|
- Maximum length 256 characters
|
|
- Must not contain NUL or other control characters (including C0/C1 control codes and Unicode format chars)
|
|
- Invalid values are rejected with `org.freedesktop.DBus.Error.InvalidArgs`
|
|
|
|
## Connection
|
|
|
|
- Session bus (`ConnectionBuilder::session()`)
|
|
- Waits up to 6 s for `DBUS_SESSION_BUS_ADDRESS` env var to be set (30 polls at 200 ms)
|
|
- Registers well-known name on session bus
|
|
- SIGTERM/Ctrl-C handler for clean shutdown
|
|
|
|
## References
|
|
- [KDE StatusNotifierItem Specification](https://www.freedesktop.org/wiki/Specifications/StatusNotifierItem/)
|
|
- Conformance: Full StatusNotifierWatcher implementation. Owner-keyed item/host tracking with canonical deduplication. NameOwnerChanged-based auto-purge for vanished unique bus names. Bounded registries with deterministic eviction. Input validation. All four registration/unregistration methods, three properties, and all four signals.
|