Patch: Minor D-BUS tutorial fixes

[David A. Wheeler]

Here are some minor tweaks to the D-BUS tutorial.

Highlights:

* Add David A. Wheeler's middle initial, contact URL.

* Add information explaining (briefly) signal semantics.

* Note in text line that interfaces are optional.

* Add information about Introspect(), based on
   Havoc Pennington's posting.

--- David A. Wheeler
-------------- next part --------------
--- dbus-tutorial.xml.orig	2005-01-22 22:53:34.000000000 -0500
+++ dbus-tutorial.xml	2005-01-23 01:43:51.000000000 -0500
@@ -22,7 +22,14 @@
       </author>
       <author>
 	<firstname>David</firstname>
+	<othername role="mi">A.</othername>
 	<surname>Wheeler</surname>
+	<affiliation>
+	  <address>
+            <!-- Reduce spam (?) by not posting email address here -->
+	    <otheraddr><ulink url="http://www.dwheeler.com/contactme.html">http://www.dwheeler.com/contactme.html</ulink></otheraddr>
+	  </address>
+	</affiliation>
       </author>
     </authorgroup>
   </articleinfo>
@@ -301,6 +308,18 @@
               Signal messages are notifications that a given signal 
               has been emitted (that an event has occurred). 
               You could also think of these as "event" messages.
+              Signals are different than method calls; the sender does not
+              normally specify a specific receiver.
+              Instead, the sender simply sends out a signal,
+              describing the event that has occurred.
+              The message bus then broadcasts that signal to all
+              applications with message matching rules that match
+              the signal.
+              If no application is interested in receiving the signal,
+              the signal is quietly discarded.
+              It is not an error if there is
+              no current application that is interested in
+              receiving the signal.
             </para>
           </listitem>
         </itemizedlist>
@@ -309,6 +328,7 @@
         A method call maps very simply to messages, then: you send a method call
         message, and receive either a method return message or an error message
         in reply.
+        All four message types have a body with zero or more data values.
       </para>
     </sect2>
 
@@ -424,7 +444,7 @@
         method call on a particular object instance, a number of 
         nested components have to be named:
         <programlisting>
-          Address -&gt; [Bus Name] -&gt; Path -&gt; Interface -&gt; Method
+          Address -&gt; [Bus Name] -&gt; Path -&gt; [Interface] -&gt; Method
         </programlisting>
         The bus name is in brackets to indicate that it's optional -- you only
         provide a name to route the method call to the right application
@@ -433,8 +453,9 @@
       </para>
 
       <para>
-        The interface is also optional, primarily for historical 
-        reasons; DCOP does not require specifying the interface, 
+        The interface is also optional (and thus shown in brackets),
+        primarily for historical reasons.
+        DCOP does not require specifying the interface, 
         instead simply forbidding duplicate method names 
         on the same object instance. D-BUS will thus let you 
         omit the interface, but if your method name is ambiguous 
@@ -443,6 +464,42 @@
       
     </sect2>
 
+    <sect2 id="introspection">
+      <title>Introspection</title>
+
+      <para>
+         Sometimes it's useful to be able to query an object and
+         find out what its interface is at run-time.
+         Applications that wish to provide this information to others
+         should implement an "Introspect()" method on its D-BUS objects.
+         Introspect() should reply with data in an
+         UTF-8 string providing detailed information
+         about how the object can be called.
+         This information should include its
+         interfaces, methods, and parameters for each of its methods
+         including the parameter names, types, and other information
+         such as if the first element in a multi-element array is a key).
+         Any binding that uses an IDL should automatically generate them.
+      </para>
+      <para>
+         At this time the format of this reply has not been determined.
+         However, the plan is for this to be an XML format.
+         By using XML, bindings can trivially create and parse
+         the results, since all languages have a xml parsers already
+         available to them.
+         Since there's just a single introspection method,
+         it's easy to implement; an application doesn't need to
+         support a suite of query operations, it just sends a constant value
+         for a given type, and then the recipient can
+         can extract from that whatever the recipient needs.
+         The other reasonable choice would be to use the
+         D-bus marshaling format, but this has several disadvantages
+         (e.g., you can't save the reply to a file as easily).
+         [FIXME: Describe XML format.]
+      </para>
+
+    </sect2>
+
   </sect1>
 
   <sect1 id="glib-client">