From b17a5f852c12b653fe892948ed2ead421f57ed97 Mon Sep 17 00:00:00 2001 From: Thiago Macieira Date: Wed, 3 Nov 2010 14:59:26 +0100 Subject: Documentated autolaunch implementation for X Windowing system. --- doc/dbus-specification.xml | 225 +++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 217 insertions(+), 8 deletions(-) (limited to 'doc') diff --git a/doc/dbus-specification.xml b/doc/dbus-specification.xml index 69be6fef..0f83f7e0 100644 --- a/doc/dbus-specification.xml +++ b/doc/dbus-specification.xml @@ -3,12 +3,11 @@ "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [ ]> -
D-Bus Specification - Version 0.14 - May 12, 2010 + Version 0.15 + 3 November 2010 Havoc @@ -3696,11 +3695,221 @@ The environment variable should have precedence over the root window property. - - [FIXME specify location of .service files, probably using - DESKTOP_DIRS etc. from basedir specification, though login session - bus is not really desktop-specific] - + The address of the login session message bus is given in the + DBUS_SESSION_BUS_ADDRESS environment variable. If + DBUS_SESSION_BUS_ADDRESS is not set, or if it's set to the string + "autolaunch:", the system should use platform-specific methods of + locating a running D-Bus session server, or starting one if a running + instance cannot be found. Note that this mechanism is not recommended + for attempting to determine if a daemon is running. It is inherently + racy to attempt to make this determination, since the bus daemon may + be started just before or just after the determination is made. + Therefore, it is recommended that applications do not try to make this + determination for their functionality purposes, and instead they + should attempt to start the server. + + + X Windowing System + + For the X Windowing System, the application must locate the + window owner of the selection represented by the atom formed by + concatenating: + + + the literal string "_DBUS_SESSION_BUS_SELECTION_" + + + + the current user's username + + + + the literal character '_' (underscore) + + + + the machine's ID + + + + + + The following properties are defined for the window that owns + this X selection: + + + + + + Atom + + + + meaning + + + + + + _DBUS_SESSION_BUS_ADDRESS + + + + the actual address of the server socket + + + + + + _DBUS_SESSION_BUS_PID + + + + the PID of the server process + + + + + + + + + At least the _DBUS_SESSION_BUS_ADDRESS property MUST be + present in this window. + + + + If the X selection cannot be located or if reading the + properties from the window fails, the implementation MUST conclude + that there is no D-Bus server running and proceed to start a new + server. (See below on concurrency issues) + + + + Failure to connect to the D-Bus server address thus obtained + MUST be treated as a fatal connection error and should be reported + to the application. + + + + As an alternative, an implementation MAY find the information + in the following file located in the current user's home directory, + in subdirectory .dbus/session-bus/: + + + the machine's ID + + + + the literal character '-' (dash) + + + + the X display without the screen number, with the + following prefixes removed, if present: ":", "localhost:" + ."localhost.localdomain:". That is, a display of + "localhost:10.0" produces just the number "10" + + + + + + The contents of this file NAME=value assignment pairs and + lines starting with # are comments (no comments are allowed + otherwise). The following variable names are defined: + + + + + + Variable + + + + meaning + + + + + + DBUS_SESSION_BUS_ADDRESS + + + + the actual address of the server socket + + + + + + DBUS_SESSION_BUS_PID + + + + the PID of the server process + + + + + + DBUS_SESSION_BUS_WINDOWID + + + + the window ID + + + + + + + + + At least the DBUS_SESSION_BUS_ADDRESS variable MUST be present + in this file. + + + + Failure to open this file MUST be interpreted as absence of a + running server. Therefore, the implementation MUST proceed to + attempting to launch a new bus server if the file cannot be + opened. + + + + However, success in opening this file MUST NOT lead to the + conclusion that the server is running. Thus, a failure to connect to + the bus address obtained by the alternative method MUST NOT be + considered a fatal error. If the connection cannot be established, + the implementation MUST proceed to check the X selection settings or + to start the server on its own. + + + + If the implementation concludes that the D-Bus server is not + running it MUST attempt to start a new server and it MUST also + ensure that the daemon started as an effect of the "autolaunch" + mechanism provides the lookup mechanisms described above, so + subsequent calls can locate the newly started server. The + implementation MUST also ensure that if two or more concurrent + initiations happen, only one server remains running and all other + initiations are able to obtain the address of this server and + connect to it. In other words, the implementation MUST ensure that + the X selection is not present when it attempts to set it, without + allowing another process to set the selection between the + verification and the setting (e.g., by using XGrabServer / + XungrabServer). + + + + + + [FIXME specify location of .service files, probably using + DESKTOP_DIRS etc. from basedir specification, though login session + bus is not really desktop-specific] + + System message bus -- cgit v1.2.3