1: <?xml version="1.0" standalone="no"?>
    2: <!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
    3: "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd"
    4: [
    5: ]>
    6: 
    7: <article id="index">
    8:   <articleinfo>
    9:     <title>D-Bus Tutorial</title>
   10:     <releaseinfo>Version 0.5.0</releaseinfo>
   11:     <date>20 August 2006</date>
   12:     <authorgroup>
   13:       <author>
   14:         <firstname>Havoc</firstname>
   15:         <surname>Pennington</surname>
   16:         <affiliation>
   17:           <orgname>Red Hat, Inc.</orgname>
   18:           <address><email>hp@pobox.com</email></address>
   19:         </affiliation>
   20:       </author>
   21:       <author>
   22:         <firstname>David</firstname>
   23:         <surname>Wheeler</surname>
   24:       </author>
   25:       <author>
   26:         <firstname>John</firstname>
   27:         <surname>Palmieri</surname>
   28:         <affiliation>
   29:           <orgname>Red Hat, Inc.</orgname>
   30:           <address><email>johnp@redhat.com</email></address>
   31:         </affiliation>
   32:       </author>
   33:       <author>
   34:         <firstname>Colin</firstname>
   35:         <surname>Walters</surname>
   36:         <affiliation>
   37:           <orgname>Red Hat, Inc.</orgname>
   38:           <address><email>walters@redhat.com</email></address>
   39:         </affiliation>
   40:       </author>
   41:     </authorgroup>
   42:   </articleinfo>
   43: 
   44:   <sect1 id="meta">
   45:     <title>Tutorial Work In Progress</title>
   46:     
   47:     <para>
   48:       This tutorial is not complete; it probably contains some useful information, but 
   49:       also has plenty of gaps. Right now, you'll also need to refer to the D-Bus specification,
   50:       Doxygen reference documentation, and look at some examples of how other apps use D-Bus.
   51:     </para>
   52: 
   53:     <para>
   54:       Enhancing the tutorial is definitely encouraged - send your patches or suggestions to the
   55:       mailing list. If you create a D-Bus binding, please add a section to the tutorial for your 
   56:       binding, if only a short section with a couple of examples.
   57:     </para>
   58: 
   59:   </sect1>
   60: 
   61:   <sect1 id="whatis">
   62:     <title>What is D-Bus?</title>
   63:     <para>
   64:       D-Bus is a system for <firstterm>interprocess communication</firstterm>
   65:       (IPC). Architecturally, it has several layers:
   66: 
   67:       <itemizedlist>
   68:         <listitem>
   69:           <para>
   70:             A library, <firstterm>libdbus</firstterm>, that allows two
   71:             applications to connect to each other and exchange messages.
   72:           </para>
   73:         </listitem>
   74:         <listitem>
   75:           <para>
   76:             A <firstterm>message bus daemon</firstterm> executable, built on
   77:             libdbus, that multiple applications can connect to. The daemon can
   78:             route messages from one application to zero or more other
   79:             applications.
   80:           </para>
   81:         </listitem>
   82:         <listitem>
   83:           <para>
   84:             <firstterm>Wrapper libraries</firstterm> or <firstterm>bindings</firstterm> 
   85:             based on particular application frameworks.  For example, libdbus-glib and
   86:             libdbus-qt. There are also bindings to languages such as
   87:             Python. These wrapper libraries are the API most people should use,
   88:             as they simplify the details of D-Bus programming. libdbus is 
   89:             intended to be a low-level backend for the higher level bindings.
   90:             Much of the libdbus API is only useful for binding implementation.
   91:           </para>
   92:         </listitem>
   93:       </itemizedlist>
   94:     </para>
   95: 
   96:     <para>
   97:       libdbus only supports one-to-one connections, just like a raw network
   98:       socket. However, rather than sending byte streams over the connection, you
   99:       send <firstterm>messages</firstterm>. Messages have a header identifying
  100:       the kind of message, and a body containing a data payload. libdbus also
  101:       abstracts the exact transport used (sockets vs. whatever else), and
  102:       handles details such as authentication.
  103:     </para>
  104: 
  105:     <para>
  106:       The message bus daemon forms the hub of a wheel. Each spoke of the wheel
  107:       is a one-to-one connection to an application using libdbus.  An
  108:       application sends a message to the bus daemon over its spoke, and the bus
  109:       daemon forwards the message to other connected applications as
  110:       appropriate. Think of the daemon as a router.
  111:     </para>
  112: 
  113:     <para>
  114:       The bus daemon has multiple instances on a typical computer.  The
  115:       first instance is a machine-global singleton, that is, a system daemon
  116:       similar to sendmail or Apache. This instance has heavy security
  117:       restrictions on what messages it will accept, and is used for systemwide
  118:       communication. The other instances are created one per user login session.
  119:       These instances allow applications in the user's session to communicate 
  120:       with one another.
  121:     </para>
  122: 
  123:     <para>
  124:       The systemwide and per-user daemons are separate.  Normal within-session
  125:       IPC does not involve the systemwide message bus process and vice versa.
  126:     </para>
  127: 
  128:     <sect2 id="uses">
  129:       <title>D-Bus applications</title>
  130:       <para>
  131:         There are many, many technologies in the world that have "Inter-process
  132:         communication" or "networking" in their stated purpose: <ulink
  133:         url="http://www.omg.org">CORBA</ulink>, <ulink
  134:         url="http://www.opengroup.org/dce/">DCE</ulink>, <ulink
  135:         url="http://www.microsoft.com/com/">DCOM</ulink>, <ulink
  136:         url="http://developer.kde.org/documentation/library/kdeqt/dcop.html">DCOP</ulink>, <ulink
  137:         url="http://www.xmlrpc.com">XML-RPC</ulink>, <ulink
  138:         url="http://www.w3.org/TR/SOAP/">SOAP</ulink>, <ulink
  139:         url="http://www.mbus.org/">MBUS</ulink>, <ulink
  140:         url="http://www.zeroc.com/ice.html">Internet Communications Engine (ICE)</ulink>,
  141:         and probably hundreds more.
  142:         Each of these is tailored for particular kinds of application.
  143:         D-Bus is designed for two specific cases:
  144:         <itemizedlist>
  145:           <listitem>
  146:             <para>
  147:               Communication between desktop applications in the same desktop
  148:               session; to allow integration of the desktop session as a whole,
  149:               and address issues of process lifecycle (when do desktop components 
  150:               start and stop running).
  151:             </para>
  152:           </listitem>
  153:           <listitem>
  154:             <para>
  155:               Communication between the desktop session and the operating system, 
  156:               where the operating system would typically include the kernel 
  157:               and any system daemons or processes.
  158:             </para>
  159:           </listitem>
  160:         </itemizedlist>
  161:       </para>
  162:       <para>
  163:         For the within-desktop-session use case, the GNOME and KDE desktops 
  164:         have significant previous experience with different IPC solutions
  165:         such as CORBA and DCOP. D-Bus is built on that experience and 
  166:         carefully tailored to meet the needs of these desktop projects 
  167:         in particular. D-Bus may or may not be appropriate for other 
  168:         applications; the FAQ has some comparisons to other IPC systems.
  169:       </para>
  170:       <para>
  171:         The problem solved by the systemwide or communication-with-the-OS case 
  172:         is explained well by the following text from the Linux Hotplug project:
  173:         <blockquote>
  174:           <para>
  175:            A gap in current Linux support is that policies with any sort of
  176:            dynamic "interact with user" component aren't currently
  177:            supported. For example, that's often needed the first time a network
  178:            adapter or printer is connected, and to determine appropriate places
  179:            to mount disk drives. It would seem that such actions could be
  180:            supported for any case where a responsible human can be identified:
  181:            single user workstations, or any system which is remotely
  182:            administered.
  183:           </para>
  184: 
  185:           <para>
  186:             This is a classic "remote sysadmin" problem, where in this case
  187:             hotplugging needs to deliver an event from one security domain
  188:             (operating system kernel, in this case) to another (desktop for
  189:             logged-in user, or remote sysadmin). Any effective response must go
  190:             the other way: the remote domain taking some action that lets the
  191:             kernel expose the desired device capabilities. (The action can often
  192:             be taken asynchronously, for example letting new hardware be idle
  193:             until a meeting finishes.) At this writing, Linux doesn't have
  194:             widely adopted solutions to such problems. However, the new D-Bus
  195:             work may begin to solve that problem.
  196:           </para>
  197:         </blockquote>
  198:       </para>
  199:       <para>
  200:         D-Bus may happen to be useful for purposes other than the one it was
  201:         designed for. Its general properties that distinguish it from 
  202:         other forms of IPC are:
  203:         <itemizedlist>
  204:           <listitem>
  205:             <para>
  206:               Binary protocol designed to be used asynchronously 
  207:               (similar in spirit to the X Window System protocol).
  208:             </para>
  209:           </listitem>
  210:           <listitem>
  211:             <para>
  212:               Stateful, reliable connections held open over time.
  213:             </para>
  214:           </listitem>
  215:           <listitem>
  216:             <para>
  217:               The message bus is a daemon, not a "swarm" or 
  218:               distributed architecture.
  219:             </para>
  220:           </listitem>
  221:           <listitem>
  222:             <para>
  223:               Many implementation and deployment issues are specified rather
  224:               than left ambiguous/configurable/pluggable.
  225:             </para>
  226:           </listitem>
  227:           <listitem>
  228:             <para>
  229:               Semantics are similar to the existing DCOP system, allowing 
  230:               KDE to adopt it more easily.
  231:             </para>
  232:           </listitem>
  233:           <listitem>
  234:             <para>
  235:               Security features to support the systemwide mode of the 
  236:               message bus.
  237:             </para>
  238:           </listitem>
  239:         </itemizedlist>
  240:       </para>
  241:     </sect2>
  242:   </sect1>
  243:   <sect1 id="concepts">
  244:     <title>Concepts</title>
  245:     <para>
  246:       Some basic concepts apply no matter what application framework you're
  247:       using to write a D-Bus application. The exact code you write will be
  248:       different for GLib vs. Qt vs. Python applications, however.
  249:     </para>
  250:     
  251:     <para>
  252:       Here is a diagram (<ulink url="diagram.png">png</ulink> <ulink
  253:       url="diagram.svg">svg</ulink>) that may help you visualize the concepts
  254:       that follow.
  255:     </para>
  256: 
  257:     <sect2 id="objects">
  258:       <title>Native Objects and Object Paths</title>
  259:       <para>
  260:         Your programming framework probably defines what an "object" is like;
  261:         usually with a base class. For example: java.lang.Object, GObject, QObject,
  262:         python's base Object, or whatever. Let's call this a <firstterm>native object</firstterm>.
  263:       </para>
  264:       <para>
  265:         The low-level D-Bus protocol, and corresponding libdbus API, does not care about native objects. 
  266:         However, it provides a concept called an 
  267:         <firstterm>object path</firstterm>. The idea of an object path is that 
  268:         higher-level bindings can name native object instances, and allow remote applications 
  269:         to refer to them.
  270:       </para>
  271:       <para>
  272:         The object path
  273:         looks like a filesystem path, for example an object could be 
  274:         named <literal>/org/kde/kspread/sheets/3/cells/4/5</literal>. 
  275:         Human-readable paths are nice, but you are free to create an 
  276:         object named <literal>/com/mycompany/c5yo817y0c1y1c5b</literal> 
  277:         if it makes sense for your application.
  278:       </para>
  279:       <para>
  280:         Namespacing object paths is smart, by starting them with the components
  281:         of a domain name you own (e.g. <literal>/org/kde</literal>). This 
  282:         keeps different code modules in the same process from stepping 
  283:         on one another's toes.
  284:       </para>
  285:     </sect2>    
  286: 
  287:     <sect2 id="members">
  288:       <title>Methods and Signals</title>
  289: 
  290:       <para>
  291:         Each object has <firstterm>members</firstterm>; the two kinds of member
  292:         are <firstterm>methods</firstterm> and
  293:         <firstterm>signals</firstterm>. Methods are operations that can be
  294:         invoked on an object, with optional input (aka arguments or "in
  295:         parameters") and output (aka return values or "out parameters").
  296:         Signals are broadcasts from the object to any interested observers 
  297:         of the object; signals may contain a data payload.
  298:       </para>
  299: 
  300:       <para>
  301:         Both methods and signals are referred to by name, such as 
  302:         "Frobate" or "OnClicked".
  303:       </para>
  304: 
  305:     </sect2>
  306: 
  307:     <sect2 id="interfaces">
  308:       <title>Interfaces</title>
  309:       <para>
  310:         Each object supports one or more <firstterm>interfaces</firstterm>.
  311:         Think of an interface as a named group of methods and signals, 
  312:         just as it is in GLib or Qt or Java. Interfaces define the 
  313:         <emphasis>type</emphasis> of an object instance.
  314:       </para>
  315:       <para>
  316:         DBus identifies interfaces with a simple namespaced string,
  317:         something like <literal>org.freedesktop.Introspectable</literal>.
  318:         Most bindings will map these interface names directly to 
  319:         the appropriate programming language construct, for example 
  320:         to Java interfaces or C++ pure virtual classes.
  321:       </para>
  322:     </sect2>
  323: 
  324:     <sect2 id="proxies">
  325:       <title>Proxies</title>
  326:       <para>
  327:         A <firstterm>proxy object</firstterm> is a convenient native object created to 
  328:         represent a remote object in another process. The low-level DBus API involves manually creating 
  329:         a method call message, sending it, then manually receiving and processing 
  330:         the method reply message. Higher-level bindings provide proxies as an alternative.
  331:         Proxies look like a normal native object; but when you invoke a method on the proxy 
  332:         object, the binding converts it into a DBus method call message, waits for the reply 
  333:         message, unpacks the return value, and returns it from the native method..
  334:       </para>
  335:       <para>
  336:         In pseudocode, programming without proxies might look like this:
  337:         <programlisting>
  338:           Message message = new Message("/remote/object/path", "MethodName", arg1, arg2);
  339:           Connection connection = getBusConnection();
  340:           connection.send(message);
  341:           Message reply = connection.waitForReply(message);
  342:           if (reply.isError()) {
  343:              
  344:           } else {
  345:              Object returnValue = reply.getReturnValue();
  346:           }
  347:         </programlisting>
  348:       </para>
  349:       <para>
  350:         Programming with proxies might look like this:
  351:         <programlisting>
  352:           Proxy proxy = new Proxy(getBusConnection(), "/remote/object/path");
  353:           Object returnValue = proxy.MethodName(arg1, arg2);
  354:         </programlisting>
  355:       </para>
  356:     </sect2>
  357: 
  358:     <sect2 id="bus-names">
  359:       <title>Bus Names</title>
  360: 
  361:       <para>
  362:         When each application connects to the bus daemon, the daemon immediately
  363:         assigns it a name, called the <firstterm>unique connection name</firstterm>.
  364:         A unique name begins with a ':' (colon) character. These names are never 
  365:         reused during the lifetime of the bus daemon - that is, you know 
  366:         a given name will always refer to the same application.
  367:         An example of a unique name might be
  368:         <literal>:34-907</literal>. The numbers after the colon have 
  369:         no meaning other than their uniqueness.
  370:       </para>
  371: 
  372:       <para>
  373:         When a name is mapped 
  374:         to a particular application's connection, that application is said to 
  375:         <firstterm>own</firstterm> that name.
  376:       </para>
  377: 
  378:       <para>
  379:         Applications may ask to own additional <firstterm>well-known
  380:         names</firstterm>. For example, you could write a specification to
  381:         define a name called <literal>com.mycompany.TextEditor</literal>.
  382:         Your definition could specify that to own this name, an application
  383:         should have an object at the path
  384:         <literal>/com/mycompany/TextFileManager</literal> supporting the
  385:         interface <literal>org.freedesktop.FileHandler</literal>.
  386:       </para>
  387:       
  388:       <para>
  389:         Applications could then send messages to this bus name, 
  390:         object, and interface to execute method calls.
  391:       </para>
  392: 
  393:       <para>
  394:         You could think of the unique names as IP addresses, and the
  395:         well-known names as domain names. So
  396:         <literal>com.mycompany.TextEditor</literal> might map to something like
  397:         <literal>:34-907</literal> just as <literal>mycompany.com</literal> maps
  398:         to something like <literal>192.168.0.5</literal>.
  399:       </para>
  400:       
  401:       <para>
  402:         Names have a second important use, other than routing messages.  They
  403:         are used to track lifecycle. When an application exits (or crashes), its
  404:         connection to the message bus will be closed by the operating system
  405:         kernel. The message bus then sends out notification messages telling
  406:         remaining applications that the application's names have lost their
  407:         owner. By tracking these notifications, your application can reliably
  408:         monitor the lifetime of other applications.
  409:       </para>
  410: 
  411:       <para>
  412:         Bus names can also be used to coordinate single-instance applications.
  413:         If you want to be sure only one
  414:         <literal>com.mycompany.TextEditor</literal> application is running for
  415:         example, have the text editor application exit if the bus name already
  416:         has an owner.
  417:       </para>
  418: 
  419:     </sect2>
  420: 
  421:     <sect2 id="addresses">
  422:       <title>Addresses</title>
  423: 
  424:       <para>
  425:         Applications using D-Bus are either servers or clients.  A server
  426:         listens for incoming connections; a client connects to a server. Once
  427:         the connection is established, it is a symmetric flow of messages; the
  428:         client-server distinction only matters when setting up the 
  429:         connection.
  430:       </para>
  431: 
  432:       <para>
  433:         If you're using the bus daemon, as you probably are, your application 
  434:         will be a client of the bus daemon. That is, the bus daemon listens 
  435:         for connections and your application initiates a connection to the bus 
  436:         daemon.
  437:       </para>
  438: 
  439:       <para>
  440:         A D-Bus <firstterm>address</firstterm> specifies where a server will
  441:         listen, and where a client will connect.  For example, the address
  442:         <literal>unix:path=/tmp/abcdef</literal> specifies that the server will
  443:         listen on a UNIX domain socket at the path
  444:         <literal>/tmp/abcdef</literal> and the client will connect to that
  445:         socket. An address can also specify TCP/IP sockets, or any other
  446:         transport defined in future iterations of the D-Bus specification.
  447:       </para>
  448: 
  449:       <para>
  450:         When using D-Bus with a message bus daemon,
  451:         libdbus automatically discovers the address of the per-session bus 
  452:         daemon by reading an environment variable. It discovers the 
  453:         systemwide bus daemon by checking a well-known UNIX domain socket path
  454:         (though you can override this address with an environment variable).
  455:       </para>
  456: 
  457:       <para>
  458:         If you're using D-Bus without a bus daemon, it's up to you to 
  459:         define which application will be the server and which will be 
  460:         the client, and specify a mechanism for them to agree on 
  461:         the server's address. This is an unusual case.
  462:       </para>
  463: 
  464:     </sect2>
  465: 
  466:     <sect2 id="bigpicture">
  467:       <title>Big Conceptual Picture</title>
  468: 
  469:       <para>
  470:         Pulling all these concepts together, to specify a particular 
  471:         method call on a particular object instance, a number of 
  472:         nested components have to be named:
  473:         <programlisting>
  474:           Address -&gt; [Bus Name] -&gt; Path -&gt; Interface -&gt; Method
  475:         </programlisting>
  476:         The bus name is in brackets to indicate that it's optional -- you only
  477:         provide a name to route the method call to the right application
  478:         when using the bus daemon. If you have a direct connection to another
  479:         application, bus names aren't used; there's no bus daemon.
  480:       </para>
  481: 
  482:       <para>
  483:         The interface is also optional, primarily for historical 
  484:         reasons; DCOP does not require specifying the interface, 
  485:         instead simply forbidding duplicate method names 
  486:         on the same object instance. D-Bus will thus let you 
  487:         omit the interface, but if your method name is ambiguous 
  488:         it is undefined which method will be invoked.
  489:       </para>
  490: 
  491:     </sect2>
  492: 
  493:     <sect2 id="messages">
  494:       <title>Messages - Behind the Scenes</title>
  495:       <para>
  496:         D-Bus works by sending messages between processes. If you're using 
  497:         a sufficiently high-level binding, you may never work with messages directly.
  498:       </para>
  499:       <para>
  500:         There are 4 message types:
  501:         <itemizedlist>
  502:           <listitem>
  503:             <para>
  504:               Method call messages ask to invoke a method 
  505:               on an object.
  506:             </para>
  507:           </listitem>
  508:           <listitem>
  509:             <para>
  510:               Method return messages return the results 
  511:               of invoking a method.
  512:             </para>
  513:           </listitem>
  514:           <listitem>
  515:             <para>
  516:               Error messages return an exception caused by 
  517:               invoking a method.
  518:             </para>
  519:           </listitem>
  520:           <listitem>
  521:             <para>
  522:               Signal messages are notifications that a given signal 
  523:               has been emitted (that an event has occurred). 
  524:               You could also think of these as "event" messages.
  525:             </para>
  526:           </listitem>
  527:         </itemizedlist>
  528:       </para>
  529:       <para>
  530:         A method call maps very simply to messages: you send a method call
  531:         message, and receive either a method return message or an error message
  532:         in reply.
  533:       </para>
  534:       <para>
  535:         Each message has a <firstterm>header</firstterm>, including <firstterm>fields</firstterm>, 
  536:         and a <firstterm>body</firstterm>, including <firstterm>arguments</firstterm>. You can think 
  537:         of the header as the routing information for the message, and the body as the payload.
  538:         Header fields might include the sender bus name, destination bus name, method or signal name, 
  539:         and so forth. One of the header fields is a <firstterm>type signature</firstterm> describing the 
  540:         values found in the body. For example, the letter "i" means "32-bit integer" so the signature 
  541:         "ii" means the payload has two 32-bit integers.
  542:       </para>
  543:     </sect2>
  544: 
  545:     <sect2 id="callprocedure">
  546:       <title>Calling a Method - Behind the Scenes</title>
  547: 
  548:       <para>
  549:         A method call in DBus consists of two messages; a method call message sent from process A to process B, 
  550:         and a matching method reply message sent from process B to process A. Both the call and the reply messages
  551:         are routed through the bus daemon. The caller includes a different serial number in each call message, and the
  552:         reply message includes this number to allow the caller to match replies to calls.
  553:       </para>
  554: 
  555:       <para>
  556:         The call message will contain any arguments to the method.
  557:         The reply message may indicate an error, or may contain data returned by the method.
  558:       </para>
  559: 
  560:       <para>
  561:         A method invocation in DBus happens as follows:
  562:         <itemizedlist>
  563:           <listitem>
  564:             <para>
  565:               The language binding may provide a proxy, such that invoking a method on 
  566:               an in-process object invokes a method on a remote object in another process. If so, the 
  567:               application calls a method on the proxy, and the proxy
  568:               constructs a method call message to send to the remote process.
  569:             </para>
  570:           </listitem>
  571:           <listitem>
  572:             <para>
  573:               For more low-level APIs, the application may construct a method call message itself, without
  574:               using a proxy.
  575:             </para>
  576:           </listitem>
  577:           <listitem>
  578:             <para>
  579:               In either case, the method call message contains: a bus name belonging to the remote process; the name of the method; 
  580:               the arguments to the method; an object path inside the remote process; and optionally the name of the 
  581:               interface that specifies the method.
  582:             </para>
  583:           </listitem>
  584:           <listitem>
  585:             <para>
  586:               The method call message is sent to the bus daemon.
  587:             </para>
  588:           </listitem>
  589:           <listitem>
  590:             <para>
  591:               The bus daemon looks at the destination bus name. If a process owns that name, 
  592:               the bus daemon forwards the method call to that process. Otherwise, the bus daemon
  593:               creates an error message and sends it back as the reply to the method call message.
  594:             </para>
  595:           </listitem>
  596:           <listitem>
  597:             <para>
  598:               The receiving process unpacks the method call message. In a simple low-level API situation, it 
  599:               may immediately run the method and send a method reply message to the bus daemon.
  600:               When using a high-level binding API, the binding might examine the object path, interface,
  601:               and method name, and convert the method call message into an invocation of a method on 
  602:               a native object (GObject, java.lang.Object, QObject, etc.), then convert the return 
  603:               value from the native method into a method reply message.
  604:             </para>
  605:           </listitem>
  606:           <listitem>
  607:             <para>
  608:               The bus daemon receives the method reply message and sends it to the process that 
  609:               made the method call.
  610:             </para>
  611:           </listitem>
  612:           <listitem>
  613:             <para>
  614:               The process that made the method call looks at the method reply and makes use of any 
  615:               return values included in the reply. The reply may also indicate that an error occurred.
  616:               When using a binding, the method reply message may be converted into the return value of 
  617:               of a proxy method, or into an exception.
  618:             </para>
  619:           </listitem>
  620:         </itemizedlist>
  621:       </para>
  622: 
  623:       <para>
  624:         The bus daemon never reorders messages. That is, if you send two method call messages to the same recipient, 
  625:         they will be received in the order they were sent. The recipient is not required to reply to the calls
  626:         in order, however; for example, it may process each method call in a separate thread, and return reply messages
  627:         in an undefined order depending on when the threads complete. Method calls have a unique serial 
  628:         number used by the method caller to match reply messages to call messages.
  629:       </para>
  630: 
  631:     </sect2>
  632: 
  633:     <sect2 id="signalprocedure">
  634:       <title>Emitting a Signal - Behind the Scenes</title>
  635: 
  636:       <para>
  637:         A signal in DBus consists of a single message, sent by one process to any number of other processes. 
  638:         That is, a signal is a unidirectional broadcast. The signal may contain arguments (a data payload), but 
  639:         because it is a broadcast, it never has a "return value." Contrast this with a method call 
  640:         (see <xref linkend="callprocedure"/>) where the method call message has a matching method reply message.
  641:       </para>
  642: 
  643:       <para>
  644:         The emitter (aka sender) of a signal has no knowledge of the signal recipients. Recipients register
  645:         with the bus daemon to receive signals based on "match rules" - these rules would typically include the sender and 
  646:         the signal name. The bus daemon sends each signal only to recipients who have expressed interest in that 
  647:         signal.
  648:       </para>
  649: 
  650:       <para>
  651:         A signal in DBus happens as follows:
  652:         <itemizedlist>
  653:           <listitem>
  654:             <para>
  655:               A signal message is created and sent to the bus daemon. When using the low-level API this may be 
  656:               done manually, with certain bindings it may be done for you by the binding when a native object
  657:               emits a native signal or event.
  658:             </para>
  659:           </listitem>
  660:           <listitem>
  661:             <para>
  662:               The signal message contains the name of the interface that specifies the signal;
  663:               the name of the signal; the bus name of the process sending the signal; and 
  664:               any arguments 
  665:             </para>
  666:           </listitem>
  667:           <listitem>
  668:             <para>
  669:               Any process on the message bus can register "match rules" indicating which signals it 
  670:               is interested in. The bus has a list of registered match rules.
  671:             </para>
  672:           </listitem>
  673:           <listitem>
  674:             <para>
  675:               The bus daemon examines the signal and determines which processes are interested in it.
  676:               It sends the signal message to these processes.
  677:             </para>
  678:           </listitem>
  679:           <listitem>
  680:             <para>
  681:               Each process receiving the signal decides what to do with it; if using a binding, 
  682:               the binding may choose to emit a native signal on a proxy object. If using the 
  683:               low-level API, the process may just look at the signal sender and name and decide
  684:               what to do based on that.
  685:             </para>
  686:           </listitem>
  687:         </itemizedlist>
  688:       </para>
  689: 
  690:     </sect2>
  691: 
  692:     <sect2 id="introspection">
  693:       <title>Introspection</title>
  694: 
  695:       <para>
  696:         D-Bus objects may support the interface <literal>org.freedesktop.DBus.Introspectable</literal>.
  697:         This interface has one method <literal>Introspect</literal> which takes no arguments and returns
  698:         an XML string. The XML string describes the interfaces, methods, and signals of the object.
  699:         See the D-Bus specification for more details on this introspection format.
  700:       </para>
  701: 
  702:     </sect2>
  703: 
  704:   </sect1>
  705: 
  706:   <sect1 id="glib-client">