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

spec: Deprecate hyphen/minus in well-known names

Browse source 
We don't really need two parallel forms of punctuation, and in
particular DNS domain names only have one (hyphens). If we choose one
representation and deprecate the other, it makes the recommendation
clearer for app authors.

This reflects a similar change to the Desktop Entry Specification,
which uses D-Bus well-known names as app IDs. While hyphens are not a
problem for D-Bus well-known names or for freedesktop.org app IDs,
they create problems for adjacent APIs and specifications that want to
use a well-known name in a context where hyphens are not allowed.
Hyphens are not allowed in D-Bus object paths and interface names,
are only conditionally allowed in Flatpak app IDs (they can only
appear in the last element), and have a special syntactic role in
Freedesktop icon names.

Bug: https://bugs.freedesktop.org/show_bug.cgi?id=103216
Bug: https://bugs.freedesktop.org/show_bug.cgi?id=103914
Signed-off-by: Simon McVittie <smcv@collabora.com>
Reviewed-by: Philip Withnall <withnall@endlessm.com>
Reviewed-by: Alexander Larsson <alexl@redhat.com>
This commit is contained in:
Simon McVittie 2017-11-26 11:40:51 +00:00
parent 67d04ad1aa
commit ac49b22458
1 changed files with 36 additions and 3 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

39
doc/dbus-specification.xml
View file

@ -1793,6 +1793,17 @@
<literal>com.example.MusicPlayer1.Seekable</literal>.
</para>
<para>
If the author's DNS domain name contains hyphen/minus characters
('-'), which are not allowed in D-Bus interface names, they
should be replaced by underscores. If the DNS domain name
contains a digit immediately following a period ('.'), which
is also not allowed in interface names), the interface name
should add an underscore before that digit. For example, if
the owner of 7-zip.org defined an interface for out-of-process
plugins, it might be named <literal>org._7_zip.Plugin</literal>.
</para>
<para>
D-Bus does not distinguish between the concepts that would be
called classes and interfaces in Java: either can be identified on
@ -1822,7 +1833,8 @@
</para>
</listitem>
<listitem><para>Each element must only contain the ASCII characters
"[A-Z][a-z][0-9]_-". Only elements that are part of a unique
"[A-Z][a-z][0-9]_-", with "-" discouraged in new bus
names. Only elements that are part of a unique
connection name may begin with a digit, elements in
other bus names must not begin with a digit.
</para>
@ -1837,8 +1849,20 @@
</itemizedlist>
</para>
<para>
Note that the hyphen ('-') character is allowed in bus names but
not in interface names.
Note that the hyphen ('-') character is allowed in bus names
but not in interface names. It is also problematic or not
allowed in various specifications and APIs that refer to
D-Bus, such as <ulink
url="http://docs.flatpak.org/en/latest/introduction.html#identifiers"
>Flatpak application IDs</ulink>,
<ulink
url="https://specifications.freedesktop.org/desktop-entry-spec/desktop-entry-spec-latest.html#dbus"
>the <literal>DBusActivatable</literal> interface in the
Desktop Entry Specification</ulink>, and the convention
that an application's "main" interface and object path
resemble its bus name. To avoid situations that require
special-case handling, it is recommended that new D-Bus names
consistently replace hyphens with underscores.
</para>
<para>
@ -1853,6 +1877,15 @@
simultaneously if backwards compatibility is required.
</para>
<para>
As with interface names, if the author's DNS domain name
contains hyphen/minus characters they should be replaced by
underscores, and if it contains leading digits they should be
escaped by prepending an underscore. For example, if the owner
of 7-zip.org used a D-Bus name for an archiving application,
it might be named <literal>org._7_zip.Archiver</literal>.
</para>
<para>
If a well-known bus name implies the presence of a "main" interface,
that "main" interface is often given the same name as