Phosphor
Qt6 / Wayland library suite for window-management tools
Loading...
Searching...
No Matches
PhosphorConfig::HostDirectory Class Reference

The descriptors and the host record of one settings API. More...

#include <PhosphorConfig/HostDirectory.h>

Public Member Functions

 HostDirectory (QString api)
 api names the API, placement for the placement API.
QList< HostDescriptor > descriptors () const
 Every valid descriptor in the phosphor-works/<api>-hosts/ directories of the XDG data dirs, sorted by id.
QString recordPath () const
 $XDG_STATE_HOME/phosphor-works/<api>-host.json.
std::optional< HostRecord > record () const
 The record, or nullopt when there is none.
bool writeRecord (const QString &hostId, const QString &configPath, qint64 pid) const
 Record host hostId, keeping its settings in configPath, as this user's host of the API.

Static Public Member Functions

static HostResolution resolve (const QList< HostDescriptor > &descriptors, const std::optional< HostRecord > &record, qint64 busOwnerPid, const QStringList &currentDesktops)
 Choose a host.
static QStringList currentDesktops ()
 XDG_CURRENT_DESKTOP, split on :.

Detailed Description

The descriptors and the host record of one settings API.

A running host calls writeRecord() at start. The record stays after it stops, so a settings module knows which file this user last used. A settings module calls descriptors(), record() and resolve() to find the file to edit.

Constructor & Destructor Documentation

◆ HostDirectory()

PhosphorConfig::HostDirectory::HostDirectory ( QString api)
explicit

api names the API, placement for the placement API.

It must match [a-z0-9][a-z0-9-]*. Any other name is refused with a warning: descriptors() then finds nothing, recordPath() is empty and writeRecord() refuses.

Member Function Documentation

◆ currentDesktops()

QStringList PhosphorConfig::HostDirectory::currentDesktops ( )
staticnodiscard

XDG_CURRENT_DESKTOP, split on :.

◆ descriptors()

QList< HostDescriptor > PhosphorConfig::HostDirectory::descriptors ( ) const
nodiscard

Every valid descriptor in the phosphor-works/<api>-hosts/ directories of the XDG data dirs, sorted by id.

Only files named *.json, the extension in lower case, are read. Descriptors are keyed by the Id inside the file, and the file name is not checked against it. A per-user descriptor overrides a system one with the same id, and of two in one directory the first in file name order is kept. Invalid ones, and directories that cannot be read, are skipped with a warning.

◆ record()

std::optional< HostRecord > PhosphorConfig::HostDirectory::record ( ) const
nodiscard

The record, or nullopt when there is none.

A record is ignored with a warning unless its Host is a valid id, its ConfigPath is absolute with no .. segment and no ASCII control character, its Pid is a non-negative integer and its Written is an ISO date.

◆ recordPath()

QString PhosphorConfig::HostDirectory::recordPath ( ) const
nodiscard

$XDG_STATE_HOME/phosphor-works/<api>-host.json.

Empty when the state directory is not absolute or the API name was refused: record() then finds nothing and writeRecord() refuses.

◆ resolve()

HostResolution PhosphorConfig::HostDirectory::resolve ( const QList< HostDescriptor > & descriptors,
const std::optional< HostRecord > & record,
qint64 busOwnerPid,
const QStringList & currentDesktops )
staticnodiscard

Choose a host.

The first of these that applies decides:

  1. the running host's own record: the record was written by the process that owns the bus name now (busOwnerPid, 0 when the name has no owner). It wins whatever the desktop.
  2. a user's choice: a record with pid 0 whose host serves this session, whether or not anything owns the name
  3. a host's record: a record with any other pid, when nothing owns the name and its host serves this session
  4. the one descriptor whose desktops match currentDesktops
  5. none. candidates lists every descriptor that matches, for the user to choose from. It is empty when no descriptor matches. A record's host serves this session when one of currentDesktops is among its desktops, ignoring case. A host that declares no desktops serves every session for this purpose, and an empty currentDesktops is served by every host. The desktop match is stricter: it never chooses or offers a descriptor without desktops, and it matches nothing when currentDesktops is empty. A record naming a host with no descriptor is ignored. So is a host's record while another process owns the name. Pid equality is the only link between the record and the bus owner: nothing else ties the process that owns the name to the host the record names.

The two pids are counted in different places. The record holds the writer's own pid (its getpid()), while busOwnerPid is what the bus reports (GetConnectionUnixProcessID), which the bus takes from the kernel's peer credentials and so counts in the bus's own pid namespace. For a host in another pid namespace (a container, or a Flatpak sandbox, whose bus traffic also passes through a proxy process) the two never agree. Rule 1 then never applies, the running host's own record is read as one written by another process and ignored, and the choice falls to rule 4. This is a limit of the pid link, not something resolve() corrects. busOwnerPid is the owner of one bus name, so the descriptors of one API are expected to share HostDescriptor::busName.

◆ writeRecord()

bool PhosphorConfig::HostDirectory::writeRecord ( const QString & hostId,
const QString & configPath,
qint64 pid ) const
nodiscard

Record host hostId, keeping its settings in configPath, as this user's host of the API.

A running host passes its own pid at start; a user's choice between hosts passes 0 and the descriptor's resolvedConfigPath(). Refused when hostId is not a valid id, configPath is not absolute or has a .. segment or an ASCII control character, or pid is negative. The path is stored cleaned.


The documentation for this class was generated from the following file: