~ubuntu-branches/ubuntu/maverick/dbus/maverick-proposed : revision 88

1

<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>D-Bus Specification</title><meta name="generator" content="DocBook XSL Stylesheets V1.74.3"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="article" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="index"></a>D-Bus Specification</h2></div><div><div class="authorgroup"><div class="author"><h3 class="author"><span class="firstname">Havoc</span> <span class="surname">Pennington</span></h3><div class="affiliation"><span class="orgname">Red Hat, Inc.<br></span><div class="address"><p><br>

1

<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>D-Bus Specification</title><meta name="generator" content="DocBook XSL Stylesheets V1.75.2"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="article" title="D-Bus Specification"><div class="titlepage"><div><div><h2 class="title"><a name="index"></a>D-Bus Specification</h2></div><div><div class="authorgroup"><div class="author"><h3 class="author"><span class="firstname">Havoc</span> <span class="surname">Pennington</span></h3><div class="affiliation"><span class="orgname">Red Hat, Inc.<br></span><div class="address"><p><br>

2

��<code class="email"><<a class="email" href="mailto:hp@pobox.com">hp@pobox.com</a>></code><br>

3

��</p></div></div></div><div class="author"><h3 class="author"><span class="firstname">Anders</span> <span class="surname">Carlsson</span></h3><div class="affiliation"><span class="orgname">CodeFactory AB<br></span><div class="address"><p><br>

4

��<code class="email"><<a class="email" href="mailto:andersca@codefactory.se">andersca@codefactory.se</a>></code><br>

5

��</p></div></div></div><div class="author"><h3 class="author"><span class="firstname">Alexander</span> <span class="surname">Larsson</span></h3><div class="affiliation"><span class="orgname">Red Hat, Inc.<br></span><div class="address"><p><br>

6

��<code class="email"><<a class="email" href="mailto:alexl@redhat.com">alexl@redhat.com</a>></code><br>

7

��</p></div></div></div></div></div><div><p class="releaseinfo">Version 0.12</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-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></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">org.freedesktop.DBus.Peer</a></span></dt><dt><span class="sect2"><a href="#standard-interfaces-introspectable">org.freedesktop.DBus.Introspectable</a></span></dt><dt><span class="sect2"><a href="#standard-interfaces-properties">org.freedesktop.DBus.Properties</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="#id2794333">Glossary</a></span></dt></dl></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="introduction"></a>Introduction</h2></div></div></div><p>

7

��</p></div></div></div></div></div><div><p class="releaseinfo">Version 0.12</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-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></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="#id324439">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>

8

D-Bus is a system for low-latency, low-overhead, easy to use

9

interprocess communication (IPC). In more detail:

10

</p><div class="itemizedlist"><ul type="disc"><li><p>

10

</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>

11

D-Bus is <span class="emphasis"><em>low-latency</em></span> because it is designed

12

to avoid round trips and allow asynchronous operation, much like

13

the X protocol.

14

</p></li><li><p>

14

</p></li><li class="listitem"><p>

15

D-Bus is <span class="emphasis"><em>low-overhead</em></span> because it uses a

16

binary protocol, and does not have to convert to and from a text

17

format such as XML. Because D-Bus is intended for potentially

18

high-resolution same-machine IPC, not primarily for Internet IPC,

19

this is an interesting optimization.

20

</p></li><li><p>

20

</p></li><li class="listitem"><p>

21

D-Bus is <span class="emphasis"><em>easy to use</em></span> because it works in terms

22

of <em class="firstterm">messages</em> rather than byte streams, and

23

automatically handles a lot of the hard IPC issues. Also, the D-Bus

40

monitoring service or a configuration service.

41

</p><p>

42

D-Bus is designed for two specific use cases:

43

</p><div class="itemizedlist"><ul type="disc"><li><p>

43

</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>

44

A "system bus" for notifications from the system to user sessions,

45

and to allow the system to request input from user sessions.

46

</p></li><li><p>

46

</p></li><li class="listitem"><p>

47

A "session bus" used to implement desktop environments such as

48

GNOME and KDE.

49

</p></li></ul></div><p>

66

document are to be interpreted as described in RFC 2119. However, the

67

document could use a serious audit to be sure it makes sense to do

68

so. Also, they are not capitalized.

69

</p><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="stability"></a>Protocol and Specification Stability</h3></div></div></div><p>

69

</p><div class="sect2" title="Protocol and Specification Stability"><div class="titlepage"><div><div><h3 class="title"><a name="stability"></a>Protocol and Specification Stability</h3></div></div></div><p>

70

The D-Bus protocol is frozen (only compatible extensions are allowed) as

71

of November 8, 2006. However, this specification could still use a fair

72

bit of work to make interoperable reimplementation possible without

83

</p><p>

84

Nonetheless, this document should be a useful starting point and is

85

to our knowledge accurate, though incomplete.

86

</p></div></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="message-protocol"></a>Message Protocol</h2></div></div></div><p>

86

</p></div></div><div class="sect1" title="Message Protocol"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="message-protocol"></a>Message Protocol</h2></div></div></div><p>

87

A <em class="firstterm">message</em> consists of a

88

<em class="firstterm">header</em> and a <em class="firstterm">body</em>. If you

89

think of a message as a package, the header is the address, and the body

100

Converting a value from some other representation into the wire

101

format is called <em class="firstterm">marshaling</em> and converting

102

it back from the wire format is <em class="firstterm">unmarshaling</em>.

103

</p><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="message-protocol-signatures"></a>Type Signatures</h3></div></div></div><p>

103

</p><div class="sect2" title="Type Signatures"><div class="titlepage"><div><div><h3 class="title"><a name="message-protocol-signatures"></a>Type Signatures</h3></div></div></div><p>

104

The D-Bus protocol does not include type tags in the marshaled data; a

105

block of marshaled values must have a known <em class="firstterm">type

106

signature</em>. The type signature is made up of <em class="firstterm">type

220

</p><p>

221

The following table summarizes the D-Bus types.

222

</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></tbody></table></div><p>

223

</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="message-protocol-marshaling"></a>Marshaling (Wire Format)</h3></div></div></div><p>

223

</p></div><div class="sect2" title="Marshaling (Wire Format)"><div class="titlepage"><div><div><h3 class="title"><a name="message-protocol-marshaling"></a>Marshaling (Wire Format)</h3></div></div></div><p>

224

Given a type signature, a block of bytes can be converted into typed

225

values. This section describes the format of the block of bytes. Byte

226

order and alignment issues are handled uniformly for all D-Bus types.

290

</td><td>

291

8

292

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

293

</p><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="message-protocol-marshaling-object-path"></a>Valid Object Paths</h4></div></div></div><p>

293

</p><div class="sect3" title="Valid Object Paths"><div class="titlepage"><div><div><h4 class="title"><a name="message-protocol-marshaling-object-path"></a>Valid Object Paths</h4></div></div></div><p>

294

An object path is a name used to refer to an object instance.

295

Conceptually, each participant in a D-Bus message exchange may have

296

any number of object instances (think of C++ or Java objects) and each

299

</p><p>

300

The following rules define a valid object path. Implementations must

301

not send or accept messages with invalid object paths.

302

</p><div class="itemizedlist"><ul type="disc"><li><p>

302

</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>

303

The path may be of any length.

304

</p></li><li><p>

304

</p></li><li class="listitem"><p>

305

The path must begin with an ASCII '/' (integer 47) character,

306

and must consist of elements separated by slash characters.

307

</p></li><li><p>

307

</p></li><li class="listitem"><p>

308

Each element must only contain the ASCII characters

309

"[A-Z][a-z][0-9]_"

310

</p></li><li><p>

310

</p></li><li class="listitem"><p>

311

No element may be the empty string.

312

</p></li><li><p>

312

</p></li><li class="listitem"><p>

313

Multiple '/' characters cannot occur in sequence.

314

</p></li><li><p>

314

</p></li><li class="listitem"><p>

315

A trailing '/' character is not allowed unless the

316

path is the root path (a single '/' character).

317

</p></li></ul></div><p>

318

</p></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="message-protocol-marshaling-signature"></a>Valid Signatures</h4></div></div></div><p>

318

</p></div><div class="sect3" title="Valid Signatures"><div class="titlepage"><div><div><h4 class="title"><a name="message-protocol-marshaling-signature"></a>Valid Signatures</h4></div></div></div><p>

319

An implementation must not send or accept invalid signatures.

320

Valid signatures will conform to the following rules:

321

</p><div class="itemizedlist"><ul type="disc"><li><p>

321

</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>

322

The signature ends with a nul byte.

323

</p></li><li><p>

323

</p></li><li class="listitem"><p>

324

The signature is a list of single complete types.

325

Arrays must have element types, and structs must

326

have both open and close parentheses.

327

</p></li><li><p>

327

</p></li><li class="listitem"><p>

328

Only type codes and open and close parentheses are

329

allowed in the signature. The <code class="literal">STRUCT</code> type code

330

is not allowed in signatures, because parentheses

331

are used instead.

332

</p></li><li><p>

332

</p></li><li class="listitem"><p>

333

The maximum depth of container type nesting is 32 array type

334

codes and 32 open parentheses. This implies that the maximum

335

total depth of recursion is 64, for an "array of array of array

336

of ... struct of struct of struct of ..." where there are 32

337

array and 32 struct.

338

</p></li><li><p>

338

</p></li><li class="listitem"><p>

339

The maximum length of a signature is 255.

340

</p></li><li><p>

340

</p></li><li class="listitem"><p>

341

Signatures must be nul-terminated.

342

</p></li></ul></div><p>

343

</p></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="message-protocol-messages"></a>Message Format</h3></div></div></div><p>

343

</p></div></div><div class="sect2" title="Message Format"><div class="titlepage"><div><div><h3 class="title"><a name="message-protocol-messages"></a>Message Format</h3></div></div></div><p>

344

A message consists of a header and a body. The header is a block of

345

values with a fixed signature and meaning. The body is a separate block

346

of values, with a signature specified in the header.

382

