Attachment 128110 Details for Bug 98671 – Spec: mostly use versioned interface and bus names

[patch] Spec: mostly use versioned interface and bus names

0004-Spec-mostly-use-versioned-interface-and-bus-names.patch (text/plain), 6.93 KB, created by Simon McVittie on 2016-11-21 20:37:28 UTC

(hide)

Description:

Filename:

MIME Type:

Creator: Simon McVittie

Created: 2016-11-21 20:37:28 UTC

Size: 6.93 KB

patch

obsolete

>From a0c2e93fbe2094e56a7735e89e72817b5b5f64e1 Mon Sep 17 00:00:00 2001
>From: Simon McVittie <simon.mcvittie@collabora.co.uk>
>Date: Mon, 21 Nov 2016 20:19:22 +0000
>Subject: [PATCH 4/4] Spec: mostly use versioned interface and bus names
>
>Using versioned names here reinforces the advice given in
><https://dbus.freedesktop.org/doc/dbus-api-design.html#api-versioning>.
>
>I haven't added versions to the sample parameters "com.example.tea" and
>"com.example.cappuccino" for methods that query information about
>names, on the basis that I assume they are more likely to be intended
>to represent an implementation than an API.
>
>Signed-off-by: Simon McVittie <simon.mcvittie@collabora.co.uk>
>Bug: https://bugs.freedesktop.org/show_bug.cgi?id=98671
>---
> doc/dbus-specification.xml | 36 ++++++++++++++++++------------------
> 1 file changed, 18 insertions(+), 18 deletions(-)
>
>diff --git a/doc/dbus-specification.xml b/doc/dbus-specification.xml
>index 2e72c31..fbb8f25 100644
>--- a/doc/dbus-specification.xml
>+++ b/doc/dbus-specification.xml
>@@ -1847,8 +1847,8 @@
>           Error names have the same naming conventions as interface
>           names, and often contain <literal>.Error.</literal>; for instance,
>           the owner of <literal>example.com</literal> might define the
>-          errors <literal>com.example.MusicPlayer.Error.FileNotFound</literal>
>-          and <literal>com.example.MusicPlayer.Error.OutOfMemory</literal>.
>+          errors <literal>com.example.MusicPlayer1.Error.FileNotFound</literal>
>+          and <literal>com.example.MusicPlayer1.Error.OutOfMemory</literal>.
>           The errors defined by D-Bus itself, such as
>           <literal>org.freedesktop.DBus.Error.Failed</literal>, follow a
>           similar pattern.
>@@ -3931,7 +3931,7 @@
>       <para>
>         <programlisting>
>           org.freedesktop.DBus.AddMatch (bus_proxy,
>-                                         "type='signal',name='org.example.App',path_namespace='/org/example/App'");
>+                                         "type='signal',name='org.example.App2',path_namespace='/org/example/App2'");
>           objects = org.freedesktop.DBus.ObjectManager.GetManagedObjects (app_proxy);
>         </programlisting>
>       </para>
>@@ -3973,8 +3973,8 @@
>       <programlisting>
>         &lt;!DOCTYPE node PUBLIC "-//freedesktop//DTD D-BUS Object Introspection 1.0//EN"
>          "http://www.freedesktop.org/standards/dbus/1.0/introspect.dtd"&gt;
>-        &lt;node name="/com/example/sample_object"&gt;
>-          &lt;interface name="com.example.SampleInterface"&gt;
>+        &lt;node name="/com/example/sample_object0"&gt;
>+          &lt;interface name="com.example.SampleInterface0"&gt;
>             &lt;method name="Frobate"&gt;
>               &lt;arg name="foo" type="i" direction="in"/&gt;
>               &lt;arg name="bar" type="s" direction="out"/&gt;
>@@ -4151,7 +4151,7 @@
>         unique-for-the-lifetime-of-the-bus name automatically assigned.
>         Applications may request additional names for a connection. Additional
>         names are usually "well-known names" such as
>-        "com.example.TextEditor". When a name is bound to a connection,
>+        "com.example.TextEditor1". When a name is bound to a connection,
>         that connection is said to <firstterm>own</firstterm> the name.
>       </para>
>       <para>
>@@ -4173,7 +4173,7 @@
> 
>       <para>
>         This feature causes the right thing to happen if you start two text
>-        editors for example; the first one may request "com.example.TextEditor",
>+        editors for example; the first one may request "com.example.TextEditor1",
>         and the second will be queued as a possible owner of that name. When
>         the first exits, the second will take over.
>       </para>
>@@ -4927,11 +4927,11 @@
>                       first argument is an interface name.</para>
> 
>                     <para>For example, the match rule
>-                      <literal>member='NameOwnerChanged',arg0namespace='com.example.backend'</literal>
>+                      <literal>member='NameOwnerChanged',arg0namespace='com.example.backend1'</literal>
>                       matches name owner changes for bus names such as
>-                      <literal>com.example.backend.foo</literal>,
>-                      <literal>com.example.backend.foo.bar</literal>, and
>-                      <literal>com.example.backend</literal> itself.</para>
>+                      <literal>com.example.backend1.foo</literal>,
>+                      <literal>com.example.backend1.foo.bar</literal>, and
>+                      <literal>com.example.backend1</literal> itself.</para>
> 
>                     <para>See also <xref linkend='bus-messages-name-owner-changed'/>.</para>
>                     <para>
>@@ -4987,7 +4987,7 @@
>         <firstterm>auto-starting</firstterm>, which is one form of activation.
>         In auto-starting, applications send a
>         message to a particular well-known name, such as
>-        <literal>com.example.TextEditor</literal>, without specifying the
>+        <literal>com.example.TextEditor1</literal>, without specifying the
>         <literal>NO_AUTO_START</literal> flag in the message header.
>         If no application on the bus owns the requested name, but the bus
>         daemon does know how to start an activatable service for that name,
>@@ -5004,7 +5004,7 @@
> 
>       <para>
>         In either case, this implies a contract documented along with the name
>-        <literal>com.example.TextEditor</literal> for which object
>+        <literal>com.example.TextEditor1</literal> for which object
>         the owner of that name will provide, and what interfaces those
>         objects will have.
>       </para>
>@@ -5032,7 +5032,7 @@
>         On the well-known system bus, the name of a service description file
>         must be its well-known name plus <literal>.service</literal>,
>         for instance
>-        <literal>com.example.ConfigurationDatabase.service</literal>.
>+        <literal>com.example.ConfigurationDatabase1.service</literal>.
>       </para>
> 
>       <para>
>@@ -5062,7 +5062,7 @@
>           <programlisting>
>             # Sample service description file
>             [D-BUS Service]
>-            Name=com.example.ConfigurationDatabase
>+            Name=com.example.ConfigurationDatabase1
>             Exec=/usr/bin/sample-configd
>           </programlisting>
>         </figure>
>@@ -6671,9 +6671,9 @@
>           A service is an executable that can be launched by the bus daemon.
>           Services normally guarantee some particular features, for example they
>           may guarantee that they will request a specific name such as
>-          "com.example.Screensaver", have a singleton object
>-          "/com/example/Application", and that object will implement the
>-          interface "com.example.Screensaver.Control".
>+          "com.example.Screensaver1", have a singleton object
>+          "/com/example/Screensaver1", and that object will implement the
>+          interface "com.example.Screensaver1.Control".
>         </para>
>       </glossdef>
>     </glossentry>
>-- 
>2.10.2
>

Actions: View | Splinter Review

Attachments on bug 98671: 128107 | 128108 | 128109 | 128110 | 128143

Use of freedesktop.org services, including Bugzilla, is subject to our Code of Conduct. How we collect and use information is described in our Privacy Policy.