From: Simon McVittie Date: Wed, 25 Sep 2024 16:56:18 +0000 (+0100) Subject: spec: Have a sect2 per interface documented for the message bus X-Git-Tag: dbus-1.15.12~15^2~3 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=bafb2c455d97a3377356bf8efeeb4ddd834be6e6;p=thirdparty%2Fdbus.git spec: Have a sect2 per interface documented for the message bus 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 --- diff --git a/doc/dbus-specification.xml b/doc/dbus-specification.xml index c2736d305..134dfa2d4 100644 --- a/doc/dbus-specification.xml +++ b/doc/dbus-specification.xml @@ -5858,11 +5858,12 @@ - Message Bus Messages + Message Bus Interface: <literal>org.freedesktop.DBus</literal> The special message bus name org.freedesktop.DBus responds to a number of additional messages at the object path - /org/freedesktop/DBus. + /org/freedesktop/DBus, + implementing the org.freedesktop.DBus interface. That object path is also used when emitting signals such as NameOwnerChanged. @@ -5882,19 +5883,8 @@ instead of relying on this. - - In addition to the method calls listed below, the message bus - should implement the standard - Introspectable, - Peer and - Properties - interfaces. - Support for the Properties and Peer interfaces was added in version - 1.11.x of the reference implementation of the message bus. - - - <literal>org.freedesktop.DBus.Hello</literal> + Method: <literal>org.freedesktop.DBus.Hello</literal> As a method: @@ -5937,7 +5927,7 @@ - <literal>org.freedesktop.DBus.RequestName</literal> + Method: <literal>org.freedesktop.DBus.RequestName</literal> As a method: @@ -6175,7 +6165,7 @@ - <literal>org.freedesktop.DBus.ReleaseName</literal> + Method: <literal>org.freedesktop.DBus.ReleaseName</literal> As a method: @@ -6268,7 +6258,7 @@ - <literal>org.freedesktop.DBus.ListQueuedOwners</literal> + Method: <literal>org.freedesktop.DBus.ListQueuedOwners</literal> As a method: @@ -6322,7 +6312,7 @@ - <literal>org.freedesktop.DBus.ListNames</literal> + Method: <literal>org.freedesktop.DBus.ListNames</literal> As a method: @@ -6353,7 +6343,7 @@ - <literal>org.freedesktop.DBus.ListActivatableNames</literal> + Method: <literal>org.freedesktop.DBus.ListActivatableNames</literal> As a method: @@ -6384,7 +6374,7 @@ - <literal>org.freedesktop.DBus.NameHasOwner</literal> + Method: <literal>org.freedesktop.DBus.NameHasOwner</literal> As a method: @@ -6435,7 +6425,7 @@ - <literal>org.freedesktop.DBus.NameOwnerChanged</literal> + Signal: <literal>org.freedesktop.DBus.NameOwnerChanged</literal> This is a signal: @@ -6478,7 +6468,7 @@ - <literal>org.freedesktop.DBus.NameLost</literal> + Signal: <literal>org.freedesktop.DBus.NameLost</literal> This is a signal: @@ -6511,7 +6501,7 @@ - <literal>org.freedesktop.DBus.NameAcquired</literal> + Signal: <literal>org.freedesktop.DBus.NameAcquired</literal> This is a signal: @@ -6544,7 +6534,7 @@ - <literal>org.freedesktop.DBus.ActivatableServicesChanged</literal> + Signal: <literal>org.freedesktop.DBus.ActivatableServicesChanged</literal> This is a signal: @@ -6570,7 +6560,7 @@ - <literal>org.freedesktop.DBus.StartServiceByName</literal> + Method: <literal>org.freedesktop.DBus.StartServiceByName</literal> As a method: @@ -6671,7 +6661,7 @@ - <literal>org.freedesktop.DBus.UpdateActivationEnvironment</literal> + Method: <literal>org.freedesktop.DBus.UpdateActivationEnvironment</literal> As a method: @@ -6708,7 +6698,7 @@ - <literal>org.freedesktop.DBus.GetNameOwner</literal> + Method: <literal>org.freedesktop.DBus.GetNameOwner</literal> As a method: @@ -6759,7 +6749,7 @@ - <literal>org.freedesktop.DBus.GetConnectionUnixUser</literal> + Method: <literal>org.freedesktop.DBus.GetConnectionUnixUser</literal> As a method: @@ -6812,7 +6802,7 @@ - <literal>org.freedesktop.DBus.GetConnectionUnixProcessID</literal> + Method: <literal>org.freedesktop.DBus.GetConnectionUnixProcessID</literal> As a method: @@ -6865,7 +6855,7 @@ - <literal>org.freedesktop.DBus.GetConnectionCredentials</literal> + Method: <literal>org.freedesktop.DBus.GetConnectionCredentials</literal> As a method: @@ -7049,7 +7039,7 @@ - <literal>org.freedesktop.DBus.GetAdtAuditSessionData</literal> + Method: <literal>org.freedesktop.DBus.GetAdtAuditSessionData</literal> As a method: @@ -7107,7 +7097,7 @@ - <literal>org.freedesktop.DBus.GetConnectionSELinuxSecurityContext</literal> + Method: <literal>org.freedesktop.DBus.GetConnectionSELinuxSecurityContext</literal> As a method: @@ -7166,7 +7156,7 @@ - <literal>org.freedesktop.DBus.AddMatch</literal> + Method: <literal>org.freedesktop.DBus.AddMatch</literal> As a method: @@ -7197,7 +7187,7 @@ - <literal>org.freedesktop.DBus.RemoveMatch</literal> + Method: <literal>org.freedesktop.DBus.RemoveMatch</literal> As a method: @@ -7229,7 +7219,7 @@ - <literal>org.freedesktop.DBus.GetId</literal> + Method: <literal>org.freedesktop.DBus.GetId</literal> As a method: @@ -7264,109 +7254,8 @@ - - <literal>org.freedesktop.DBus.Monitoring.BecomeMonitor</literal> - - As a method: - - BecomeMonitor (in ARRAY of STRING rule, in UINT32 flags) - - Message arguments: - - - - - Argument - Type - Description - - - - - 0 - ARRAY of STRING - Match rules to add to the connection - - - 1 - UINT32 - Not used, must be 0 - - - - - - - - Converts the connection into a monitor - connection 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 - - 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. - - . - - - - 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. - - - - 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 eavesdrop='true' member. - - - - 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. - - - - The second argument might be used for flags to influence the - behaviour of the monitor connection in future D-Bus versions. - - - - 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. - - - - - - - Message Bus Properties - - The special message bus name org.freedesktop.DBus - exports several properties (see - ) on the object path - /org/freedesktop/DBus. - - - <literal>org.freedesktop.DBus.Features</literal> + Property: <literal>org.freedesktop.DBus.Features</literal> As a property: @@ -7471,7 +7360,7 @@ - <literal>org.freedesktop.DBus.Interfaces</literal> + Property: <literal>org.freedesktop.DBus.Interfaces</literal> As a property: @@ -7503,6 +7392,139 @@ + + Message Bus Introspection + + The message bus should implement the standard + Introspectable + interface. + + + + + Message Bus as a Peer + + The message bus should implement the standard + Peer interface. + Support for the Peer interface was added in version + 1.11.x of the reference implementation of the message bus. + + + + + Message Bus Properties + + The message bus should implement the standard + Properties + interface on the object path + /org/freedesktop/DBus. + 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. + + + + + Monitoring Interface: <literal>org.freedesktop.DBus.Monitoring</literal> + + The special message bus name org.freedesktop.DBus + may optionally implement the + org.freedesktop.DBus.Monitoring interface on + the object path /org/freedesktop/DBus. + + + + Method: <literal>org.freedesktop.DBus.Monitoring.BecomeMonitor</literal> + + As a method: + + BecomeMonitor (in ARRAY of STRING rule, in UINT32 flags) + + Message arguments: + + + + + Argument + Type + Description + + + + + 0 + ARRAY of STRING + Match rules to add to the connection + + + 1 + UINT32 + Not used, must be 0 + + + + + + + + Converts the connection into a monitor + connection 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 + + 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. + + . + + + + 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. + + + + 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 eavesdrop='true' member. + + + + 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. + + + + The second argument might be used for flags to influence the + behaviour of the monitor connection in future D-Bus versions. + + + + 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. + + + +