its alignment padding to an 8-boundary.

383

</td></tr><tr><td>2nd <code class="literal">UINT32</code></td><td>The serial of this message, used as a cookie

384

by the sender to identify the reply corresponding

385

to this request.

385

to this request. This must not be zero.

386

</td></tr><tr><td><code class="literal">ARRAY</code> of <code class="literal">STRUCT</code> of (<code class="literal">BYTE</code>,<code class="literal">VARIANT</code>)</td><td>An array of zero or more <em class="firstterm">header

387

fields</em> where the byte is the field code, and the

388

variant is the field value. The message type determines

403

</td></tr><tr><td><code class="literal">NO_AUTO_START</code></td><td>0x2</td><td>The bus must not launch an owner

404

for the destination name in response to this message.

405

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

406

</p><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="message-protocol-header-fields"></a>Header Fields</h4></div></div></div><p>

406

</p><div class="sect3" title="Header Fields"><div class="titlepage"><div><div><h4 class="title"><a name="message-protocol-header-fields"></a>Header Fields</h4></div></div></div><p>

407

The array at the end of the header contains <em class="firstterm">header

408

fields</em>, where each field is a 1-byte field code followed

409

by a field value. A header must contain the required header fields for

451

only meaningful in combination with the message bus.</td></tr><tr><td><code class="literal">SIGNATURE</code></td><td>8</td><td><code class="literal">SIGNATURE</code></td><td>optional</td><td>The signature of the message body.

452

If omitted, it is assumed to be the

453

empty signature "" (i.e. the body must be 0-length).</td></tr></tbody></table></div><p>

454

</p></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="message-protocol-names"></a>Valid Names</h3></div></div></div><p>

454

</p></div></div><div class="sect2" title="Valid Names"><div class="titlepage"><div><div><h3 class="title"><a name="message-protocol-names"></a>Valid Names</h3></div></div></div><p>

455

The various names in D-Bus messages have some restrictions.

456

</p><p>

457

There is a <em class="firstterm">maximum name length</em>

458

of 255 which applies to bus names, interfaces, and members.

459

</p><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="message-protocol-names-interface"></a>Interface names</h4></div></div></div><p>

459

</p><div class="sect3" title="Interface names"><div class="titlepage"><div><div><h4 class="title"><a name="message-protocol-names-interface"></a>Interface names</h4></div></div></div><p>

460

Interfaces have names with type <code class="literal">STRING</code>, meaning that

461

they must be valid UTF-8. However, there are also some

462

additional restrictions that apply to interface names

463

specifically:

464

</p><div class="itemizedlist"><ul type="disc"><li><p>Interface names are composed of 1 or more elements separated by

464

</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>Interface names are composed of 1 or more elements separated by

465

a period ('.') character. All elements must contain at least

466

one character.

467

</p></li><li><p>Each element must only contain the ASCII characters

467

</p></li><li class="listitem"><p>Each element must only contain the ASCII characters

468

"[A-Z][a-z][0-9]_" and must not begin with a digit.

469

</p></li><li><p>Interface names must contain at least one '.' (period)

469

</p></li><li class="listitem"><p>Interface names must contain at least one '.' (period)

470

character (and thus at least two elements).

471

</p></li><li><p>Interface names must not begin with a '.' (period) character.</p></li><li><p>Interface names must not exceed the maximum name length.</p></li></ul></div><p>

472

</p></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="message-protocol-names-bus"></a>Bus names</h4></div></div></div><p>

471

</p></li><li class="listitem"><p>Interface names must not begin with a '.' (period) character.</p></li><li class="listitem"><p>Interface names must not exceed the maximum name length.</p></li></ul></div><p>

472

</p></div><div class="sect3" title="Bus names"><div class="titlepage"><div><div><h4 class="title"><a name="message-protocol-names-bus"></a>Bus names</h4></div></div></div><p>

473

Connections have one or more bus names associated with them.

474

A connection has exactly one bus name that is a unique connection

475

name. The unique connection name remains with the connection for

478

meaning that it must be valid UTF-8. However, there are also

479

some additional restrictions that apply to bus names

480

specifically:

481

</p><div class="itemizedlist"><ul type="disc"><li><p>Bus names that start with a colon (':')

481

</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>Bus names that start with a colon (':')

482

character are unique connection names.

483

</p></li><li><p>Bus names are composed of 1 or more elements separated by

483

</p></li><li class="listitem"><p>Bus names are composed of 1 or more elements separated by

484

a period ('.') character. All elements must contain at least

485

one character.

486

</p></li><li><p>Each element must only contain the ASCII characters

486

</p></li><li class="listitem"><p>Each element must only contain the ASCII characters

487

"[A-Z][a-z][0-9]_-". Only elements that are part of a unique

488

connection name may begin with a digit, elements in

489

other bus names must not begin with a digit.

490

</p></li><li><p>Bus names must contain at least one '.' (period)

490

</p></li><li class="listitem"><p>Bus names must contain at least one '.' (period)

491

character (and thus at least two elements).

492

</p></li><li><p>Bus names must not begin with a '.' (period) character.</p></li><li><p>Bus names must not exceed the maximum name length.</p></li></ul></div><p>

492

</p></li><li class="listitem"><p>Bus names must not begin with a '.' (period) character.</p></li><li class="listitem"><p>Bus names must not exceed the maximum name length.</p></li></ul></div><p>

493

</p><p>

494

Note that the hyphen ('-') character is allowed in bus names but

495

not in interface names.

496

</p></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="message-protocol-names-member"></a>Member names</h4></div></div></div><p>

496

</p></div><div class="sect3" title="Member names"><div class="titlepage"><div><div><h4 class="title"><a name="message-protocol-names-member"></a>Member names</h4></div></div></div><p>

497

Member (i.e. method or signal) names:

498

</p><div class="itemizedlist"><ul type="disc"><li><p>Must only contain the ASCII characters

498

</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>Must only contain the ASCII characters

499

"[A-Z][a-z][0-9]_" and may not begin with a

500

digit.</p></li><li><p>Must not contain the '.' (period) character.</p></li><li><p>Must not exceed the maximum name length.</p></li><li><p>Must be at least 1 byte in length.</p></li></ul></div><p>

501

</p></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="message-protocol-names-error"></a>Error names</h4></div></div></div><p>

500

digit.</p></li><li class="listitem"><p>Must not contain the '.' (period) character.</p></li><li class="listitem"><p>Must not exceed the maximum name length.</p></li><li class="listitem"><p>Must be at least 1 byte in length.</p></li></ul></div><p>

501

</p></div><div class="sect3" title="Error names"><div class="titlepage"><div><div><h4 class="title"><a name="message-protocol-names-error"></a>Error names</h4></div></div></div><p>

502

Error names have the same restrictions as interface names.

503

</p></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="message-protocol-types"></a>Message Types</h3></div></div></div><p>

503

</p></div></div><div class="sect2" title="Message Types"><div class="titlepage"><div><div><h3 class="title"><a name="message-protocol-types"></a>Message Types</h3></div></div></div><p>

504

Each of the message types (<code class="literal">METHOD_CALL</code>, <code class="literal">METHOD_RETURN</code>, <code class="literal">ERROR</code>, and

505

<code class="literal">SIGNAL</code>) has its own expected usage conventions and header fields.

506

This section describes these conventions.

507

</p><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="message-protocol-types-method"></a>Method Calls</h4></div></div></div><p>

507

</p><div class="sect3" title="Method Calls"><div class="titlepage"><div><div><h4 class="title"><a name="message-protocol-types-method"></a>Method Calls</h4></div></div></div><p>

508

Some messages invoke an operation on a remote object. These are

509

called method call messages and have the type tag <code class="literal">METHOD_CALL</code>. Such

510

messages map naturally to methods on objects in a typical program.

556

failed to start; in case of failure, an error will be returned. This

557

flag is only relevant in the context of a message bus, it is ignored

558

during one-to-one communication with no intermediate bus.

559

</p><div class="sect4" lang="en"><div class="titlepage"><div><div><h5 class="title"><a name="message-protocol-types-method-apis"></a>Mapping method calls to native APIs</h5></div></div></div><p>

559

</p><div class="sect4" title="Mapping method calls to native APIs"><div class="titlepage"><div><div><h5 class="title"><a name="message-protocol-types-method-apis"></a>Mapping method calls to native APIs</h5></div></div></div><p>

560

APIs for D-Bus may map method calls to a method call in a specific

561

programming language, such as C++, or may map a method call written

562

in an IDL to a D-Bus message.

595

This specification doesn't require anything of native API bindings;

596

the preceding is only a suggested convention for consistency

597

among bindings.

598

</p></div></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="message-protocol-types-signal"></a>Signal Emission</h4></div></div></div><p>

598

</p></div></div><div class="sect3" title="Signal Emission"><div class="titlepage"><div><div><h4 class="title"><a name="message-protocol-types-signal"></a>Signal Emission</h4></div></div></div><p>

599

Unlike method calls, signal emissions have no replies.

600

A signal emission is simply a single message of type <code class="literal">SIGNAL</code>.

601

It must have three header fields: <code class="literal">PATH</code> giving the object

602

the signal was emitted from, plus <code class="literal">INTERFACE</code> and <code class="literal">MEMBER</code> giving

603

the fully-qualified name of the signal. The <code class="literal">INTERFACE</code> header is required

604

for signals, though it is optional for method calls.

605

</p></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="message-protocol-types-errors"></a>Errors</h4></div></div></div><p>

605

</p></div><div class="sect3" title="Errors"><div class="titlepage"><div><div><h4 class="title"><a name="message-protocol-types-errors"></a>Errors</h4></div></div></div><p>

606

Messages of type <code class="literal">ERROR</code> are most commonly replies

607

to a <code class="literal">METHOD_CALL</code>, but may be returned in reply

608

to any kind of message. The message bus for example

613

argument is a <code class="literal">STRING</code>, it must be an error message.

614

The error message may be logged or shown to the user

615

in some way.

616

</p></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="message-protocol-types-notation"></a>Notation in this document</h4></div></div></div><p>

616

</p></div><div class="sect3" title="Notation in this document"><div class="titlepage"><div><div><h4 class="title"><a name="message-protocol-types-notation"></a>Notation in this document</h4></div></div></div><p>

617

This document uses a simple pseudo-IDL to describe particular method

618

calls and signals. Here is an example of a method call:

619

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

651

It isn't especially encouraged to use this lame pseudo-IDL in actual

652

API implementations; you might use the native notation for the

653

language you're using, or you might use COM or CORBA IDL, for example.

654

</p></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="message-protocol-handling-invalid"></a>Invalid Protocol and Spec Extensions</h3></div></div></div><p>

654

</p></div></div><div class="sect2" title="Invalid Protocol and Spec Extensions"><div class="titlepage"><div><div><h3 class="title"><a name="message-protocol-handling-invalid"></a>Invalid Protocol and Spec Extensions</h3></div></div></div><p>

655

For security reasons, the D-Bus protocol should be strictly parsed and

656

validated, with the exception of defined extension points. Any invalid

657

protocol or spec violations should result in immediately dropping the

674

without breaking interoperability would be to introduce a way to negotiate new

675

feature support as part of the auth protocol, using EXTENSION_-prefixed

676

commands. There is not yet a standard way to negotiate features.

677

</p><div class="itemizedlist"><ul type="disc"><li><p>

677

</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>

678

In the authentication protocol (see <a class="xref" href="#auth-protocol" title="Authentication Protocol">the section called “Authentication Protocol”</a>) unknown

679

commands result in an ERROR rather than a disconnect. This enables

680

future extensions to the protocol. Commands starting with EXTENSION_ are

681

reserved for third parties.

682

</p></li><li><p>

682

</p></li><li class="listitem"><p>

683

The authentication protocol supports pluggable auth mechanisms.

684

</p></li><li><p>

684

</p></li><li class="listitem"><p>

685

The address format (see <a class="xref" href="#addresses" title="Server Addresses">the section called “Server Addresses”</a>) supports new

686

kinds of transport.

687

</p></li><li><p>

687

</p></li><li class="listitem"><p>

688

Messages with an unknown type (something other than

689

<code class="literal">METHOD_CALL</code>, <code class="literal">METHOD_RETURN</code>,

690

<code class="literal">ERROR</code>, <code class="literal">SIGNAL</code>) are ignored.

691

Unknown-type messages must still be well-formed in the same way

692

as the known messages, however. They still have the normal

693

header and body.

694

</p></li><li><p>

694

</p></li><li class="listitem"><p>

695

Header fields with an unknown or unexpected field code must be ignored,

696

though again they must still be well-formed.

697

</p></li><li><p>

697

</p></li><li class="listitem"><p>

698

New standard interfaces (with new methods and signals) can of course be added.

699

</p></li></ul></div><p>

700

</p></div></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="auth-protocol"></a>Authentication Protocol</h2></div></div></div><p>

700

</p></div></div><div class="sect1" title="Authentication Protocol"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="auth-protocol"></a>Authentication Protocol</h2></div></div></div><p>

701

Before the flow of messages begins, two applications must

702

authenticate. A simple plain-text protocol is used for

703

authentication; this protocol is a SASL profile, and maps fairly

706

</p><p>

707

In examples, "C:" and "S:" indicate lines sent by the client and

708

server respectively.

709

</p><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="auth-protocol-overview"></a>Protocol Overview</h3></div></div></div><p>

709

</p><div class="sect2" title="Protocol Overview"><div class="titlepage"><div><div><h3 class="title"><a name="auth-protocol-overview"></a>Protocol Overview</h3></div></div></div><p>

710

The protocol is a line-based protocol, where each line ends with

711

\r\n. Each line begins with an all-caps ASCII command name containing

712

only the character range [A-Z_], a space, then any arguments for the

715

716

Commands from the client to the server are as follows:

717

718

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

718

</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 <data in hex encoding></p></li><li class="listitem"><p>ERROR [human-readable error explanation]</p></li></ul></div><p>

719

720

From server to client are as follows:

721

722

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

722

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

723

</p><p>

724

Unofficial extensions to the command set must begin with the letters

725

"EXTENSION_", to avoid conflicts with future official commands.

726

For example, "EXTENSION_COM_MYDOMAIN_DO_STUFF".

727

</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="auth-nul-byte"></a>Special credentials-passing nul byte</h3></div></div></div><p>

727

</p></div><div class="sect2" title="Special credentials-passing nul byte"><div class="titlepage"><div><div><h3 class="title"><a name="auth-nul-byte"></a>Special credentials-passing nul byte</h3></div></div></div><p>

728

Immediately after connecting to the server, the client must send a

729

single nul byte. This byte may be accompanied by credentials

730

information on some operating systems that use sendmsg() with

741

</p><p>

742

The credentials sent along with the nul byte may be used with the

743

SASL mechanism EXTERNAL.

744

</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="auth-command-auth"></a>AUTH command</h3></div></div></div><p>

744

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

745

If an AUTH command has no arguments, it is a request to list

746

available mechanisms. The server must respond with a REJECTED

747

command listing the mechanisms it understands, or with an error.

771

The first octet received by the server after the \r\n of the BEGIN

772

command from the client must be the first octet of the

773

authenticated/encrypted stream of D-Bus messages.

774

</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="auth-command-cancel"></a>CANCEL Command</h3></div></div></div><p>

774

</p></div><div class="sect2" title="CANCEL Command"><div class="titlepage"><div><div><h3 class="title"><a name="auth-command-cancel"></a>CANCEL Command</h3></div></div></div><p>

775

At any time up to sending the BEGIN command, the client may send a

776

CANCEL command. On receiving the CANCEL command, the server must

777

send a REJECTED command and abort the current authentication

778

exchange.

779

</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="auth-command-data"></a>DATA Command</h3></div></div></div><p>

779

</p></div><div class="sect2" title="DATA Command"><div class="titlepage"><div><div><h3 class="title"><a name="auth-command-data"></a>DATA Command</h3></div></div></div><p>

780

The DATA command may come from either client or server, and simply

781

contains a hex-encoded block of data to be interpreted

782

according to the SASL mechanism in use.

783

</p><p>

784

Some SASL mechanisms support sending an "empty string";

785

FIXME we need some way to do this.

786

</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="auth-command-begin"></a>BEGIN Command</h3></div></div></div><p>

786

</p></div><div class="sect2" title="BEGIN Command"><div class="titlepage"><div><div><h3 class="title"><a name="auth-command-begin"></a>BEGIN Command</h3></div></div></div><p>

787

The BEGIN command acknowledges that the client has received an

788

OK command from the server, and that the stream of messages

789

is about to begin.

791

The first octet received by the server after the \r\n of the BEGIN

792

command from the client must be the first octet of the

793

authenticated/encrypted stream of D-Bus messages.

794

</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="auth-command-rejected"></a>REJECTED Command</h3></div></div></div><p>

794

</p></div><div class="sect2" title="REJECTED Command"><div class="titlepage"><div><div><h3 class="title"><a name="auth-command-rejected"></a>REJECTED Command</h3></div></div></div><p>

795

The REJECTED command indicates that the current authentication

796

exchange has failed, and further exchange of DATA is inappropriate.

797

The client would normally try another mechanism, or try providing

802

a list of supported mechanisms, it must provide the same list

803

each time it sends a REJECTED message. Clients are free to

804

ignore all lists received after the first.

805

</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="auth-command-ok"></a>OK Command</h3></div></div></div><p>

805

</p></div><div class="sect2" title="OK Command"><div class="titlepage"><div><div><h3 class="title"><a name="auth-command-ok"></a>OK Command</h3></div></div></div><p>

806

The OK command indicates that the client has been authenticated,

807

and that further communication will be a stream of D-Bus messages

808

(optionally encrypted, as negotiated) rather than this protocol.

818

</p><p>

819

The OK command has one argument, which is the GUID of the server.

820

See <a class="xref" href="#addresses" title="Server Addresses">the section called “Server Addresses”</a> for more on server GUIDs.

821

</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="auth-command-error"></a>ERROR Command</h3></div></div></div><p>

821

</p></div><div class="sect2" title="ERROR Command"><div class="titlepage"><div><div><h3 class="title"><a name="auth-command-error"></a>ERROR Command</h3></div></div></div><p>

822

The ERROR command indicates that either server or client did not

823

know a command, does not accept the given command in the current

824

context, or did not understand the arguments to the command. This

839

receiving an ERROR from applications that don't understand it. Thus the

840

ERROR feature of the auth protocol is an escape hatch that lets us

841

negotiate extensions or changes to the D-Bus protocol in the future.

842

</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="auth-examples"></a>Authentication examples</h3></div></div></div><p>

843

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

842

</p></div><div class="sect2" title="Authentication examples"><div class="titlepage"><div><div><h3 class="title"><a name="auth-examples"></a>Authentication examples</h3></div></div></div><p>

843

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

844

(MAGIC_COOKIE is a made up mechanism)

845

846

C: AUTH MAGIC_COOKIE 3138363935333137393635383634

847

S: OK 1234deadbeef

848

C: BEGIN

849

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

850

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

850

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

851

C: AUTH

852

S: REJECTED KERBEROS_V4 SKEY

853

C: AUTH SKEY 7ab83f32ee

856

S: OK 1234deadbeef

857

C: BEGIN

858

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

859

</p><div class="figure"><a name="id2789400"></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">

859

</p><div class="figure"><a name="id320480"></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">

860

C: FOOBAR

861

S: ERROR

862

C: AUTH MAGIC_COOKIE 3736343435313230333039

863

S: OK 1234deadbeef

864

C: BEGIN

865

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

866

</p><div class="figure"><a name="id2789418"></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">

866

</p><div class="figure"><a name="id320496"></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">

867

C: AUTH MAGIC_COOKIE 3736343435313230333039

868

S: REJECTED KERBEROS_V4 SKEY

869

C: AUTH SKEY 7ab83f32ee

872

S: OK 1234deadbeef

873

C: BEGIN

874

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

875

</p><div class="figure"><a name="id2789437"></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">

875

</p><div class="figure"><a name="id320513"></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">

876

C: AUTH MAGIC_COOKIE 3736343435313230333039

877

S: REJECTED KERBEROS_V4 SKEY

878

C: AUTH SKEY 7ab83f32ee

885

S: OK 1234deadbeef

886

C: BEGIN

887

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

888

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

888

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

889

C: AUTH MAGIC_COOKIE 3736343435313230333039

890

S: REJECTED KERBEROS_V4 SKEY

891

C: AUTH SKEY 7ab83f32ee

898

S: OK 1234deadbeef

899

C: BEGIN

900

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

901

</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="auth-states"></a>Authentication state diagrams</h3></div></div></div><p>

901

</p></div><div class="sect2" title="Authentication state diagrams"><div class="titlepage"><div><div><h3 class="title"><a name="auth-states"></a>Authentication state diagrams</h3></div></div></div><p>

902

This section documents the auth protocol in terms of

903

a state machine for the client and the server. This is

904

probably the most robust way to implement the protocol.

905

</p><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="auth-states-client"></a>Client states</h4></div></div></div><p>

905

</p><div class="sect3" title="Client states"><div class="titlepage"><div><div><h4 class="title"><a name="auth-states-client"></a>Client states</h4></div></div></div><p>

906

To more precisely describe the interaction between the

907

protocol state machine and the authentication mechanisms the

908

following notation is used: MECH(CHALL) means that the

909

server challenge CHALL was fed to the mechanism MECH, which

910

returns one of

911

912

</p><div class="itemizedlist"><ul type="disc"><li><p>

912

</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>

913

CONTINUE(RESP) means continue the auth conversation

914

and send RESP as the response to the server;

915

</p></li><li><p>

915

</p></li><li class="listitem"><p>

916

OK(RESP) means that after sending RESP to the server

917

the client side of the auth conversation is finished

918

and the server should return "OK";

919

</p></li><li><p>

919

</p></li><li class="listitem"><p>

920

ERROR means that CHALL was invalid and could not be

921

processed.

922

</p></li></ul></div><p>

936

used to decide which AUTH command to send. When the list is

937

exhausted, the client should give up and close the

938

connection.

939

</p><p><b><span class="emphasis"><em>WaitingForData</em></span>.�</b>

940

</p><div class="itemizedlist"><ul type="disc"><li><p>

939

</p><p title="WaitingForData"><b><span class="emphasis"><em>WaitingForData</em></span>.�</b>

940

</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>

941

Receive DATA CHALL

942

</p><table class="simplelist" border="0" summary="Simple list"><tr><td>

942

</p><table border="0" summary="Simple list" class="simplelist"><tr><td>

943

MECH(CHALL) returns CONTINUE(RESP) → send

944

DATA RESP, goto

945

<span class="emphasis"><em>WaitingForData</em></span>

950

MECH(CHALL) returns ERROR → send ERROR

951

[msg], goto <span class="emphasis"><em>WaitingForData</em></span>

952

</td></tr></table><p>

953

</p></li><li><p>

953

</p></li><li class="listitem"><p>

954

Receive REJECTED [mechs] →

955

send AUTH [next mech], goto

956

WaitingForData or <span class="emphasis"><em>WaitingForOK</em></span>

957

</p></li><li><p>

957

</p></li><li class="listitem"><p>

958

Receive ERROR → send

959

CANCEL, goto

960

<span class="emphasis"><em>WaitingForReject</em></span>

961

</p></li><li><p>

961

</p></li><li class="listitem"><p>

962

Receive OK → send

963

BEGIN, terminate auth

964

conversation, authenticated

965

</p></li><li><p>

965

</p></li><li class="listitem"><p>

966

Receive anything else → send

967

ERROR, goto

968

<span class="emphasis"><em>WaitingForData</em></span>

969

</p></li></ul></div><p>

970

</p><p><b><span class="emphasis"><em>WaitingForOK</em></span>.�</b>

971

</p><div class="itemizedlist"><ul type="disc"><li><p>

969

</p></li></ul></div><p title="WaitingForData">

970

</p><p title="WaitingForOK"><b><span class="emphasis"><em>WaitingForOK</em></span>.�</b>

971

</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>

972

Receive OK → send BEGIN, terminate auth

973

conversation, <span class="emphasis"><em>authenticated</em></span>

974

</p></li><li><p>

974

</p></li><li class="listitem"><p>

975

Receive REJECT [mechs] → send AUTH [next mech],

976

goto <span class="emphasis"><em>WaitingForData</em></span> or

977

<span class="emphasis"><em>WaitingForOK</em></span>

978

</p></li><li><p>

978

</p></li><li class="listitem"><p>

979

Receive DATA → send CANCEL, goto

980

<span class="emphasis"><em>WaitingForReject</em></span>

981

</p></li><li><p>

981

</p></li><li class="listitem"><p>

982

Receive ERROR → send CANCEL, goto

983

<span class="emphasis"><em>WaitingForReject</em></span>

984

</p></li><li><p>

984

</p></li><li class="listitem"><p>

985

Receive anything else → send ERROR, goto

986

<span class="emphasis"><em>WaitingForOK</em></span>

987

</p></li></ul></div><p>

988

</p><p><b><span class="emphasis"><em>WaitingForReject</em></span>.�</b>

989

</p><div class="itemizedlist"><ul type="disc"><li><p>

987

</p></li></ul></div><p title="WaitingForOK">

988

</p><p title="WaitingForReject"><b><span class="emphasis"><em>WaitingForReject</em></span>.�</b>

989

</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>

990

Receive REJECT [mechs] → send AUTH [next mech],

991

goto <span class="emphasis"><em>WaitingForData</em></span> or

992

<span class="emphasis"><em>WaitingForOK</em></span>

993

</p></li><li><p>

993

</p></li><li class="listitem"><p>

994

Receive anything else → terminate auth

995

conversation, disconnect

996

</p></li></ul></div><p>

997

</p></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="auth-states-server"></a>Server states</h4></div></div></div><p>

996

</p></li></ul></div><p title="WaitingForReject">

997

</p></div><div class="sect3" title="Server states"><div class="titlepage"><div><div><h4 class="title"><a name="auth-states-server"></a>Server states</h4></div></div></div><p>

998

For the server MECH(RESP) means that the client response

999

RESP was fed to the the mechanism MECH, which returns one of

1000

1001

</p><div class="itemizedlist"><ul type="disc"><li><p>

1001

</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>

1002

CONTINUE(CHALL) means continue the auth conversation and

1003

send CHALL as the challenge to the client;

1004

</p></li><li><p>

1004

</p></li><li class="listitem"><p>

1005

OK means that the client has been successfully

1006

authenticated;

1007

</p></li><li><p>

1007

</p></li><li class="listitem"><p>

1008

REJECT means that the client failed to authenticate or

1009

there was an error in RESP.

1010

</p></li></ul></div><p>

1013

<span class="emphasis"><em>WaitingForAuth</em></span>. If the client is

1014

rejected too many times the server must disconnect the

1015

client.

1016

</p><p><b><span class="emphasis"><em>WaitingForAuth</em></span>.�</b>

1017

</p><div class="itemizedlist"><ul type="disc"><li><p>

1016

</p><p title="WaitingForAuth"><b><span class="emphasis"><em>WaitingForAuth</em></span>.�</b>

1017

</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>

1018

Receive AUTH → send REJECTED [mechs], goto

1019

<span class="emphasis"><em>WaitingForAuth</em></span>

1020

</p></li><li><p>

1020

</p></li><li class="listitem"><p>

1021

Receive AUTH MECH RESP

1022

1023

</p><table class="simplelist" border="0" summary="Simple list"><tr><td>

1023

</p><table border="0" summary="Simple list" class="simplelist"><tr><td>

1024

MECH not valid mechanism → send REJECTED

1025

[mechs], goto

1026

<span class="emphasis"><em>WaitingForAuth</em></span>

1036

[mechs], goto

1037

<span class="emphasis"><em>WaitingForAuth</em></span>

1038

</td></tr></table><p>

1039

</p></li><li><p>

1039

</p></li><li class="listitem"><p>

1040

Receive BEGIN → terminate

1041

auth conversation, disconnect

1042

</p></li><li><p>

1042

</p></li><li class="listitem"><p>

1043

Receive ERROR → send REJECTED [mechs], goto

1044

<span class="emphasis"><em>WaitingForAuth</em></span>

1045

</p></li><li><p>

1045

</p></li><li class="listitem"><p>

1046

Receive anything else → send

1047

ERROR, goto

1048

<span class="emphasis"><em>WaitingForAuth</em></span>

1049

</p></li></ul></div><p>

1050

</p><p><b><span class="emphasis"><em>WaitingForData</em></span>.�</b>

1051

</p><div class="itemizedlist"><ul type="disc"><li><p>

1049

</p></li></ul></div><p title="WaitingForAuth">

1050

</p><p title="WaitingForData"><b><span class="emphasis"><em>WaitingForData</em></span>.�</b>

1051

</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>

1052

Receive DATA RESP

1053

</p><table class="simplelist" border="0" summary="Simple list"><tr><td>

1053

</p><table border="0" summary="Simple list" class="simplelist"><tr><td>

1054

MECH(RESP) returns CONTINUE(CHALL) → send

1055

DATA CHALL, goto

1056

<span class="emphasis"><em>WaitingForData</em></span>

1062

[mechs], goto

1063

<span class="emphasis"><em>WaitingForAuth</em></span>

1064

</td></tr></table><p>

1065

</p></li><li><p>

1065

</p></li><li class="listitem"><p>

1066

Receive BEGIN → terminate auth conversation,

1067

disconnect

1068

</p></li><li><p>

1068

</p></li><li class="listitem"><p>

1069

Receive CANCEL → send REJECTED [mechs], goto

1070

<span class="emphasis"><em>WaitingForAuth</em></span>

1071

</p></li><li><p>

1071

