From 5f6a9499408cb86e16cbcaba5d06f97480cf0f69 Mon Sep 17 00:00:00 2001 From: Simon McVittie Date: Sun, 26 Nov 2017 11:40:51 +0000 Subject: [PATCH] spec: Deprecate hyphen/minus in well-known names 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. Signed-off-by: Simon McVittie Bug: https://bugs.freedesktop.org/show_bug.cgi?id=103216 --- doc/dbus-specification.xml | 39 ++++++++++++++++++++++++++++++++++++--- 1 file changed, 36 insertions(+), 3 deletions(-) diff --git a/doc/dbus-specification.xml b/doc/dbus-specification.xml index c33f0a0c..860b10d7 100644 --- a/doc/dbus-specification.xml +++ b/doc/dbus-specification.xml @@ -1793,6 +1793,17 @@ com.example.MusicPlayer1.Seekable. + + 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 org._7_zip.Plugin. + + 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 @@ 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. @@ -1837,8 +1849,20 @@ - 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 Flatpak application IDs, + the DBusActivatable interface in the + Desktop Entry Specification, 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. @@ -1853,6 +1877,15 @@ simultaneously if backwards compatibility is required. + + 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 org._7_zip.Archiver. + + If a well-known bus name implies the presence of a "main" interface, that "main" interface is often given the same name as -- 2.15.0