fdo-mirrors/dbus
1
0
Fork 0
mirror of https://gitlab.freedesktop.org/dbus/dbus.git synced 2026-01-05 19:30:19 +01:00
Code Issues Projects Releases Packages Wiki Activity Actions

spec: Have a sect2 per interface documented for the message bus

Browse source 
Previously, we arbitrarily divided o.fd.DBus into "messages"
(methods and signals), in one sect2, and Properties, in another sect2;
and for the only extended interface that is documented so far,
o.fd.DBus.Monitoring, we included its single method in the list of
o.fd.DBus methods.

This is putting too much weight on implementation details of how the
D-Bus protocol is implemented (with Properties being "less core" than
methods and signals), and not enough weight on how interfaces are
conceptually structured. It's more usual to group together all aspects
of an interface into one document or section, and the current arbitrary
separation is going to look more and more odd as we start documenting
more interfaces like Containers (dbus!449), Stats and Verbose.

Instead, repurpose the "Message Bus Messages" section to become the
documentation for the o.fd.DBus interface, and introduce a separate
section for each other interface that the message bus provides.
Each one contains a full list of methods, signals and properties (if any)
if it is specific to the message bus, or a cross-reference to a more
generic interface description if it is equally applicable to the message
bus and its clients.

Prompted by discussion on dbus!449.

Signed-off-by: Simon McVittie <smcv@collabora.com>
This commit is contained in:
Simon McVittie 2024-09-25 17:56:18 +01:00
parent a36d0e1cdb
commit bafb2c455d
1 changed files with 160 additions and 138 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

298
doc/dbus-specification.xml
View file