</p></li><li class="listitem"><p>

1072

Receive ERROR → send REJECTED [mechs], goto

1073

<span class="emphasis"><em>WaitingForAuth</em></span>

1074

</p></li><li><p>

1074

</p></li><li class="listitem"><p>

1075

Receive anything else → send ERROR, goto

1076

<span class="emphasis"><em>WaitingForData</em></span>

1077

</p></li></ul></div><p>

1078

</p><p><b><span class="emphasis"><em>WaitingForBegin</em></span>.�</b>

1079

</p><div class="itemizedlist"><ul type="disc"><li><p>

1077

</p></li></ul></div><p title="WaitingForData">

1078

</p><p title="WaitingForBegin"><b><span class="emphasis"><em>WaitingForBegin</em></span>.�</b>

1079

</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>

1080

Receive BEGIN → terminate auth conversation,

1081

client authenticated

1082

</p></li><li><p>

1082

</p></li><li class="listitem"><p>

1083

Receive CANCEL → send REJECTED [mechs], goto

1084

<span class="emphasis"><em>WaitingForAuth</em></span>

1085

</p></li><li><p>

1085

</p></li><li class="listitem"><p>

1086

Receive ERROR → send REJECTED [mechs], goto

1087

<span class="emphasis"><em>WaitingForAuth</em></span>

1088

</p></li><li><p>

1088

</p></li><li class="listitem"><p>

1089

Receive anything else → send ERROR, goto

1090

<span class="emphasis"><em>WaitingForBegin</em></span>

1091

</p></li></ul></div><p>

1092

</p></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="auth-mechanisms"></a>Authentication mechanisms</h3></div></div></div><p>

1091

</p></li></ul></div><p title="WaitingForBegin">

1092

</p></div></div><div class="sect2" title="Authentication mechanisms"><div class="titlepage"><div><div><h3 class="title"><a name="auth-mechanisms"></a>Authentication mechanisms</h3></div></div></div><p>

1093

This section describes some new authentication mechanisms.

1094

D-Bus also allows any standard SASL mechanism of course.

1095

</p><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="auth-mechanisms-sha"></a>DBUS_COOKIE_SHA1</h4></div></div></div><p>

1095

</p><div class="sect3" title="DBUS_COOKIE_SHA1"><div class="titlepage"><div><div><h4 class="title"><a name="auth-mechanisms-sha"></a>DBUS_COOKIE_SHA1</h4></div></div></div><p>

1096

The DBUS_COOKIE_SHA1 mechanism is designed to establish that a client

1097

has the ability to read a private file owned by the user being

1098

authenticated. If the client can prove that it has access to a secret

1100

Thus the security of DBUS_COOKIE_SHA1 depends on a secure home

1101

directory.

1102

</p><p>

1103

Throughout this description, "hex encoding" must output the digits

1104

from a to f in lower-case; the digits A to F must not be used

1105

in the DBUS_COOKIE_SHA1 mechanism.

1106

</p><p>

1103

1107

Authentication proceeds as follows:

1104

</p><div class="itemizedlist"><ul type="disc"><li><p>

1108

</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>

1105

1109

The client sends the username it would like to authenticate

1106

1110

as, hex-encoded.

1107

</p></li><li><p>

1111

</p></li><li class="listitem"><p>

1108

1112

The server sends the name of its "cookie context" (see below); a

1109

1113

space character; the integer ID of the secret cookie the client

1110

1114

must demonstrate knowledge of; a space character; then a

1111

1115

randomly-generated challenge string, all of this hex-encoded into

1112

1116

one, single string.

1113

</p></li><li><p>

1117

</p></li><li class="listitem"><p>

1114

1118

The client locates the cookie and generates its own

1115

1119

randomly-generated challenge string. The client then concatenates

1116

1120

the server's decoded challenge, a ":" character, its own challenge,

1118

1122

of this composite string as a hex digest. It concatenates the

1119

1123

client's challenge string, a space character, and the SHA-1 hex

1120

1124

digest, hex-encodes the result and sends it back to the server.

1121

</p></li><li><p>

1125

</p></li><li class="listitem"><p>

1122

1126

The server generates the same concatenated string used by the

1123

1127

client and computes its SHA-1 hash. It compares the hash with

1124

1128

the hash received from the client; if the two hashes match, the

1142

1146

</p><p>

1143

1147

A cookie file contains one cookie per line. Each line

1144

1148

has three space-separated fields:

1145

</p><div class="itemizedlist"><ul type="disc"><li><p>

1149

</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>

1146

1150

The cookie ID number, which must be a non-negative integer and

1147

1151

may not be used twice in the same file.

1148

</p></li><li><p>

1152

</p></li><li class="listitem"><p>

1149

1153

The cookie's creation time, in UNIX seconds-since-the-epoch

1150

1154

format.

1151

</p></li><li><p>

1155

</p></li><li class="listitem"><p>

1152

1156

The cookie itself, a hex-encoded random block of bytes. The cookie

1153

1157

may be of any length, though obviously security increases

1154

1158

as the length increases.

1156

1160

</p><p>

1157

1161

Only server processes modify the cookie file.

1158

1162

They must do so with this procedure:

1159

</p><div class="itemizedlist"><ul type="disc"><li><p>

1163

</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>

1160

1164

Create a lockfile name by appending ".lock" to the name of the

1161

1165

cookie file. The server should attempt to create this file

1162

1166

using <code class="literal">O_CREAT | O_EXCL</code>. If file creation

1163

1167

fails, the lock fails. Servers should retry for a reasonable

1164

1168

period of time, then they may choose to delete an existing lock

1165

1169

to keep users from having to manually delete a stale

1166

lock. <sup>[<a name="id2737619" href="#ftn.id2737619" class="footnote">1</a>]</sup>

1167

</p></li><li><p>

1170

lock. <sup>[<a name="id321252" href="#ftn.id321252" class="footnote">1</a>]</sup>

1171

</p></li><li class="listitem"><p>

1168

1172

Once the lockfile has been created, the server loads the cookie

1169

1173

file. It should then delete any cookies that are old (the

1170

1174

timeout can be fairly short), or more than a reasonable

1172

1176

become permanent, if the clock was set far into the future

1173

1177

at some point). If no recent keys remain, the

1174

1178

server may generate a new key.

1175

</p></li><li><p>

1179

</p></li><li class="listitem"><p>

1176

1180

The pruned and possibly added-to cookie file

1177

1181

