~ubuntu-branches/ubuntu/maverick/dbus/maverick-proposed

����������</p></div></div></div></div></div><div><p class="releaseinfo">Version 0.14</p></div></div><hr></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="sect1"><a href="#introduction">Introduction</a></span></dt><dd><dl><dt><span class="sect2"><a href="#stability">Protocol and Specification Stability</a></span></dt></dl></dd><dt><span class="sect1"><a href="#message-protocol">Message Protocol</a></span></dt><dd><dl><dt><span class="sect2"><a href="#message-protocol-signatures">Type Signatures</a></span></dt><dt><span class="sect2"><a href="#message-protocol-marshaling">Marshaling (Wire Format)</a></span></dt><dt><span class="sect2"><a href="#message-protocol-messages">Message Format</a></span></dt><dt><span class="sect2"><a href="#message-protocol-names">Valid Names</a></span></dt><dt><span class="sect2"><a href="#message-protocol-types">Message Types</a></span></dt><dt><span class="sect2"><a href="#message-protocol-handling-invalid">Invalid Protocol and Spec Extensions</a></span></dt></dl></dd><dt><span class="sect1"><a href="#auth-protocol">Authentication Protocol</a></span></dt><dd><dl><dt><span class="sect2"><a href="#auth-protocol-overview">Protocol Overview</a></span></dt><dt><span class="sect2"><a href="#auth-nul-byte">Special credentials-passing nul byte</a></span></dt><dt><span class="sect2"><a href="#auth-command-auth">AUTH command</a></span></dt><dt><span class="sect2"><a href="#auth-command-cancel">CANCEL Command</a></span></dt><dt><span class="sect2"><a href="#auth-command-data">DATA Command</a></span></dt><dt><span class="sect2"><a href="#auth-command-begin">BEGIN Command</a></span></dt><dt><span class="sect2"><a href="#auth-command-rejected">REJECTED Command</a></span></dt><dt><span class="sect2"><a href="#auth-command-ok">OK Command</a></span></dt><dt><span class="sect2"><a href="#auth-command-error">ERROR Command</a></span></dt><dt><span class="sect2"><a href="#auth-command-negotiate-unix-fd">NEGOTIATE_UNIX_FD Command</a></span></dt><dt><span class="sect2"><a href="#auth-command-agree-unix-fd">AGREE_UNIX_FD Command</a></span></dt><dt><span class="sect2"><a href="#auth-command-future">Future Extensions</a></span></dt><dt><span class="sect2"><a href="#auth-examples">Authentication examples</a></span></dt><dt><span class="sect2"><a href="#auth-states">Authentication state diagrams</a></span></dt><dt><span class="sect2"><a href="#auth-mechanisms">Authentication mechanisms</a></span></dt></dl></dd><dt><span class="sect1"><a href="#addresses">Server Addresses</a></span></dt><dt><span class="sect1"><a href="#transports">Transports</a></span></dt><dd><dl><dt><span class="sect2"><a href="#transports-unix-domain-sockets">Unix Domain Sockets</a></span></dt><dt><span class="sect2"><a href="#transports-tcp-sockets">TCP Sockets</a></span></dt><dt><span class="sect2"><a href="#transports-nonce-tcp-sockets">Nonce-secured TCP Sockets</a></span></dt></dl></dd><dt><span class="sect1"><a href="#naming-conventions">Naming Conventions</a></span></dt><dt><span class="sect1"><a href="#uuids">UUIDs</a></span></dt><dt><span class="sect1"><a href="#standard-interfaces">Standard Interfaces</a></span></dt><dd><dl><dt><span class="sect2"><a href="#standard-interfaces-peer"><code class="literal">org.freedesktop.DBus.Peer</code></a></span></dt><dt><span class="sect2"><a href="#standard-interfaces-introspectable"><code class="literal">org.freedesktop.DBus.Introspectable</code></a></span></dt><dt><span class="sect2"><a href="#standard-interfaces-properties"><code class="literal">org.freedesktop.DBus.Properties</code></a></span></dt></dl></dd><dt><span class="sect1"><a href="#introspection-format">Introspection Data Format</a></span></dt><dt><span class="sect1"><a href="#message-bus">Message Bus Specification</a></span></dt><dd><dl><dt><span class="sect2"><a href="#message-bus-overview">Message Bus Overview</a></span></dt><dt><span class="sect2"><a href="#message-bus-names">Message Bus Names</a></span></dt><dt><span class="sect2"><a href="#message-bus-routing">Message Bus Message Routing</a></span></dt><dt><span class="sect2"><a href="#message-bus-starting-services">Message Bus Starting Services</a></span></dt><dt><span class="sect2"><a href="#message-bus-types">Well-known Message Bus Instances</a></span></dt><dt><span class="sect2"><a href="#message-bus-messages">Message Bus Messages</a></span></dt></dl></dd><dt><span class="glossary"><a href="#id426787">Glossary</a></span></dt></dl></div><div class="sect1" title="Introduction"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="introduction"></a>Introduction</h2></div></div></div><p>

        </p><div class="informaltable"><table border="1"><colgroup><col><col><col></colgroup><thead><tr><th>Conventional Name</th><th>Code</th><th>Description</th></tr></thead><tbody><tr><td><code class="literal">INVALID</code></td><td>0 (ASCII NUL)</td><td>Not a valid type code, used to terminate signatures</td></tr><tr><td><code class="literal">BYTE</code></td><td>121 (ASCII 'y')</td><td>8-bit unsigned integer</td></tr><tr><td><code class="literal">BOOLEAN</code></td><td>98 (ASCII 'b')</td><td>Boolean value, 0 is <code class="literal">FALSE</code> and 1 is <code class="literal">TRUE</code>. Everything else is invalid.</td></tr><tr><td><code class="literal">INT16</code></td><td>110 (ASCII 'n')</td><td>16-bit signed integer</td></tr><tr><td><code class="literal">UINT16</code></td><td>113 (ASCII 'q')</td><td>16-bit unsigned integer</td></tr><tr><td><code class="literal">INT32</code></td><td>105 (ASCII 'i')</td><td>32-bit signed integer</td></tr><tr><td><code class="literal">UINT32</code></td><td>117 (ASCII 'u')</td><td>32-bit unsigned integer</td></tr><tr><td><code class="literal">INT64</code></td><td>120 (ASCII 'x')</td><td>64-bit signed integer</td></tr><tr><td><code class="literal">UINT64</code></td><td>116 (ASCII 't')</td><td>64-bit unsigned integer</td></tr><tr><td><code class="literal">DOUBLE</code></td><td>100 (ASCII 'd')</td><td>IEEE 754 double</td></tr><tr><td><code class="literal">STRING</code></td><td>115 (ASCII 's')</td><td>UTF-8 string (<span class="emphasis"><em>must</em></span> be valid UTF-8). Must be nul terminated and contain no other nul bytes.</td></tr><tr><td><code class="literal">OBJECT_PATH</code></td><td>111 (ASCII 'o')</td><td>Name of an object instance</td></tr><tr><td><code class="literal">SIGNATURE</code></td><td>103 (ASCII 'g')</td><td>A type signature</td></tr><tr><td><code class="literal">ARRAY</code></td><td>97 (ASCII 'a')</td><td>Array</td></tr><tr><td><code class="literal">STRUCT</code></td><td>114 (ASCII 'r'), 40 (ASCII '('), 41 (ASCII ')')</td><td>Struct</td></tr><tr><td><code class="literal">VARIANT</code></td><td>118 (ASCII 'v') </td><td>Variant type (the type of the value is part of the value itself)</td></tr><tr><td><code class="literal">DICT_ENTRY</code></td><td>101 (ASCII 'e'), 123 (ASCII '{'), 125 (ASCII '}') </td><td>Entry in a dict or map (array of key-value pairs)</td></tr><tr><td><code class="literal">UNIX_FD</code></td><td>104 (ASCII 'h')</td><td>Unix file descriptor</td></tr></tbody></table></div><p>

                </td></tr><tr><td><code class="literal">UNIX_FD</code></td><td>32-bit unsigned integer in the message's byte

                order. The actual file descriptors need to be

                transferred out-of-band via some platform specific

                mechanism. On the wire, values of this type store the index to the

                file descriptor in the array of file descriptors that

                accompany the message.</td><td>4</td></tr></tbody></table></div><p>

                  empty signature "" (i.e. the body must be 0-length).</td></tr><tr><td><code class="literal">UNIX_FDS</code></td><td>9</td><td><code class="literal">UINT32</code></td><td>optional</td><td>The number of Unix file descriptors that

                  accompany the message.  If omitted, it is assumed

                  that no Unix file descriptors accompany the

                  message. The actual file descriptors need to be

                  transferred via platform specific mechanism

                  out-of-band. They must be sent at the same time as

                  part of the message itself. They may not be sent

                  before the first byte of the message itself is

                  transferred or after the last byte of the message

                  itself.</td></tr></tbody></table></div><p>

        </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>AUTH [mechanism] [initial-response]</p></li><li class="listitem"><p>CANCEL</p></li><li class="listitem"><p>BEGIN</p></li><li class="listitem"><p>DATA &lt;data in hex encoding&gt;</p></li><li class="listitem"><p>ERROR [human-readable error explanation]</p></li><li class="listitem"><p>NEGOTIATE_UNIX_FD</p></li></ul></div><p>

        </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>REJECTED &lt;space-separated list of mechanism names&gt;</p></li><li class="listitem"><p>OK &lt;GUID in hex&gt;</p></li><li class="listitem"><p>DATA &lt;data in hex encoding&gt;</p></li><li class="listitem"><p>ERROR</p></li><li class="listitem"><p>AGREE_UNIX_FD</p></li></ul></div><p>

      </p><p>

        If BEGIN is received by the server, the first octet received

        by the client after the \r\n of the OK command must be the

        first octet of the authenticated/encrypted stream of D-Bus

        messages.

        The OK command indicates that the client has been

        authenticated. The client may now proceed with negotiating

        Unix file descriptor passing. To do that it shall send

        NEGOTIATE_UNIX_FD to the server.

      </p><p>

        Otherwise, the client must respond to the OK command by

        sending a BEGIN command, followed by its stream of messages,

        or by disconnecting.  The server must not accept additional

        commands using this protocol after the BEGIN command has been

        received. Further communication will be a stream of D-Bus

        messages (optionally encrypted, as negotiated) rather than

        this protocol.

      </p><p>

        If a client sends BEGIN the first octet received by the client

        after the \r\n of the OK command must be the first octet of

        the authenticated/encrypted stream of D-Bus messages.

      </p></div><div class="sect2" title="NEGOTIATE_UNIX_FD Command"><div class="titlepage"><div><div><h3 class="title"><a name="auth-command-negotiate-unix-fd"></a>NEGOTIATE_UNIX_FD Command</h3></div></div></div><p>

        The NEGOTIATE_UNIX_FD command indicates that the client

        supports Unix file descriptor passing. This command may only

        be sent after the connection is authenticated, i.e. after OK

        was received by the client. This command may only be sent on

        transports that support Unix file descriptor passing.

      </p><p>

        On receiving NEGOTIATE_UNIX_FD the server must respond with

        either AGREE_UNIX_FD or ERROR. It shall respond the former if

        the transport chosen supports Unix file descriptor passing and

        the server supports this feature. It shall respond the latter

        if the transport does not support Unix file descriptor

        passing, the server does not support this feature, or the

        server decides not to enable file descriptor passing due to

        security or other reasons.

      </p></div><div class="sect2" title="AGREE_UNIX_FD Command"><div class="titlepage"><div><div><h3 class="title"><a name="auth-command-agree-unix-fd"></a>AGREE_UNIX_FD Command</h3></div></div></div><p>

        The AGREE_UNIX_FD command indicates that the server supports

        Unix file descriptor passing. This command may only be sent

        after the connection is authenticated, and the client sent

        NEGOTIATE_UNIX_FD to enable Unix file descriptor passing. This

        command may only be sent on transports that support Unix file

        descriptor passing.

      </p><p>

        On receiving AGREE_UNIX_FD the client must respond with BEGIN,

        followed by its stream of messages, or by disconnecting.  The

        server must not accept additional commands using this protocol

        after the BEGIN command has been received. Further

        communication will be a stream of D-Bus messages (optionally

        encrypted, as negotiated) rather than this protocol.

      </p></div><div class="sect2" title="Future Extensions"><div class="titlepage"><div><div><h3 class="title"><a name="auth-command-future"></a>Future Extensions</h3></div></div></div><p>

        Future extensions to the authentication and negotiation

        protocol are possible. For that new commands may be

        introduced. If a client or server receives an unknown command

        it shall respond with ERROR and not consider this fatal. New

        commands may be introduced both before, and after

        authentication, i.e. both before and after the OK command.

        </p><div class="figure"><a name="id422013"></a><p class="title"><b>Figure�1.�Example of successful magic cookie authentication</b></p><div class="figure-contents"><pre class="programlisting">

        </p><div class="figure"><a name="id422028"></a><p class="title"><b>Figure�2.�Example of finding out mechanisms then picking one</b></p><div class="figure-contents"><pre class="programlisting">

        </p><div class="figure"><a name="id422044"></a><p class="title"><b>Figure�3.�Example of client sends unknown command then falls back to regular auth</b></p><div class="figure-contents"><pre class="programlisting">

        </p><div class="figure"><a name="id422060"></a><p class="title"><b>Figure�4.�Example of server doesn't support initial auth mechanism</b></p><div class="figure-contents"><pre class="programlisting">

        </p><div class="figure"><a name="id422076"></a><p class="title"><b>Figure�5.�Example of wrong password or the like followed by successful retry</b></p><div class="figure-contents"><pre class="programlisting">

        </p><div class="figure"><a name="id422094"></a><p class="title"><b>Figure�6.�Example of skey cancelled and restarted</b></p><div class="figure-contents"><pre class="programlisting">

        </p><div class="figure"><a name="id422112"></a><p class="title"><b>Figure�7.�Example of successful magic cookie authentication with successful negotiation of Unix FD passing</b></p><div class="figure-contents"><pre class="programlisting">

            (MAGIC_COOKIE is a made up mechanism)

 

            C: AUTH MAGIC_COOKIE 3138363935333137393635383634

            S: OK 1234deadbeef

            C: NEGOTIATE_UNIX_FD

            S: AGREE_UNIX_FD

            C: BEGIN

          </pre></div></div><p><br class="figure-break">

        </p><div class="figure"><a name="id422128"></a><p class="title"><b>Figure�8.�Example of successful magic cookie authentication with unsuccessful negotiation of Unix FD passing</b></p><div class="figure-contents"><pre class="programlisting">

            (MAGIC_COOKIE is a made up mechanism)

 

            C: AUTH MAGIC_COOKIE 3138363935333137393635383634

            S: OK 1234deadbeef

            C: NEGOTIATE_UNIX_FD

            S: ERROR

            C: BEGIN

          </pre></div></div><p><br class="figure-break">

                lock. ^{[<a name="id422845" href="#ftn.id422845" class="footnote">1</a>]}

      </p><p>

        Unix domain sockets are not available on windows. 

      </p><div class="sect3" title="Server Address Format"><div class="titlepage"><div><div><h4 class="title"><a name="transports-unix-domain-sockets-addresses"></a>Server Address Format</h4></div></div></div><p> 

          Unix domain socket addresses are identified by the "unix:" prefix 

          and support the following key/value pairs:

        </p><div class="informaltable"><table border="1"><colgroup><col><col><col></colgroup><thead><tr><th>Name</th><th>Values</th><th>Description</th></tr></thead><tbody><tr><td>path</td><td>(path)</td><td>path of the unix domain socket. If set, the "tmpdir" and "abstract" key must not be set.</td></tr><tr><td>tmpdir</td><td>(path)</td><td>temporary directory in which a socket file with a random file name starting with 'dbus-' will be created by the server. This key can only be used in server addresses, not in client addresses. If set, the "path" and "abstract" key must not be set.</td></tr><tr><td>abstract</td><td>(string)</td><td>unique string (path) in the abstract namespace. If set, the "path" or "tempdir" key must not be set.</td></tr></tbody></table></div></div></div><div class="sect2" title="TCP Sockets"><div class="titlepage"><div><div><h3 class="title"><a name="transports-tcp-sockets"></a>TCP Sockets</h3></div></div></div><p>

        The tcp transport provides TCP/IP based connections between clients

        located on the same or different hosts. 

      </p><p>

        Using tcp transport without any additional secure authentification mechanismus 

        over a network is unsecure. 

      </p><p>  

        Windows notes: Because of the tcp stack on windows does not provide sending 

        credentials over a tcp connection, the EXTERNAL authentification 

        mechanismus does not work. 

      </p><div class="sect3" title="Server Address Format"><div class="titlepage"><div><div><h4 class="title"><a name="transports-tcp-sockets-addresses"></a>Server Address Format</h4></div></div></div><p> 

         TCP/IP socket addresses are identified by the "tcp:" prefix 

         and support the following key/value pairs:

        </p><div class="informaltable"><table border="1"><colgroup><col><col><col></colgroup><thead><tr><th>Name</th><th>Values</th><th>Description</th></tr></thead><tbody><tr><td>host</td><td>(string)</td><td>dns name or ip address</td></tr><tr><td>port</td><td>(number)</td><td>The tcp port the server will open. A zero value let the server 

            choose a free port provided from the underlaying operating system. 

            libdbus is able to retrieve the real used port from the server.  

           </td></tr><tr><td>family</td><td>(string)</td><td>If set, provide the type of socket family either "ipv4" or "ipv6". If unset, the family is unspecified.</td></tr></tbody></table></div></div></div><div class="sect2" title="Nonce-secured TCP Sockets"><div class="titlepage"><div><div><h3 class="title"><a name="transports-nonce-tcp-sockets"></a>Nonce-secured TCP Sockets</h3></div></div></div><p>

        The nonce-tcp transport provides a secured TCP transport, using a

        simple authentication mechanism to ensure that only clients with read

        access to a certain location in the filesystem can connect to the server.

        The server writes a secret, the nonce, to a file and an incoming client

        connection is only accepted if the client sends the nonce right after

        the connect. The nonce mechanism requires no setup and is orthogonal to

        the higher-level authentication mechanisms described in the

        Authentication section.

      </p><p>

        On start, the server generates a random 16 byte nonce and writes it

        to a file in the user's temporary directory. The nonce file location

        is published as part of the server's D-Bus address using the

        "noncefile" key-value pair.

 

        After an accept, the server reads 16 bytes from the socket. If the

        read bytes do not match the nonce stored in the nonce file, the

        server MUST immediately drop the connection.

        If the nonce match the received byte sequence, the client is accepted

        and the transport behaves like an unsecured tcp transport.

      </p><p>

        After a successful connect to the server socket, the client MUST read

        the nonce from the file published by the server via the noncefile=

        key-value pair and send it over the socket. After that, the

        transport behaves like an unsecured tcp transport.

      </p><div class="sect3" title="Server Address Format"><div class="titlepage"><div><div><h4 class="title"><a name="transports-nonce-tcp-sockets-addresses"></a>Server Address Format</h4></div></div></div><p> 

         Nonce TCP/IP socket addresses uses the "nonce-tcp:" prefix 

         and support the following key/value pairs:

        </p><div class="informaltable"><table border="1"><colgroup><col><col><col></colgroup><thead><tr><th>Name</th><th>Values</th><th>Description</th></tr></thead><tbody><tr><td>host</td><td>(string)</td><td>dns name or ip address</td></tr><tr><td>port</td><td>(number)</td><td>The tcp port the server will open. A zero value let the server 

            choose a free port provided from the underlaying operating system. 

            libdbus is able to retrieve the real used port from the server.  

           </td></tr><tr><td>family</td><td>(string)</td><td>If set, provide the type of socket family either "ipv4" or "ipv6". If unset, the family is unspecified.</td></tr><tr><td>noncefile</td><td>(path)</td><td>file location containing the secret</td></tr></tbody></table></div></div></div></div><div class="sect1" title="Naming Conventions"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="naming-conventions"></a>Naming Conventions</h2></div></div></div><p>

      </p><p>

        If one or more properties change on an object, the

        <code class="literal">org.freedesktop.DBus.Properties.PropertiesChanged</code>

        signal may be emitted (this signal was added in 0.14):

      </p><p>

        </p><pre class="programlisting">

              org.freedesktop.DBus.Properties.PropertiesChanged (STRING interface_name,

                                                                 DICT&lt;STRING,VARIANT&gt; changed_properties,

                                                                 ARRAY&lt;STRING&gt; invalidated_properties);

        </pre><p>

      </p><p>

        where <code class="literal">changed_properties</code> is a dictionary

        containing the changed properties with the new values and

        <code class="literal">invalidated_properties</code> is an array of

        properties that changed but the value is not conveyed.

      </p><p>

        Whether the <code class="literal">PropertiesChanged</code> signal is

        supported can be determined by calling

        <code class="literal">org.freedesktop.DBus.Introspectable.Introspect</code>. Note

        that the signal may be supported for an object but it may

        differ how whether and how it is used on a per-property basis

        (for e.g. performance or security reasons). Each property (or

        the parent interface) must be annotated with the

        <code class="literal">org.freedesktop.DBus.Property.EmitsChangedSignal</code>

        annotation to convey this (usually the default value

        <code class="literal">true</code> is sufficient meaning that the

        annotation does not need to be used). See <a class="xref" href="#introspection-format" title="Introspection Data Format">the section called &#8220;Introspection Data Format&#8221;</a> for details on this

        annotation.

     </p><div class="informaltable"><table border="1"><colgroup><col><col><col></colgroup><thead><tr><th>Name</th><th>Values (separated by ,)</th><th>Description</th></tr></thead><tbody><tr><td>org.freedesktop.DBus.Deprecated</td><td>true,false</td><td>Whether or not the entity is deprecated; defaults to false</td></tr><tr><td>org.freedesktop.DBus.GLib.CSymbol</td><td>(string)</td><td>The C symbol; may be used for methods and interfaces</td></tr><tr><td>org.freedesktop.DBus.Method.NoReply</td><td>true,false</td><td>If set, don't expect a reply to the method call; defaults to false.</td></tr><tr><td>org.freedesktop.DBus.Property.EmitsChangedSignal</td><td>true,invalidates,false</td><td>

               <p>

                 If set to <code class="literal">false</code>, the

                 <code class="literal">org.freedesktop.DBus.Properties.PropertiesChanged</code>

                 signal, see <a class="xref" href="#standard-interfaces-properties" title="org.freedesktop.DBus.Properties">the section called &#8220;<code class="literal">org.freedesktop.DBus.Properties</code>&#8221;</a> is not

                 guaranteed to be emitted if the property changes.

               </p>

               <p>

                 If set to <code class="literal">invalidates</code> the signal

                 is emitted but the value is not included in the

                 signal.

               </p>

               <p>

                 If set to <code class="literal">true</code> the signal is

                 emitted with the value included.

               </p>

               <p>

                 The value for the annotation defaults to

                 <code class="literal">true</code> if the enclosing interface

                 element does not specify the annotation. Otherwise it

                 defaults to the value specified in the enclosing

                 interface element.

               </p>

             </td></tr></tbody></table></div></div><div class="sect1" title="Message Bus Specification"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="message-bus"></a>Message Bus Specification</h2></div></div></div><div class="sect2" title="Message Bus Overview"><div class="titlepage"><div><div><h3 class="title"><a name="message-bus-overview"></a>Message Bus Overview</h3></div></div></div><p>

        </p></div><div class="sect3" title="org.freedesktop.DBus.ListQueuedOwners"><div class="titlepage"><div><div><h4 class="title"><a name="bus-messages-list-queued-owners"></a><code class="literal">org.freedesktop.DBus.ListQueuedOwners</code></h4></div></div></div><p>

          As a method:

          </p><pre class="programlisting">

            ARRAY of STRING ListQueuedOwners (in STRING name)

          </pre><p>

          Message arguments:

          </p><div class="informaltable"><table border="1"><colgroup><col><col><col></colgroup><thead><tr><th>Argument</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td>0</td><td>STRING</td><td>The well-known bus name to query, such as

                    <code class="literal">com.example.cappuccino</code></td></tr></tbody></table></div><p>

          Reply arguments:

          </p><div class="informaltable"><table border="1"><colgroup><col><col><col></colgroup><thead><tr><th>Argument</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td>0</td><td>ARRAY of STRING</td><td>The unique bus names of connections currently queued

                    for the name</td></tr></tbody></table></div><p>

        </p><p>

          This method call should be sent to

          <code class="literal">org.freedesktop.DBus</code> and lists the connections

          currently queued for a bus name (see

          <a class="xref" href="#term-queued-owner" title="Queued Name Owner">Queued Name Owner</a>).

          (see <a class="xref" href="#bus-messages-add-match" title="org.freedesktop.DBus.AddMatch">the section called &#8220;<code class="literal">org.freedesktop.DBus.AddMatch</code>&#8221;</a>).  Rules are

        </p><div class="figure"><a name="id425209"></a><p class="title"><b>Figure�9.�Example service description file</b></p><div class="figure-contents"><pre class="programlisting">

          ^{[<a name="id425407" href="#ftn.id425407" class="footnote">2</a>]}

        </p><p>

          Note, both the environment variable names and values must be valid UTF-8.  There's no way to update the activation environment with data that is invalid UTF-8.

            UINT32 GetConnectionUnixUser (in STRING bus_name)

          </pre><p>

          Message arguments:

          </p><div class="informaltable"><table border="1"><colgroup><col><col><col></colgroup><thead><tr><th>Argument</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td>0</td><td>STRING</td><td>Unique or well-known bus name of the connection to

                    query, such as <code class="literal">:12.34</code> or

                    <code class="literal">com.example.tea</code></td></tr></tbody></table></div><p>

        Reply arguments:

        </p><div class="informaltable"><table border="1"><colgroup><col><col><col></colgroup><thead><tr><th>Argument</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td>0</td><td>UINT32</td><td>Unix user ID</td></tr></tbody></table></div><p>

        Returns the Unix user ID of the process connected to the server. If

        unable to determine it (for instance, because the process is not on the

        same machine as the bus daemon), an error is returned.

       </p></div><div class="sect3" title="org.freedesktop.DBus.GetConnectionUnixProcessID"><div class="titlepage"><div><div><h4 class="title"><a name="bus-messages-get-connection-unix-process-id"></a><code class="literal">org.freedesktop.DBus.GetConnectionUnixProcessID</code></h4></div></div></div><p>

          As a method:

          </p><pre class="programlisting">

            UINT32 GetConnectionUnixProcessID (in STRING bus_name)

          </pre><p>

          Message arguments:

          </p><div class="informaltable"><table border="1"><colgroup><col><col><col></colgroup><thead><tr><th>Argument</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td>0</td><td>STRING</td><td>Unique or well-known bus name of the connection to

                    query, such as <code class="literal">:12.34</code> or

                    <code class="literal">com.example.tea</code></td></tr></tbody></table></div><p>

        Reply arguments:

        </p><div class="informaltable"><table border="1"><colgroup><col><col><col></colgroup><thead><tr><th>Argument</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td>0</td><td>UINT32</td><td>Unix process id</td></tr></tbody></table></div><p>

        Returns the Unix process ID of the process connected to the server. If

        unable to determine it (for instance, because the process is not on the

        same machine as the bus daemon), an error is returned.

        </p></div></div></div><div class="glossary" title="Glossary"><div class="titlepage"><div><div><h2 class="title"><a name="id426787"></a>Glossary</h2></div></div></div><p>

        </p></dd></dl></div><div class="footnotes"><br><hr width="100" align="left"><div class="footnote"><p>^{[<a name="ftn.id422845" href="#id422845" class="para">1</a>]}Lockfiles are used instead of real file

                filesystems.</p></div><div class="footnote"><p>^{[<a name="ftn.id425407" href="#id425407" class="para">2</a>]}