@ -5858,11 +5858,12 @@
</sect2>
<sect2 id="message-bus-messages">
<title>Message Bus Messages</title>
<title>Message Bus Interface: <literal>org.freedesktop.DBus</literal></title>
<para>
The special message bus name <literal>org.freedesktop.DBus</literal>
responds to a number of additional messages at the object path
<literal>/org/freedesktop/DBus</literal>.
<literal>/org/freedesktop/DBus</literal>,
implementing the <literal>org.freedesktop.DBus</literal> interface.
That object path is also used when emitting signals such as
<link linkend='bus-messages-name-owner-changed'>NameOwnerChanged</link>.
</para>
@ -5882,19 +5883,8 @@
instead of relying on this.
</para>
<para>
In addition to the method calls listed below, the message bus
should implement the standard
<link linkend="standard-interfaces-introspectable">Introspectable</link>,
<link linkend="standard-interfaces-peer">Peer</link> and
<link linkend="standard-interfaces-properties">Properties</link>
interfaces.
Support for the Properties and Peer interfaces was added in version
1.11.x of the reference implementation of the message bus.
</para>
<sect3 id="bus-messages-hello">
<title><literal>org.freedesktop.DBus.Hello</literal></title>
<title>Method: <literal>org.freedesktop.DBus.Hello</literal></title>
<para>
As a method:
<programlisting>
@ -5937,7 +5927,7 @@
</sect3>
<sect3 id="bus-messages-request-name">
<title><literal>org.freedesktop.DBus.RequestName</literal></title>
<title>Method: <literal>org.freedesktop.DBus.RequestName</literal></title>
<para>
As a method:
<programlisting>
@ -6175,7 +6165,7 @@
</sect3>
<sect3 id="bus-messages-release-name">
<title><literal>org.freedesktop.DBus.ReleaseName</literal></title>
<title>Method: <literal>org.freedesktop.DBus.ReleaseName</literal></title>
<para>
As a method:
<programlisting>
@ -6268,7 +6258,7 @@
</sect3>
<sect3 id="bus-messages-list-queued-owners">
<title><literal>org.freedesktop.DBus.ListQueuedOwners</literal></title>
<title>Method: <literal>org.freedesktop.DBus.ListQueuedOwners</literal></title>
<para>
As a method:
<programlisting>
@ -6322,7 +6312,7 @@
</sect3>
<sect3 id="bus-messages-list-names">
<title><literal>org.freedesktop.DBus.ListNames</literal></title>
<title>Method: <literal>org.freedesktop.DBus.ListNames</literal></title>
<para>
As a method:
<programlisting>
@ -6353,7 +6343,7 @@
</para>
</sect3>
<sect3 id="bus-messages-list-activatable-names">
<title><literal>org.freedesktop.DBus.ListActivatableNames</literal></title>
<title>Method: <literal>org.freedesktop.DBus.ListActivatableNames</literal></title>
<para>
As a method:
<programlisting>
@ -6384,7 +6374,7 @@
</para>
</sect3>
<sect3 id="bus-messages-name-exists">
<title><literal>org.freedesktop.DBus.NameHasOwner</literal></title>
<title>Method: <literal>org.freedesktop.DBus.NameHasOwner</literal></title>
<para>
As a method:
<programlisting>
@ -6435,7 +6425,7 @@
</sect3>
<sect3 id="bus-messages-name-owner-changed">
<title><literal>org.freedesktop.DBus.NameOwnerChanged</literal></title>
<title>Signal: <literal>org.freedesktop.DBus.NameOwnerChanged</literal></title>
<para>
This is a signal:
<programlisting>
@ -6478,7 +6468,7 @@
</para>
</sect3>
<sect3 id="bus-messages-name-lost">
<title><literal>org.freedesktop.DBus.NameLost</literal></title>
<title>Signal: <literal>org.freedesktop.DBus.NameLost</literal></title>
<para>
This is a signal:
<programlisting>
@ -6511,7 +6501,7 @@
</sect3>
<sect3 id="bus-messages-name-acquired">
<title><literal>org.freedesktop.DBus.NameAcquired</literal></title>
<title>Signal: <literal>org.freedesktop.DBus.NameAcquired</literal></title>
<para>
This is a signal:
<programlisting>
@ -6544,7 +6534,7 @@
</sect3>
<sect3 id="bus-messages-activatable-services-changed">
<title><literal>org.freedesktop.DBus.ActivatableServicesChanged</literal></title>
<title>Signal: <literal>org.freedesktop.DBus.ActivatableServicesChanged</literal></title>
<para>
This is a signal:
<programlisting>
@ -6570,7 +6560,7 @@
</sect3>
<sect3 id="bus-messages-start-service-by-name">
<title><literal>org.freedesktop.DBus.StartServiceByName</literal></title>
<title>Method: <literal>org.freedesktop.DBus.StartServiceByName</literal></title>
<para>
As a method:
<programlisting>
@ -6671,7 +6661,7 @@
</sect3>
<sect3 id="bus-messages-update-activation-environment">
<title><literal>org.freedesktop.DBus.UpdateActivationEnvironment</literal></title>
<title>Method: <literal>org.freedesktop.DBus.UpdateActivationEnvironment</literal></title>
<para>
As a method:
<programlisting>
@ -6708,7 +6698,7 @@
</sect3>
<sect3 id="bus-messages-get-name-owner">
<title><literal>org.freedesktop.DBus.GetNameOwner</literal></title>
<title>Method: <literal>org.freedesktop.DBus.GetNameOwner</literal></title>
<para>
As a method:
<programlisting>
@ -6759,7 +6749,7 @@
</sect3>
<sect3 id="bus-messages-get-connection-unix-user">
<title><literal>org.freedesktop.DBus.GetConnectionUnixUser</literal></title>
<title>Method: <literal>org.freedesktop.DBus.GetConnectionUnixUser</literal></title>
<para>
As a method:
<programlisting>
@ -6812,7 +6802,7 @@
</sect3>
<sect3 id="bus-messages-get-connection-unix-process-id">
<title><literal>org.freedesktop.DBus.GetConnectionUnixProcessID</literal></title>
<title>Method: <literal>org.freedesktop.DBus.GetConnectionUnixProcessID</literal></title>
<para>
As a method:
<programlisting>
@ -6865,7 +6855,7 @@
</sect3>
<sect3 id="bus-messages-get-connection-credentials">
<title><literal>org.freedesktop.DBus.GetConnectionCredentials</literal></title>
<title>Method: <literal>org.freedesktop.DBus.GetConnectionCredentials</literal></title>
<para>
As a method:
<programlisting>
@ -7049,7 +7039,7 @@
</sect3>
<sect3 id="bus-messages-get-adt-audit-session-data">
<title><literal>org.freedesktop.DBus.GetAdtAuditSessionData</literal></title>
<title>Method: <literal>org.freedesktop.DBus.GetAdtAuditSessionData</literal></title>
<para>
As a method:
<programlisting>
@ -7107,7 +7097,7 @@
</sect3>
<sect3 id="bus-messages-get-connection-selinux-security-context">
<title><literal>org.freedesktop.DBus.GetConnectionSELinuxSecurityContext</literal></title>
<title>Method: <literal>org.freedesktop.DBus.GetConnectionSELinuxSecurityContext</literal></title>
<para>
As a method:
<programlisting>
@ -7166,7 +7156,7 @@
<sect3 id="bus-messages-add-match">
<title><literal>org.freedesktop.DBus.AddMatch</literal></title>
<title>Method: <literal>org.freedesktop.DBus.AddMatch</literal></title>
<para>
As a method:
<programlisting>
@ -7197,7 +7187,7 @@
</para>
</sect3>
<sect3 id="bus-messages-remove-match">
<title><literal>org.freedesktop.DBus.RemoveMatch</literal></title>
<title>Method: <literal>org.freedesktop.DBus.RemoveMatch</literal></title>
<para>
As a method:
<programlisting>
@ -7229,7 +7219,7 @@
</sect3>
<sect3 id="bus-messages-get-id">
<title><literal>org.freedesktop.DBus.GetId</literal></title>
<title>Method: <literal>org.freedesktop.DBus.GetId</literal></title>
<para>
As a method:
<programlisting>
@ -7264,109 +7254,8 @@
</para>
</sect3>
<sect3 id="bus-messages-become-monitor">
<title><literal>org.freedesktop.DBus.Monitoring.BecomeMonitor</literal></title>
<para>
As a method:
<programlisting>
BecomeMonitor (in ARRAY of STRING rule, in UINT32 flags)
</programlisting>
Message arguments:
<informaltable>
<tgroup cols="3">
<thead>
<row>
<entry>Argument</entry>
<entry>Type</entry>
<entry>Description</entry>
</row>
</thead>
<tbody>
<row>
<entry>0</entry>
<entry>ARRAY of STRING</entry>
<entry>Match rules to add to the connection</entry>
</row>
<row>
<entry>1</entry>
<entry>UINT32</entry>
<entry>Not used, must be 0</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</para>
<para>
Converts the connection into a <emphasis>monitor
connection</emphasis> which can be used as a debugging/monitoring
tool. Only a user who is privileged on this
bus (by some implementation-specific definition) may create
monitor connections<footnote>
<para>
In the reference implementation,
the default configuration is that each user (identified by
numeric user ID) may monitor their own session bus,
and the root user (user ID zero) may monitor the
system bus.
</para>
</footnote>.
</para>
<para>
Monitor connections lose all their bus names, including the unique
connection name, and all their match rules. Sending messages on a
monitor connection is not allowed: applications should use a private
connection for monitoring.
</para>
<para>
Monitor connections may receive all messages, even messages that
should only have gone to some other connection ("eavesdropping").
The first argument is a list of match rules, which replace any
match rules that were previously active for this connection.
These match rules are always treated as if they contained the
special <literal>eavesdrop='true'</literal> member.
</para>
<para>
As a special case, an empty list of match rules (which would
otherwise match nothing, making the monitor useless) is treated
as a shorthand for matching all messages.
</para>
<para>
The second argument might be used for flags to influence the
behaviour of the monitor connection in future D-Bus versions.
</para>
<para>
Message bus implementations should attempt to minimize the
side-effects of monitoring — in particular, unlike ordinary
eavesdropping, monitoring the system bus does not require the
access control rules to be relaxed, which would change the set
of messages that can be delivered to their (non-monitor)
destinations. However, it is unavoidable that monitoring
will increase the message bus's resource consumption. In
edge cases where there was barely enough time or memory without
monitoring, this might result in message deliveries failing
when they would otherwise have succeeded.
</para>
</sect3>
</sect2>
<sect2 id="message-bus-properties">
<title>Message Bus Properties</title>
<para>
The special message bus name <literal>org.freedesktop.DBus</literal>
exports several properties (see
<xref linkend="standard-interfaces-properties"/>) on the object path
<literal>/org/freedesktop/DBus</literal>.
</para>
<sect3 id="message-bus-properties-features">
<title><literal>org.freedesktop.DBus.Features</literal></title>
<title>Property: <literal>org.freedesktop.DBus.Features</literal></title>
<para>
As a property:
<programlisting>
@ -7471,7 +7360,7 @@
</sect3>
<sect3 id="message-bus-properties-interfaces">
<title><literal>org.freedesktop.DBus.Interfaces</literal></title>
<title>Property: <literal>org.freedesktop.DBus.Interfaces</literal></title>
<para>
As a property:
<programlisting>
@ -7503,6 +7392,139 @@
</sect3>
</sect2>
<sect2>
<title>Message Bus Introspection</title>
<para>
The message bus should implement the standard
<link linkend="standard-interfaces-introspectable">Introspectable</link>
interface.
</para>
</sect2>
<sect2>
<title>Message Bus as a Peer</title>
<para>
The message bus should implement the standard
<link linkend="standard-interfaces-peer">Peer</link> interface.
Support for the Peer interface was added in version
1.11.x of the reference implementation of the message bus.
</para>
</sect2>
<sect2 id="message-bus-properties">
<title>Message Bus Properties</title>
<para>
The message bus should implement the standard
<link linkend="standard-interfaces-properties">Properties</link>
interface on the object path
<literal>/org/freedesktop/DBus</literal>.
The specific properties to be provided are documented as part of
their respective interfaces.
Support for the Properties interface was added in version
1.11.x of the reference implementation of the message bus.
</para>
</sect2>
<sect2 id="message-bus-monitoring-interface">
<title>Monitoring Interface: <literal>org.freedesktop.DBus.Monitoring</literal></title>
<para>
The special message bus name <literal>org.freedesktop.DBus</literal>
may optionally implement the
<literal>org.freedesktop.DBus.Monitoring</literal> interface on
the object path <literal>/org/freedesktop/DBus</literal>.
</para>
<sect3 id="bus-messages-become-monitor">
<title>Method: <literal>org.freedesktop.DBus.Monitoring.BecomeMonitor</literal></title>
<para>
As a method:
<programlisting>
BecomeMonitor (in ARRAY of STRING rule, in UINT32 flags)
</programlisting>
Message arguments:
<informaltable>
<tgroup cols="3">
<thead>
<row>
<entry>Argument</entry>
<entry>Type</entry>
<entry>Description</entry>
</row>
</thead>
<tbody>
<row>
<entry>0</entry>
<entry>ARRAY of STRING</entry>
<entry>Match rules to add to the connection</entry>
</row>
<row>
<entry>1</entry>
<entry>UINT32</entry>
<entry>Not used, must be 0</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</para>
<para>
Converts the connection into a <emphasis>monitor
connection</emphasis> which can be used as a debugging/monitoring
tool. Only a user who is privileged on this
bus (by some implementation-specific definition) may create
monitor connections<footnote>
<para>
In the reference implementation,
the default configuration is that each user (identified by
numeric user ID) may monitor their own session bus,
and the root user (user ID zero) may monitor the
system bus.
</para>
</footnote>.
</para>
<para>
Monitor connections lose all their bus names, including the unique
connection name, and all their match rules. Sending messages on a
monitor connection is not allowed: applications should use a private
connection for monitoring.
</para>
<para>
Monitor connections may receive all messages, even messages that
should only have gone to some other connection ("eavesdropping").
The first argument is a list of match rules, which replace any
match rules that were previously active for this connection.
These match rules are always treated as if they contained the
special <literal>eavesdrop='true'</literal> member.
</para>
<para>
As a special case, an empty list of match rules (which would
otherwise match nothing, making the monitor useless) is treated
as a shorthand for matching all messages.
</para>
<para>
The second argument might be used for flags to influence the
behaviour of the monitor connection in future D-Bus versions.
</para>
<para>
Message bus implementations should attempt to minimize the
side-effects of monitoring — in particular, unlike ordinary
eavesdropping, monitoring the system bus does not require the
access control rules to be relaxed, which would change the set
of messages that can be delivered to their (non-monitor)
destinations. However, it is unavoidable that monitoring
will increase the message bus's resource consumption. In
edge cases where there was barely enough time or memory without
monitoring, this might result in message deliveries failing
when they would otherwise have succeeded.
</para>
</sect3>
</sect2>
</sect1>
<!--
<appendix id="implementation-notes">