must be resaved atomically (using a temporary

1178

1182

file which is rename()'d).

1179

</p></li><li><p>

1183

</p></li><li class="listitem"><p>

1180

1184

The lock must be dropped by deleting the lockfile.

1181

1185

</p></li></ul></div><p>

1182

1186

</p><p>

1183

1187

Clients need not lock the file in order to load it,

1184

1188

because servers are required to save the file atomically.

1185

</p></div></div></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="addresses"></a>Server Addresses</h2></div></div></div><p>

1189

</p></div></div></div><div class="sect1" title="Server Addresses"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="addresses"></a>Server Addresses</h2></div></div></div><p>

1186

1190

Server addresses consist of a transport name followed by a colon, and

1187

1191

then an optional, comma-separated list of keys and values in the form key=value.

1188

1192

Each value is escaped.

1192

1196

Which is the address to a unix socket with the path /tmp/dbus-test.

1193

1197

</p><p>

1194

1198

Value escaping is similar to URI escaping but simpler.

1195

</p><div class="itemizedlist"><ul type="disc"><li><p>

1199

</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>

1196

1200

The set of optionally-escaped bytes is:

1197

1201

<code class="literal">[0-9A-Za-z_-/.\]</code>. To escape, each

1198

1202

<span class="emphasis"><em>byte</em></span> (note, not character) which is not in the

1200

1204

percent (<code class="literal">%</code>) and the value of the byte in hex.

1201

1205

The hex value must always be two digits, even if the first digit is

1202

1206

zero. The optionally-escaped bytes may be escaped if desired.

1203

</p></li><li><p>

1207

</p></li><li class="listitem"><p>

1204

1208

To unescape, append each byte in the value; if a byte is an ASCII

1205

1209

percent (<code class="literal">%</code>) character then append the following

1206

1210

hex value instead. It is an error if a <code class="literal">%</code> byte

1238

1242

to the first address and if that fails, it'll try to connect to

1239

1243

the next one specified, and so forth. For example

1240

1244

</p><pre class="programlisting">unix:path=/tmp/dbus-test;unix:path=/tmp/dbus-test2</pre><p>

1241

</p></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="transports"></a>Transports</h2></div></div></div><p>

1245

</p></div><div class="sect1" title="Transports"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="transports"></a>Transports</h2></div></div></div><p>

1242

1246

[FIXME we need to specify in detail each transport and its possible arguments]

1243

1247

1244

1248

Current transports include: unix domain sockets (including

1245

1249

abstract namespace on linux), TCP/IP, and a debug/testing transport using

1246

1250

in-process pipes. Future possible transports include one that

1247

1251

tunnels over X11 protocol.

1248

</p><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="transports-unix-domain-sockets"></a>Unix Domain Sockets</h3></div></div></div><p>

1252

</p><div class="sect2" title="Unix Domain Sockets"><div class="titlepage"><div><div><h3 class="title"><a name="transports-unix-domain-sockets"></a>Unix Domain Sockets</h3></div></div></div><p>

1249

1253

Unix domain sockets can be either paths in the file system or on Linux

1250

1254

kernels, they can be abstract which are similar to paths but

1251

1255

do not show up in the file system.

1256

1260

previous versions of D-Bus that would create sockets with a fixed

1257

1261

length path name. Names which were shorter than the fixed length

1258

1262

would be padded by Nul bytes.

1259

</p></div></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="naming-conventions"></a>Naming Conventions</h2></div></div></div><p>

1263

</p></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>

1260

1264

D-Bus namespaces are all lowercase and correspond to reversed domain

1261

1265

names, as with Java. e.g. "org.freedesktop"

1262

1266

</p><p>

1265

1269

</p><p>

1266

1270

Object paths are normally all lowercase with underscores used rather than

1267

1271

hyphens.

1268

</p></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="uuids"></a>UUIDs</h2></div></div></div><p>

1272

</p></div><div class="sect1" title="UUIDs"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="uuids"></a>UUIDs</h2></div></div></div><p>

1269

1273

A working D-Bus implementation uses universally-unique IDs in two places.

1270

1274

First, each server address has a UUID identifying the address,

1271

1275

as described in <a class="xref" href="#addresses" title="Server Addresses">the section called “Server Addresses”</a>. Second, each operating

1272

1276

system kernel instance running a D-Bus client or server has a UUID

1273

1277

identifying that kernel, retrieved by invoking the method

1274

org.freedesktop.DBus.Peer.GetMachineId() (see <a class="xref" href="#standard-interfaces-peer" title="org.freedesktop.DBus.Peer">the section called “org.freedesktop.DBus.Peer”</a>).

1278

org.freedesktop.DBus.Peer.GetMachineId() (see <a class="xref" href="#standard-interfaces-peer" title="org.freedesktop.DBus.Peer">the section called “<code class="literal">org.freedesktop.DBus.Peer</code>”</a>).

1275

1279

</p><p>

1276

1280

The term "UUID" in this document is intended literally, i.e. an

1277

1281

identifier that is universally unique. It is not intended to refer to

1292

1296

</p><p>

1293

1297

Implementations should, however, stick to random data for the first 96 bits

1294

1298

of the UUID.

1295

</p></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="standard-interfaces"></a>Standard Interfaces</h2></div></div></div><p>

1299

</p></div><div class="sect1" title="Standard Interfaces"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="standard-interfaces"></a>Standard Interfaces</h2></div></div></div><p>

1296

1300

See <a class="xref" href="#message-protocol-types-notation" title="Notation in this document">the section called “Notation in this document”</a> for details on

1297

1301

the notation used in this section. There are some standard interfaces

1298

1302

that may be useful across various D-Bus applications.

1299

</p><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="standard-interfaces-peer"></a><code class="literal">org.freedesktop.DBus.Peer</code></h3></div></div></div><p>

1303

</p><div class="sect2" title="org.freedesktop.DBus.Peer"><div class="titlepage"><div><div><h3 class="title"><a name="standard-interfaces-peer"></a><code class="literal">org.freedesktop.DBus.Peer</code></h3></div></div></div><p>

1300

1304

The <code class="literal">org.freedesktop.DBus.Peer</code> interface

1301

1305

has two methods:

1302

1306

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

1332

1336

is more robust.

1333

1337

</p><p>

1334

1338

<a class="xref" href="#uuids" title="UUIDs">the section called “UUIDs”</a> explains the format of the UUID.

1335

</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="standard-interfaces-introspectable"></a><code class="literal">org.freedesktop.DBus.Introspectable</code></h3></div></div></div><p>

1339

</p></div><div class="sect2" title="org.freedesktop.DBus.Introspectable"><div class="titlepage"><div><div><h3 class="title"><a name="standard-interfaces-introspectable"></a><code class="literal">org.freedesktop.DBus.Introspectable</code></h3></div></div></div><p>

1336

1340

This interface has one method:

1337

1341

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

1338

1342

org.freedesktop.DBus.Introspectable.Introspect (out STRING xml_data)

1344

1348

below it in the object path tree, and its properties.

1345

1349

</p><p>

1346

1350

<a class="xref" href="#introspection-format" title="Introspection Data Format">the section called “Introspection Data Format”</a> describes the format of this XML string.

1347

</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="standard-interfaces-properties"></a><code class="literal">org.freedesktop.DBus.Properties</code></h3></div></div></div><p>

1351

</p></div><div class="sect2" title="org.freedesktop.DBus.Properties"><div class="titlepage"><div><div><h3 class="title"><a name="standard-interfaces-properties"></a><code class="literal">org.freedesktop.DBus.Properties</code></h3></div></div></div><p>

1348

1352

Many native APIs will have a concept of object <em class="firstterm">properties</em>

1349

1353

or <em class="firstterm">attributes</em>. These can be exposed via the

1350

1354

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

1362

1366

</p><p>

1363

1367

The available properties and whether they are writable can be determined

1364

1368

by calling <code class="literal">org.freedesktop.DBus.Introspectable.Introspect</code>,

1365

see <a class="xref" href="#standard-interfaces-introspectable" title="org.freedesktop.DBus.Introspectable">the section called “org.freedesktop.DBus.Introspectable”</a>.

1369

see <a class="xref" href="#standard-interfaces-introspectable" title="org.freedesktop.DBus.Introspectable">the section called “<code class="literal">org.freedesktop.DBus.Introspectable</code>”</a>.

1366

1370

</p><p>

1367

1371

An empty string may be provided for the interface name; in this case,

1368

1372

if there are multiple properties on an object with the same name,

1369

1373

the results are undefined (picking one by according to an arbitrary

1370

1374

deterministic rule, or returning an error, are the reasonable

1371

1375

possibilities).

1372

</p></div></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="introspection-format"></a>Introspection Data Format</h2></div></div></div><p>

1373

As described in <a class="xref" href="#standard-interfaces-introspectable" title="org.freedesktop.DBus.Introspectable">the section called “org.freedesktop.DBus.Introspectable”</a>,

1376

</p></div></div><div class="sect1" title="Introspection Data Format"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="introspection-format"></a>Introspection Data Format</h2></div></div></div><p>

1377

As described in <a class="xref" href="#standard-interfaces-introspectable" title="org.freedesktop.DBus.Introspectable">the section called “<code class="literal">org.freedesktop.DBus.Introspectable</code>”</a>,

1374

1378

objects may be introspected at runtime, returning an XML string

1375

1379

that describes the object. The same XML format may be used in

1376

1380

other contexts as well, for example as an "IDL" for generating

1406

1410

</pre><p>

1407

1411

</p><p>

1408

1412

A more formal DTD and spec needs writing, but here are some quick notes.

1409

</p><div class="itemizedlist"><ul type="disc"><li><p>

1413

</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>

1410

1414

Only the root <node> element can omit the node name, as it's

1411

1415

known to be the object that was introspected. If the root

1412

1416

<node> does have a name attribute, it must be an absolute

1413

1417

object path. If child <node> have object paths, they must be

1414

1418

relative.

1415

</p></li><li><p>

1419

</p></li><li class="listitem"><p>

1416

1420

If a child <node> has any sub-elements, then they

1417

1421

must represent a complete introspection of the child.

1418

1422

If a child <node> is empty, then it may or may

1421

1425

knows that its children are "fast" to introspect

1422

1426

it can go ahead and return their information, but

1423

1427

otherwise it can omit it.

1424

</p></li><li><p>

1428

</p></li><li class="listitem"><p>

1425

1429

The direction element on <arg> may be omitted,

1426

1430

in which case it defaults to "in" for method calls

1427

1431

and "out" for signals. Signals only allow "out"

1428

1432

so while direction may be specified, it's pointless.

1429

</p></li><li><p>

1433

</p></li><li class="listitem"><p>

1430

1434

The possible directions are "in" and "out",

1431

1435

unlike CORBA there is no "inout"

1432

</p></li><li><p>

1436

</p></li><li class="listitem"><p>

1433

1437

The possible property access flags are

1434

1438

"readwrite", "read", and "write"

1435

</p></li><li><p>

1439

</p></li><li class="listitem"><p>

1436

1440

Multiple interfaces can of course be listed for

1437

1441

one <node>.

1438

</p></li><li><p>

1442

</p></li><li class="listitem"><p>

1439

1443

The "name" attribute on arguments is optional.

1440

1444

</p></li></ul></div><p>

1441

1445

</p><p>

1443

1447

"annotations", which are generic key/value pairs of metadata.

1444

1448

They are similar conceptually to Java's annotations and C# attributes.

1445

1449

Well-known annotations:

1446

</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></tbody></table></div></div><div class="sect1" lang="en"><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" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="message-bus-overview"></a>Message Bus Overview</h3></div></div></div><p>

1450

</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></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>

1447

1451

The message bus accepts connections from one or more applications.

1448

1452

Once connected, applications can exchange messages with other

1449

1453

applications that are also connected to the bus.

1494

1498

<code class="literal">com.yoyodyne.Screensaver</code>, then the ping would be

1495

1499

forwarded, and the Yoyodyne Corporation screensaver application would be

1496

1500

expected to reply to the ping.

1497

</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="message-bus-names"></a>Message Bus Names</h3></div></div></div><p>

1501

</p></div><div class="sect2" title="Message Bus Names"><div class="titlepage"><div><div><h3 class="title"><a name="message-bus-names"></a>Message Bus Names</h3></div></div></div><p>

1498

1502

Each connection has at least one name, assigned at connection time and

1499

1503

returned in response to the

1500

1504

<code class="literal">org.freedesktop.DBus.Hello</code> method call. This

1521

1525

the <code class="literal">org.freedesktop.DBus.RequestName</code> message. <a class="xref" href="#message-protocol-names-bus" title="Bus names">the section called “Bus names”</a> describes the format of a valid

1522

1526

name. These names can be released again using the

1523

1527

<code class="literal">org.freedesktop.DBus.ReleaseName</code> message.

1524

</p><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="bus-messages-request-name"></a><code class="literal">org.freedesktop.DBus.RequestName</code></h4></div></div></div><p>

1528

</p><div class="sect3" title="org.freedesktop.DBus.RequestName"><div class="titlepage"><div><div><h4 class="title"><a name="bus-messages-request-name"></a><code class="literal">org.freedesktop.DBus.RequestName</code></h4></div></div></div><p>

1525

1529

As a method:

1526

1530

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

1527

1531

UINT32 RequestName (in STRING name, in UINT32 flags)

1539

1543

maintains the DBUS_NAME_FLAG_ALLOW_REPLACEMENT and

1540

1544

DBUS_NAME_FLAG_DO_NOT_QUEUE settings from its latest RequestName

1541

1545

call. When RequestName is invoked the following occurs:

1542

</p><div class="itemizedlist"><ul type="disc"><li><p>

1546

</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>

1543

1547

If the method caller is currently the primary owner of the name,

1544

1548

the DBUS_NAME_FLAG_ALLOW_REPLACEMENT and DBUS_NAME_FLAG_DO_NOT_QUEUE

1545

1549

values are updated with the values from the new RequestName call,

1546

1550

and nothing further happens.

1547

</p></li><li><p>

1551

</p></li><li class="listitem"><p>

1548

1552

If the current primary owner (head of the queue) has

1549

1553

DBUS_NAME_FLAG_ALLOW_REPLACEMENT set, and the RequestName

1550

1554

invocation has the DBUS_NAME_FLAG_REPLACE_EXISTING flag, then

1553

1557

second position in the queue. If the caller of RequestName was

1554

1558

in the queue previously its flags are updated with the values from

1555

1559

the new RequestName in addition to moving it to the head of the queue.

1556

</p></li><li><p>

1560

</p></li><li class="listitem"><p>

1557

1561

If replacement is not possible, and the method caller is

1558

1562

currently in the queue but not the primary owner, its flags are

1559

1563

updated with the values from the new RequestName call.

1560

</p></li><li><p>

1564

</p></li><li class="listitem"><p>

1561

1565

If replacement is not possible, and the method caller is

1562

1566

currently not in the queue, the method caller is appended to the

1563

1567

queue.

1564

</p></li><li><p>

1568

</p></li><li class="listitem"><p>

1565

1569

If any connection in the queue has DBUS_NAME_FLAG_DO_NOT_QUEUE

1566

1570

set and is not the primary owner, it is removed from the

1567

1571

queue. This can apply to the previous primary owner (if it

1636

1640

DBUS_NAME_FLAG_ALLOW_REPLACEMENT was not specified by the

1637

1641

current owner, or DBUS_NAME_FLAG_REPLACE_EXISTING was not

1638

1642

specified by the requesting application.</td></tr><tr><td>DBUS_REQUEST_NAME_REPLY_ALREADY_OWNER</td><td>4</td><td>The application trying to request ownership of a name is already the owner of it.</td></tr></tbody></table></div><p>

1639

</p></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="bus-messages-release-name"></a><code class="literal">org.freedesktop.DBus.ReleaseName</code></h4></div></div></div><p>

1643

</p></div><div class="sect3" title="org.freedesktop.DBus.ReleaseName"><div class="titlepage"><div><div><h4 class="title"><a name="bus-messages-release-name"></a><code class="literal">org.freedesktop.DBus.ReleaseName</code></h4></div></div></div><p>

1640

1644

As a method:

1641

1645

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

1642

1646

UINT32 ReleaseName (in STRING name)

1665

1669

in the queue for the name and has now been removed from the

1666

1670

queue.</td></tr><tr><td>DBUS_RELEASE_NAME_REPLY_NON_EXISTENT</td><td>2</td><td>The given name does not exist on this bus.</td></tr><tr><td>DBUS_RELEASE_NAME_REPLY_NOT_OWNER</td><td>3</td><td>The caller was not the primary owner of this name,

1667

1671

and was also not waiting in the queue to own this name.</td></tr></tbody></table></div><p>

1668

</p></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="message-bus-routing"></a>Message Bus Message Routing</h3></div></div></div><p>

1672

</p></div></div><div class="sect2" title="Message Bus Message Routing"><div class="titlepage"><div><div><h3 class="title"><a name="message-bus-routing"></a>Message Bus Message Routing</h3></div></div></div><p>

1669

1673

FIXME

1670

</p><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="message-bus-routing-match-rules"></a>Match Rules</h4></div></div></div><p>

1674

</p><div class="sect3" title="Match Rules"><div class="titlepage"><div><div><h4 class="title"><a name="message-bus-routing-match-rules"></a>Match Rules</h4></div></div></div><p>

1671

1675

An important part of the message bus routing protocol is match

1672

1676

rules. Match rules describe what messages can be sent to a client

1673

1677

based on the contents of the message. When a message is routed

1712

1716

would match messages with first arguments of '/', '/aa/',

1713

1717

'/aa/bb/', '/aa/bb/cc/' and '/aa/bb/cc'. It would not match

1714

1718

messages with first arguments of '/aa/b', '/aa' or even '/aa/bb'.</td></tr></tbody></table></div><p>

1715

</p></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="message-bus-starting-services"></a>Message Bus Starting Services</h3></div></div></div><p>

1719

</p></div></div><div class="sect2" title="Message Bus Starting Services"><div class="titlepage"><div><div><h3 class="title"><a name="message-bus-starting-services"></a>Message Bus Starting Services</h3></div></div></div><p>

1716

1720

The message bus can start applications on behalf of other applications.

1717

1721

In CORBA terms, this would be called <em class="firstterm">activation</em>.

1718

1722

An application that can be started in this way is called a

1743

1747

must be namespaced using the same mechanism as messages and service

1744

1748

names.

1745

1749

1746

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

1750

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

1747

1751

# Sample service description file

1748

1752

[D-BUS Service]

1749

1753

Names=org.freedesktop.ConfigurationDatabase;org.gnome.GConf;

1775

1779

in the .service file, by the client, or just a global value

1776

1780

and if the client being activated fails to connect within that

1777

1781

timeout, an error should be sent back.]

1778

</p><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="message-bus-starting-services-scope"></a>Message Bus Service Scope</h4></div></div></div><p>

1782

</p><div class="sect3" title="Message Bus Service Scope"><div class="titlepage"><div><div><h4 class="title"><a name="message-bus-starting-services-scope"></a>Message Bus Service Scope</h4></div></div></div><p>

1779

1783

The "scope" of a service is its "per-", such as per-session,

1780

1784

per-machine, per-home-directory, or per-display. The reference

1781

1785

implementation doesn't yet support starting services in a different

1795

1799

want a single bus spanning all sessions using a given display.

1796

1800

So we might set a <code class="literal">_DBUS_DISPLAY_BUS_ADDRESS</code>

1797

1801

property on screen 0 of the display, pointing to this bus.

1798

</p></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="message-bus-types"></a>Well-known Message Bus Instances</h3></div></div></div><p>

1802

</p></div></div><div class="sect2" title="Well-known Message Bus Instances"><div class="titlepage"><div><div><h3 class="title"><a name="message-bus-types"></a>Well-known Message Bus Instances</h3></div></div></div><p>

1799

1803

Two standard message bus instances are defined here, along with how

1800

1804

to locate them and where their service files live.

1801

</p><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="message-bus-types-login"></a>Login session message bus</h4></div></div></div><p>

1805

</p><div class="sect3" title="Login session message bus"><div class="titlepage"><div><div><h4 class="title"><a name="message-bus-types-login"></a>Login session message bus</h4></div></div></div><p>

1802

1806

Each time a user logs in, a <em class="firstterm">login session message

1803

1807

bus</em> may be started. All applications in the user's login

1804

1808

session may interact with one another using this message bus.

1815

1819

[FIXME specify location of .service files, probably using

1816

1820

DESKTOP_DIRS etc. from basedir specification, though login session

1817

1821

bus is not really desktop-specific]

1818

</p></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="message-bus-types-system"></a>System message bus</h4></div></div></div><p>

1822

</p></div><div class="sect3" title="System message bus"><div class="titlepage"><div><div><h4 class="title"><a name="message-bus-types-system"></a>System message bus</h4></div></div></div><p>

1819

1823

A computer may have a <em class="firstterm">system message bus</em>,

1820

1824

accessible to all applications on the system. This message bus may be

1821

1825

used to broadcast system events, such as adding new hardware devices,

1826

1830

variable. If that variable is not set, applications should try

1827

1831

to connect to the well-known address

1828

1832

<code class="literal">unix:path=/var/run/dbus/system_bus_socket</code>.

1829

1833

1830

1834

</p><p>

1831

1835

[FIXME specify location of system bus .service files]

1832

</p></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="message-bus-messages"></a>Message Bus Messages</h3></div></div></div><p>

1836

</p></div></div><div class="sect2" title="Message Bus Messages"><div class="titlepage"><div><div><h3 class="title"><a name="message-bus-messages"></a>Message Bus Messages</h3></div></div></div><p>

1833

1837

The special message bus name <code class="literal">org.freedesktop.DBus</code>

1834

1838

responds to a number of additional messages.

1835

</p><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="bus-messages-hello"></a><code class="literal">org.freedesktop.DBus.Hello</code></h4></div></div></div><p>

1839

</p><div class="sect3" title="org.freedesktop.DBus.Hello"><div class="titlepage"><div><div><h4 class="title"><a name="bus-messages-hello"></a><code class="literal">org.freedesktop.DBus.Hello</code></h4></div></div></div><p>

1836

1840

As a method:

1837

1841

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

1838

1842

STRING Hello ()

1851

1855

There is no corresponding "disconnect" request; if a client wishes to

1852

1856

disconnect from the bus, it simply closes the socket (or other

1853

1857

communication channel).

1854

</p></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="bus-messages-list-names"></a><code class="literal">org.freedesktop.DBus.ListNames</code></h4></div></div></div><p>

1858

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

1855

1859

As a method:

1856

1860

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

1857

1861

ARRAY of STRING ListNames ()

1860

1864

</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>Array of strings where each string is a bus name</td></tr></tbody></table></div><p>

1861

1865

</p><p>

1862

1866

Returns a list of all currently-owned names on the bus.

1863

</p></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="bus-messages-list-activatable-names"></a><code class="literal">org.freedesktop.DBus.ListActivatableNames</code></h4></div></div></div><p>

1867

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

1864

1868

As a method:

1865

1869

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

1866

1870

ARRAY of STRING ListActivatableNames ()

1869

1873

</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>Array of strings where each string is a bus name</td></tr></tbody></table></div><p>

1870

1874

</p><p>

1871

1875

Returns a list of all names that can be activated on the bus.

1872

</p></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="bus-messages-name-exists"></a><code class="literal">org.freedesktop.DBus.NameHasOwner</code></h4></div></div></div><p>

1876

</p></div><div class="sect3" title="org.freedesktop.DBus.NameHasOwner"><div class="titlepage"><div><div><h4 class="title"><a name="bus-messages-name-exists"></a><code class="literal">org.freedesktop.DBus.NameHasOwner</code></h4></div></div></div><p>

1873

1877

As a method:

1874

1878

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

1875

1879

BOOLEAN NameHasOwner (in STRING name)

1880

1884

</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>BOOLEAN</td><td>Return value, true if the name exists</td></tr></tbody></table></div><p>

1881

1885

</p><p>

1882

1886

Checks if the specified name exists (currently has an owner).

1883

</p></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="bus-messages-name-owner-changed"></a><code class="literal">org.freedesktop.DBus.NameOwnerChanged</code></h4></div></div></div><p>

1887

</p></div><div class="sect3" title="org.freedesktop.DBus.NameOwnerChanged"><div class="titlepage"><div><div><h4 class="title"><a name="bus-messages-name-owner-changed"></a><code class="literal">org.freedesktop.DBus.NameOwnerChanged</code></h4></div></div></div><p>

1884

1888

This is a signal:

1885

1889

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

1886

1890

NameOwnerChanged (STRING name, STRING old_owner, STRING new_owner)

1891

1895

This signal indicates that the owner of a name has changed.

1892

1896

It's also the signal to use to detect the appearance of

1893

1897

new names on the bus.

1894

</p></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="bus-messages-name-lost"></a><code class="literal">org.freedesktop.DBus.NameLost</code></h4></div></div></div><p>

1898

</p></div><div class="sect3" title="org.freedesktop.DBus.NameLost"><div class="titlepage"><div><div><h4 class="title"><a name="bus-messages-name-lost"></a><code class="literal">org.freedesktop.DBus.NameLost</code></h4></div></div></div><p>

1895

1899

This is a signal:

1896

1900

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

1897

1901

NameLost (STRING name)

1901

1905

</p><p>

1902

1906

This signal is sent to a specific application when it loses

1903

1907

ownership of a name.

1904

</p></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="bus-messages-name-acquired"></a><code class="literal">org.freedesktop.DBus.NameAcquired</code></h4></div></div></div><p>

1908

</p></div><div class="sect3" title="org.freedesktop.DBus.NameAcquired"><div class="titlepage"><div><div><h4 class="title"><a name="bus-messages-name-acquired"></a><code class="literal">org.freedesktop.DBus.NameAcquired</code></h4></div></div></div><p>

1905

1909

This is a signal:

1906

1910

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

1907

1911

NameAcquired (STRING name)

1911

1915

</p><p>

1912

1916

This signal is sent to a specific application when it gains

1913

1917

ownership of a name.

1914

</p></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="bus-messages-start-service-by-name"></a><code class="literal">org.freedesktop.DBus.StartServiceByName</code></h4></div></div></div><p>

1918

</p></div><div class="sect3" title="org.freedesktop.DBus.StartServiceByName"><div class="titlepage"><div><div><h4 class="title"><a name="bus-messages-start-service-by-name"></a><code class="literal">org.freedesktop.DBus.StartServiceByName</code></h4></div></div></div><p>

1915

1919

As a method:

1916

1920

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

1917

1921

UINT32 StartServiceByName (in STRING name, in UINT32 flags)

1925

1929

</p><p>

1926

1930

The return value can be one of the following values:

1927

1931

</p><div class="informaltable"><table border="1"><colgroup><col><col><col></colgroup><thead><tr><th>Identifier</th><th>Value</th><th>Description</th></tr></thead><tbody><tr><td>DBUS_START_REPLY_SUCCESS</td><td>1</td><td>The service was successfully started.</td></tr><tr><td>DBUS_START_REPLY_ALREADY_RUNNING</td><td>2</td><td>A connection already owns the given name.</td></tr></tbody></table></div><p>

1928

</p></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="bus-messages-update-activation-environment"></a><code class="literal">org.freedesktop.DBus.UpdateActivationEnvironment</code></h4></div></div></div><p>

1932

</p></div><div class="sect3" title="org.freedesktop.DBus.UpdateActivationEnvironment"><div class="titlepage"><div><div><h4 class="title"><a name="bus-messages-update-activation-environment"></a><code class="literal">org.freedesktop.DBus.UpdateActivationEnvironment</code></h4></div></div></div><p>

1929

1933

As a method:

1930

1934

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

1931

1935

UpdateActivationEnvironment (in ARRAY of DICT<STRING,STRING> environment)

1935

1939

Normally, session bus activated services inherit the environment of the bus daemon. This method adds to or modifies that environment when activating services.

1936

1940

</p><p>

1937

1941

Some bus instances, such as the standard system bus, may disable access to this method for some or all callers.

1938

</p></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="bus-messages-get-name-owner"></a><code class="literal">org.freedesktop.DBus.GetNameOwner</code></h4></div></div></div><p>

1942

</p></div><div class="sect3" title="org.freedesktop.DBus.GetNameOwner"><div class="titlepage"><div><div><h4 class="title"><a name="bus-messages-get-name-owner"></a><code class="literal">org.freedesktop.DBus.GetNameOwner</code></h4></div></div></div><p>

1939

1943

As a method:

1940

1944

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

1941

1945

STRING GetNameOwner (in STRING name)

1947

1951

Returns the unique connection name of the primary owner of the name

1948

1952

given. If the requested name doesn't have an owner, returns a

1949

1953

<code class="literal">org.freedesktop.DBus.Error.NameHasNoOwner</code> error.

1950

</p></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="bus-messages-get-connection-unix-user"></a><code class="literal">org.freedesktop.DBus.GetConnectionUnixUser</code></h4></div></div></div><p>

1954

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

1951

1955

As a method:

1952

1956

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

1953

1957

UINT32 GetConnectionUnixUser (in STRING connection_name)

1959

1963

Returns the unix uid of the process connected to the server. If unable to

1960

1964

determine it, a <code class="literal">org.freedesktop.DBus.Error.Failed</code>

1961

1965

error is returned.

1962

</p></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="bus-messages-add-match"></a><code class="literal">org.freedesktop.DBus.AddMatch</code></h4></div></div></div><p>

1966

</p></div><div class="sect3" title="org.freedesktop.DBus.AddMatch"><div class="titlepage"><div><div><h4 class="title"><a name="bus-messages-add-match"></a><code class="literal">org.freedesktop.DBus.AddMatch</code></h4></div></div></div><p>

1963

1967

As a method:

1964

1968

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

1965

1969

AddMatch (in STRING rule)

1969

1973

Adds a match rule to match messages going through the message bus (see <a class="xref" href="#message-bus-routing-match-rules" title="Match Rules">the section called “Match Rules”</a>).

1970

1974

If the bus does not have enough resources the <code class="literal">org.freedesktop.DBus.Error.OOM</code>

1971

1975

error is returned.

1972

</p></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="bus-messages-remove-match"></a><code class="literal">org.freedesktop.DBus.RemoveMatch</code></h4></div></div></div><p>

1976

</p></div><div class="sect3" title="org.freedesktop.DBus.RemoveMatch"><div class="titlepage"><div><div><h4 class="title"><a name="bus-messages-remove-match"></a><code class="literal">org.freedesktop.DBus.RemoveMatch</code></h4></div></div></div><p>

1973

1977

As a method:

1974

1978

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

1975

1979

RemoveMatch (in STRING rule)

1979

1983

Removes the first rule that matches (see <a class="xref" href="#message-bus-routing-match-rules" title="Match Rules">the section called “Match Rules”</a>).

1980

1984

If the rule is not found the <code class="literal">org.freedesktop.DBus.Error.MatchRuleNotFound</code>

1981

1985

error is returned.

1982

</p></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="bus-messages-get-id"></a><code class="literal">org.freedesktop.DBus.GetId</code></h4></div></div></div><p>

1986

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

1983

1987

As a method:

1984

1988

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

1985

1989

GetId (out STRING id)

1990

1994

bus daemon is listening on (TCP, UNIX domain socket, etc.) and its format is described in

1991

1995

<a class="xref" href="#uuids" title="UUIDs">the section called “UUIDs”</a>. Each address the bus is listening on also has its own unique

1992

1996

ID, as described in <a class="xref" href="#addresses" title="Server Addresses">the section called “Server Addresses”</a>. The per-bus and per-address IDs are not related.

1993

There is also a per-machine ID, described in <a class="xref" href="#standard-interfaces-peer" title="org.freedesktop.DBus.Peer">the section called “org.freedesktop.DBus.Peer”</a> and returned

1997

There is also a per-machine ID, described in <a class="xref" href="#standard-interfaces-peer" title="org.freedesktop.DBus.Peer">the section called “<code class="literal">org.freedesktop.DBus.Peer</code>”</a> and returned

1994

1998

by org.freedesktop.DBus.Peer.GetMachineId().

1995

1999

For a desktop session bus, the bus ID can be used as a way to uniquely identify a user's session.

1996

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

2000

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

1997

2001

This glossary defines some of the terms used in this specification.

1998

2002

</p><dl><dt><a name="term-bus-name"></a>Bus Name</dt><dd><p>

1999

2003

The message bus maintains an association between names and

2067

2071

message bus. This name will never change owner, and will be unique

2068

2072

(never reused during the lifetime of the message bus).

2069

2073

It will begin with a ':' character.

2070

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

2074

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

2071

2075

locking <code class="literal">fcntl()</code> because real locking

2072

2076

implementations are still flaky on network

2073

filesystems.</p></div><div class="footnote"><p><sup>[<a name="ftn.id2790412" href="#id2790412" class="para">2</a>] </sup>

2077

filesystems.</p></div><div class="footnote"><p><sup>[<a name="ftn.id323183" href="#id323183" class="para">2</a>] </sup>

2074

2078

The D-Bus reference implementation actually honors the

2075

2079

<code class="literal">$(localstatedir)</code> configure option

2076

2080

for this address, on both client and server side.