~ubuntu-branches/ubuntu/oneiric/dbus/oneiric-security : revision 1.1.19

1

<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>D-Bus Tutorial</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 Tutorial</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><code class="email"><<a class="email" href="mailto:hp@pobox.com">hp@pobox.com</a>></code></p></div></div></div><div class="author"><h3 class="author"><span class="firstname">David</span> <span class="surname">Wheeler</span></h3></div><div class="author"><h3 class="author"><span class="firstname">John</span> <span class="surname">Palmieri</span></h3><div class="affiliation"><span class="orgname">Red Hat, Inc.<br></span><div class="address"><p><code class="email"><<a class="email" href="mailto:johnp@redhat.com">johnp@redhat.com</a>></code></p></div></div></div><div class="author"><h3 class="author"><span class="firstname">Colin</span> <span class="surname">Walters</span></h3><div class="affiliation"><span class="orgname">Red Hat, Inc.<br></span><div class="address"><p><code class="email"><<a class="email" href="mailto:walters@redhat.com">walters@redhat.com</a>></code></p></div></div></div></div></div><div><p class="releaseinfo">Version 0.5.0</p></div></div><hr></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="sect1"><a href="#meta">Tutorial Work In Progress</a></span></dt><dt><span class="sect1"><a href="#whatis">What is D-Bus?</a></span></dt><dd><dl><dt><span class="sect2"><a href="#uses">D-Bus applications</a></span></dt></dl></dd><dt><span class="sect1"><a href="#concepts">Concepts</a></span></dt><dd><dl><dt><span class="sect2"><a href="#objects">Native Objects and Object Paths</a></span></dt><dt><span class="sect2"><a href="#members">Methods and Signals</a></span></dt><dt><span class="sect2"><a href="#interfaces">Interfaces</a></span></dt><dt><span class="sect2"><a href="#proxies">Proxies</a></span></dt><dt><span class="sect2"><a href="#bus-names">Bus Names</a></span></dt><dt><span class="sect2"><a href="#addresses">Addresses</a></span></dt><dt><span class="sect2"><a href="#bigpicture">Big Conceptual Picture</a></span></dt><dt><span class="sect2"><a href="#messages">Messages - Behind the Scenes</a></span></dt><dt><span class="sect2"><a href="#callprocedure">Calling a Method - Behind the Scenes</a></span></dt><dt><span class="sect2"><a href="#signalprocedure">Emitting a Signal - Behind the Scenes</a></span></dt><dt><span class="sect2"><a href="#introspection">Introspection</a></span></dt></dl></dd><dt><span class="sect1"><a href="#glib-client">GLib API: Using Remote Objects</a></span></dt><dd><dl><dt><span class="sect2"><a href="#glib-typemappings">D-Bus - GLib type mappings</a></span></dt><dt><span class="sect2"><a href="#sample-program-1">A sample program</a></span></dt><dt><span class="sect2"><a href="#glib-program-setup">Program initalization</a></span></dt><dt><span class="sect2"><a href="#glib-method-invocation">Understanding method invocation</a></span></dt><dt><span class="sect2"><a href="#glib-signal-connection">Connecting to object signals</a></span></dt><dt><span class="sect2"><a href="#glib-error-handling">Error handling and remote exceptions</a></span></dt><dt><span class="sect2"><a href="#glib-more-examples">More examples of method invocation</a></span></dt><dt><span class="sect2"><a href="#glib-generated-bindings">Generated Bindings</a></span></dt></dl></dd><dt><span class="sect1"><a href="#glib-server">GLib API: Implementing Objects</a></span></dt><dd><dl><dt><span class="sect2"><a href="#glib-annotations">Server-side Annotations</a></span></dt></dl></dd><dt><span class="sect1"><a href="#python-client">Python API</a></span></dt><dt><span class="sect1"><a href="#qt-client">Qt API: Using Remote Objects</a></span></dt><dt><span class="sect1"><a href="#qt-server">Qt API: Implementing Objects</a></span></dt></dl></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="meta"></a>Tutorial Work In Progress</h2></div></div></div><p>

1

<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>D-Bus Tutorial</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 Tutorial"><div class="titlepage"><div><div><h2 class="title"><a name="index"></a>D-Bus Tutorial</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><code class="email"><<a class="email" href="mailto:hp@pobox.com">hp@pobox.com</a>></code></p></div></div></div><div class="author"><h3 class="author"><span class="firstname">David</span> <span class="surname">Wheeler</span></h3></div><div class="author"><h3 class="author"><span class="firstname">John</span> <span class="surname">Palmieri</span></h3><div class="affiliation"><span class="orgname">Red Hat, Inc.<br></span><div class="address"><p><code class="email"><<a class="email" href="mailto:johnp@redhat.com">johnp@redhat.com</a>></code></p></div></div></div><div class="author"><h3 class="author"><span class="firstname">Colin</span> <span class="surname">Walters</span></h3><div class="affiliation"><span class="orgname">Red Hat, Inc.<br></span><div class="address"><p><code class="email"><<a class="email" href="mailto:walters@redhat.com">walters@redhat.com</a>></code></p></div></div></div></div></div><div><p class="releaseinfo">Version 0.5.0</p></div></div><hr></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="sect1"><a href="#meta">Tutorial Work In Progress</a></span></dt><dt><span class="sect1"><a href="#whatis">What is D-Bus?</a></span></dt><dd><dl><dt><span class="sect2"><a href="#uses">D-Bus applications</a></span></dt></dl></dd><dt><span class="sect1"><a href="#concepts">Concepts</a></span></dt><dd><dl><dt><span class="sect2"><a href="#objects">Native Objects and Object Paths</a></span></dt><dt><span class="sect2"><a href="#members">Methods and Signals</a></span></dt><dt><span class="sect2"><a href="#interfaces">Interfaces</a></span></dt><dt><span class="sect2"><a href="#proxies">Proxies</a></span></dt><dt><span class="sect2"><a href="#bus-names">Bus Names</a></span></dt><dt><span class="sect2"><a href="#addresses">Addresses</a></span></dt><dt><span class="sect2"><a href="#bigpicture">Big Conceptual Picture</a></span></dt><dt><span class="sect2"><a href="#messages">Messages - Behind the Scenes</a></span></dt><dt><span class="sect2"><a href="#callprocedure">Calling a Method - Behind the Scenes</a></span></dt><dt><span class="sect2"><a href="#signalprocedure">Emitting a Signal - Behind the Scenes</a></span></dt><dt><span class="sect2"><a href="#introspection">Introspection</a></span></dt></dl></dd><dt><span class="sect1"><a href="#glib-client">GLib API: Using Remote Objects</a></span></dt><dd><dl><dt><span class="sect2"><a href="#glib-typemappings">D-Bus - GLib type mappings</a></span></dt><dt><span class="sect2"><a href="#sample-program-1">A sample program</a></span></dt><dt><span class="sect2"><a href="#glib-program-setup">Program initalization</a></span></dt><dt><span class="sect2"><a href="#glib-method-invocation">Understanding method invocation</a></span></dt><dt><span class="sect2"><a href="#glib-signal-connection">Connecting to object signals</a></span></dt><dt><span class="sect2"><a href="#glib-error-handling">Error handling and remote exceptions</a></span></dt><dt><span class="sect2"><a href="#glib-more-examples">More examples of method invocation</a></span></dt><dt><span class="sect2"><a href="#glib-generated-bindings">Generated Bindings</a></span></dt></dl></dd><dt><span class="sect1"><a href="#glib-server">GLib API: Implementing Objects</a></span></dt><dd><dl><dt><span class="sect2"><a href="#glib-annotations">Server-side Annotations</a></span></dt></dl></dd><dt><span class="sect1"><a href="#python-client">Python API</a></span></dt><dt><span class="sect1"><a href="#qt-client">Qt API: Using Remote Objects</a></span></dt><dt><span class="sect1"><a href="#qt-server">Qt API: Implementing Objects</a></span></dt></dl></div><div class="sect1" title="Tutorial Work In Progress"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="meta"></a>Tutorial Work In Progress</h2></div></div></div><p>

2

This tutorial is not complete; it probably contains some useful information, but

3

also has plenty of gaps. Right now, you'll also need to refer to the D-Bus specification,

4

Doxygen reference documentation, and look at some examples of how other apps use D-Bus.

6

Enhancing the tutorial is definitely encouraged - send your patches or suggestions to the

7

mailing list. If you create a D-Bus binding, please add a section to the tutorial for your

8

binding, if only a short section with a couple of examples.

9

</p></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="whatis"></a>What is D-Bus?</h2></div></div></div><p>

9

</p></div><div class="sect1" title="What is D-Bus?"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="whatis"></a>What is D-Bus?</h2></div></div></div><p>

10

D-Bus is a system for <em class="firstterm">interprocess communication</em>

11

(IPC). Architecturally, it has several layers:

12

13

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

13

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

14

A library, <em class="firstterm">libdbus</em>, that allows two

15

applications to connect to each other and exchange messages.

16

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

16

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

17

A <em class="firstterm">message bus daemon</em> executable, built on

18

libdbus, that multiple applications can connect to. The daemon can

19

route messages from one application to zero or more other

20

applications.

21

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

21

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

22

<em class="firstterm">Wrapper libraries</em> or <em class="firstterm">bindings</em>

23

based on particular application frameworks. For example, libdbus-glib and

24

libdbus-qt. There are also bindings to languages such as

51

</p><p>

52

The systemwide and per-user daemons are separate. Normal within-session

53

IPC does not involve the systemwide message bus process and vice versa.

54

</p><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="uses"></a>D-Bus applications</h3></div></div></div><p>

54

</p><div class="sect2" title="D-Bus applications"><div class="titlepage"><div><div><h3 class="title"><a name="uses"></a>D-Bus applications</h3></div></div></div><p>

55

There are many, many technologies in the world that have "Inter-process

56

communication" or "networking" in their stated purpose: <a class="ulink" href="http://www.omg.org" target="_top">CORBA</a>, <a class="ulink" href="http://www.opengroup.org/dce/" target="_top">DCE</a>, <a class="ulink" href="http://www.microsoft.com/com/" target="_top">DCOM</a>, <a class="ulink" href="http://developer.kde.org/documentation/library/kdeqt/dcop.html" target="_top">DCOP</a>, <a class="ulink" href="http://www.xmlrpc.com" target="_top">XML-RPC</a>, <a class="ulink" href="http://www.w3.org/TR/SOAP/" target="_top">SOAP</a>, <a class="ulink" href="http://www.mbus.org/" target="_top">MBUS</a>, <a class="ulink" href="http://www.zeroc.com/ice.html" target="_top">Internet Communications Engine (ICE)</a>,

57

and probably hundreds more.

58

Each of these is tailored for particular kinds of application.

59

D-Bus is designed for two specific cases:

60

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

60

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

61

Communication between desktop applications in the same desktop

62

session; to allow integration of the desktop session as a whole,

63

and address issues of process lifecycle (when do desktop components

64

start and stop running).

65

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

65

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

66

Communication between the desktop session and the operating system,

67

where the operating system would typically include the kernel

68

and any system daemons or processes.

102

D-Bus may happen to be useful for purposes other than the one it was

103

designed for. Its general properties that distinguish it from

104

other forms of IPC are:

105

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

105

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

106

Binary protocol designed to be used asynchronously

107

(similar in spirit to the X Window System protocol).

108

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

108

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

109

Stateful, reliable connections held open over time.

110

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

110

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

111

The message bus is a daemon, not a "swarm" or

112

distributed architecture.

113

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

113

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

114

Many implementation and deployment issues are specified rather

115

than left ambiguous/configurable/pluggable.

116

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

116

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

117

Semantics are similar to the existing DCOP system, allowing

118

KDE to adopt it more easily.

119

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

119

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

120

Security features to support the systemwide mode of the

121

message bus.

122

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

123

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

123

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

124

Some basic concepts apply no matter what application framework you're

125

using to write a D-Bus application. The exact code you write will be

126

different for GLib vs. Qt vs. Python applications, however.

127

</p><p>

128

Here is a diagram (<a class="ulink" href="diagram.png" target="_top">png</a> <a class="ulink" href="diagram.svg" target="_top">svg</a>) that may help you visualize the concepts

129

that follow.

130

</p><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="objects"></a>Native Objects and Object Paths</h3></div></div></div><p>

130

</p><div class="sect2" title="Native Objects and Object Paths"><div class="titlepage"><div><div><h3 class="title"><a name="objects"></a>Native Objects and Object Paths</h3></div></div></div><p>

131

Your programming framework probably defines what an "object" is like;

132

usually with a base class. For example: java.lang.Object, GObject, QObject,

133

python's base Object, or whatever. Let's call this a <em class="firstterm">native object</em>.

149

of a domain name you own (e.g. <code class="literal">/org/kde</code>). This

150

keeps different code modules in the same process from stepping

151

on one another's toes.

152

</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="members"></a>Methods and Signals</h3></div></div></div><p>

152

</p></div><div class="sect2" title="Methods and Signals"><div class="titlepage"><div><div><h3 class="title"><a name="members"></a>Methods and Signals</h3></div></div></div><p>

153

Each object has <em class="firstterm">members</em>; the two kinds of member

154

are <em class="firstterm">methods</em> and

155

<em class="firstterm">signals</em>. Methods are operations that can be

160

</p><p>

161

Both methods and signals are referred to by name, such as

162

"Frobate" or "OnClicked".

163

</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="interfaces"></a>Interfaces</h3></div></div></div><p>

163

</p></div><div class="sect2" title="Interfaces"><div class="titlepage"><div><div><h3 class="title"><a name="interfaces"></a>Interfaces</h3></div></div></div><p>

164

Each object supports one or more <em class="firstterm">interfaces</em>.

165

Think of an interface as a named group of methods and signals,

166

just as it is in GLib or Qt or Java. Interfaces define the

171

Most bindings will map these interface names directly to

172

the appropriate programming language construct, for example

173

to Java interfaces or C++ pure virtual classes.

174

</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="proxies"></a>Proxies</h3></div></div></div><p>

174

</p></div><div class="sect2" title="Proxies"><div class="titlepage"><div><div><h3 class="title"><a name="proxies"></a>Proxies</h3></div></div></div><p>

175

A <em class="firstterm">proxy object</em> is a convenient native object created to

176

represent a remote object in another process. The low-level DBus API involves manually creating

177

a method call message, sending it, then manually receiving and processing

198

Proxy proxy = new Proxy(getBusConnection(), "/remote/object/path");

199

Object returnValue = proxy.MethodName(arg1, arg2);

200

</pre><p>

201

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

201

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

202

When each application connects to the bus daemon, the daemon immediately

203

assigns it a name, called the <em class="firstterm">unique connection name</em>.

204

A unique name begins with a ':' (colon) character. These names are never

242

<code class="literal">com.mycompany.TextEditor</code> application is running for

243

example, have the text editor application exit if the bus name already

244

has an owner.

245

</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="addresses"></a>Addresses</h3></div></div></div><p>

245

</p></div><div class="sect2" title="Addresses"><div class="titlepage"><div><div><h3 class="title"><a name="addresses"></a>Addresses</h3></div></div></div><p>

246

Applications using D-Bus are either servers or clients. A server

247

listens for incoming connections; a client connects to a server. Once

248

the connection is established, it is a symmetric flow of messages; the

272

define which application will be the server and which will be

273

the client, and specify a mechanism for them to agree on

274

the server's address. This is an unusual case.

275

</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="bigpicture"></a>Big Conceptual Picture</h3></div></div></div><p>

275

</p></div><div class="sect2" title="Big Conceptual Picture"><div class="titlepage"><div><div><h3 class="title"><a name="bigpicture"></a>Big Conceptual Picture</h3></div></div></div><p>

276

Pulling all these concepts together, to specify a particular

277

method call on a particular object instance, a number of

278

nested components have to be named:

290

on the same object instance. D-Bus will thus let you

291

omit the interface, but if your method name is ambiguous

292

it is undefined which method will be invoked.

293

</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="messages"></a>Messages - Behind the Scenes</h3></div></div></div><p>

293

</p></div><div class="sect2" title="Messages - Behind the Scenes"><div class="titlepage"><div><div><h3 class="title"><a name="messages"></a>Messages - Behind the Scenes</h3></div></div></div><p>

294

D-Bus works by sending messages between processes. If you're using

295

a sufficiently high-level binding, you may never work with messages directly.

296

</p><p>

297

There are 4 message types:

298

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

298

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

299

Method call messages ask to invoke a method

300

on an object.

301

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

301

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

302

Method return messages return the results

303

of invoking a method.

304

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

304

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

305

Error messages return an exception caused by

306

invoking a method.

307

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

307

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

308

Signal messages are notifications that a given signal

309

has been emitted (that an event has occurred).

310

You could also think of these as "event" messages.

321

and so forth. One of the header fields is a <em class="firstterm">type signature</em> describing the

322

values found in the body. For example, the letter "i" means "32-bit integer" so the signature

323

"ii" means the payload has two 32-bit integers.

324

</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="callprocedure"></a>Calling a Method - Behind the Scenes</h3></div></div></div><p>

324

</p></div><div class="sect2" title="Calling a Method - Behind the Scenes"><div class="titlepage"><div><div><h3 class="title"><a name="callprocedure"></a>Calling a Method - Behind the Scenes</h3></div></div></div><p>

325

A method call in DBus consists of two messages; a method call message sent from process A to process B,

326

and a matching method reply message sent from process B to process A. Both the call and the reply messages

327

are routed through the bus daemon. The caller includes a different serial number in each call message, and the

331

The reply message may indicate an error, or may contain data returned by the method.

332

</p><p>

333

A method invocation in DBus happens as follows:

334

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

334

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

335

The language binding may provide a proxy, such that invoking a method on

336

an in-process object invokes a method on a remote object in another process. If so, the

337

application calls a method on the proxy, and the proxy

338

constructs a method call message to send to the remote process.

339

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

339

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

340

For more low-level APIs, the application may construct a method call message itself, without

341

using a proxy.

342

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

342

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

343

In either case, the method call message contains: a bus name belonging to the remote process; the name of the method;

344

the arguments to the method; an object path inside the remote process; and optionally the name of the

345

interface that specifies the method.

346

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

346

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

347

The method call message is sent to the bus daemon.

348

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

348

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

349

The bus daemon looks at the destination bus name. If a process owns that name,

350

the bus daemon forwards the method call to that process. Otherwise, the bus daemon

351

creates an error message and sends it back as the reply to the method call message.

352

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

352

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

353

The receiving process unpacks the method call message. In a simple low-level API situation, it

354

may immediately run the method and send a method reply message to the bus daemon.

355

When using a high-level binding API, the binding might examine the object path, interface,

356

and method name, and convert the method call message into an invocation of a method on

357

a native object (GObject, java.lang.Object, QObject, etc.), then convert the return

358

value from the native method into a method reply message.

359

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

359

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

360

The bus daemon receives the method reply message and sends it to the process that

361

made the method call.

362

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

362

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

363

The process that made the method call looks at the method reply and makes use of any

364

return values included in the reply. The reply may also indicate that an error occurred.

365

When using a binding, the method reply message may be converted into the return value of

371

in order, however; for example, it may process each method call in a separate thread, and return reply messages

372

in an undefined order depending on when the threads complete. Method calls have a unique serial

373

number used by the method caller to match reply messages to call messages.

374

</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="signalprocedure"></a>Emitting a Signal - Behind the Scenes</h3></div></div></div><p>

374

</p></div><div class="sect2" title="Emitting a Signal - Behind the Scenes"><div class="titlepage"><div><div><h3 class="title"><a name="signalprocedure"></a>Emitting a Signal - Behind the Scenes</h3></div></div></div><p>

375

A signal in DBus consists of a single message, sent by one process to any number of other processes.

376

That is, a signal is a unidirectional broadcast. The signal may contain arguments (a data payload), but

377

because it is a broadcast, it never has a "return value." Contrast this with a method call

383

signal.

384

</p><p>

385

A signal in DBus happens as follows:

386

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

386

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

387

A signal message is created and sent to the bus daemon. When using the low-level API this may be

388

done manually, with certain bindings it may be done for you by the binding when a native object

389

emits a native signal or event.

390

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

390

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

391

The signal message contains the name of the interface that specifies the signal;

392

the name of the signal; the bus name of the process sending the signal; and

393

any arguments

394

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

394

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

395

Any process on the message bus can register "match rules" indicating which signals it

396

is interested in. The bus has a list of registered match rules.

397

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

397

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

398

The bus daemon examines the signal and determines which processes are interested in it.

399

It sends the signal message to these processes.

400

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

400

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

401

Each process receiving the signal decides what to do with it; if using a binding,

402

the binding may choose to emit a native signal on a proxy object. If using the

403

low-level API, the process may just look at the signal sender and name and decide

404

what to do based on that.

405

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

406

</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="introspection"></a>Introspection</h3></div></div></div><p>

406

</p></div><div class="sect2" title="Introspection"><div class="titlepage"><div><div><h3 class="title"><a name="introspection"></a>Introspection</h3></div></div></div><p>

407

D-Bus objects may support the interface <code class="literal">org.freedesktop.DBus.Introspectable</code>.

408

This interface has one method <code class="literal">Introspect</code> which takes no arguments and returns

409

an XML string. The XML string describes the interfaces, methods, and signals of the object.

410

See the D-Bus specification for more details on this introspection format.

411

</p></div></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="glib-client"></a>GLib API: Using Remote Objects</h2></div></div></div><p>

411

</p></div></div><div class="sect1" title="GLib API: Using Remote Objects"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="glib-client"></a>GLib API: Using Remote Objects</h2></div></div></div><p>

412

The GLib binding is defined in the header file

413

<code class="literal"><dbus/dbus-glib.h></code>.

414

</p><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="glib-typemappings"></a>D-Bus - GLib type mappings</h3></div></div></div><p>

414

</p><div class="sect2" title="D-Bus - GLib type mappings"><div class="titlepage"><div><div><h3 class="title"><a name="glib-typemappings"></a>D-Bus - GLib type mappings</h3></div></div></div><p>

415

The heart of the GLib bindings for D-Bus is the mapping it

416

provides between D-Bus "type signatures" and GLib types

417

(<code class="literal">GType</code>). The D-Bus type system is composed of

418

a number of "basic" types, along with several "container" types.

419

</p><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="glib-basic-typemappings"></a>Basic type mappings</h4></div></div></div><p>

419

</p><div class="sect3" title="Basic type mappings"><div class="titlepage"><div><div><h4 class="title"><a name="glib-basic-typemappings"></a>Basic type mappings</h4></div></div></div><p>

420

Below is a list of the basic types, along with their associated

421

mapping to a <code class="literal">GType</code>.

422

</p><div class="informaltable"><table border="1"><colgroup><col><col><col><col></colgroup><thead><tr><th>D-Bus basic type</th><th>GType</th><th>Free function</th><th>Notes</th></tr></thead><tbody><tr><td><code class="literal">BYTE</code></td><td><code class="literal">G_TYPE_UCHAR</code></td><td>�</td><td>�</td></tr><tr><td><code class="literal">BOOLEAN</code></td><td><code class="literal">G_TYPE_BOOLEAN</code></td><td>�</td><td>�</td></tr><tr><td><code class="literal">INT16</code></td><td><code class="literal">G_TYPE_INT</code></td><td>�</td><td>Will be changed to a <code class="literal">G_TYPE_INT16</code> once GLib has it</td></tr><tr><td><code class="literal">UINT16</code></td><td><code class="literal">G_TYPE_UINT</code></td><td>�</td><td>Will be changed to a <code class="literal">G_TYPE_UINT16</code> once GLib has it</td></tr><tr><td><code class="literal">INT32</code></td><td><code class="literal">G_TYPE_INT</code></td><td>�</td><td>Will be changed to a <code class="literal">G_TYPE_INT32</code> once GLib has it</td></tr><tr><td><code class="literal">UINT32</code></td><td><code class="literal">G_TYPE_UINT</code></td><td>�</td><td>Will be changed to a <code class="literal">G_TYPE_UINT32</code> once GLib has it</td></tr><tr><td><code class="literal">INT64</code></td><td><code class="literal">G_TYPE_GINT64</code></td><td>�</td><td>�</td></tr><tr><td><code class="literal">UINT64</code></td><td><code class="literal">G_TYPE_GUINT64</code></td><td>�</td><td>�</td></tr><tr><td><code class="literal">DOUBLE</code></td><td><code class="literal">G_TYPE_DOUBLE</code></td><td>�</td><td>�</td></tr><tr><td><code class="literal">STRING</code></td><td><code class="literal">G_TYPE_STRING</code></td><td><code class="literal">g_free</code></td><td>�</td></tr><tr><td><code class="literal">OBJECT_PATH</code></td><td><code class="literal">DBUS_TYPE_G_PROXY</code></td><td><code class="literal">g_object_unref</code></td><td>The returned proxy does not have an interface set; use <code class="literal">dbus_g_proxy_set_interface</code> to invoke methods</td></tr></tbody></table></div><p>

423

As you can see, the basic mapping is fairly straightforward.

424

</p></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="glib-container-typemappings"></a>Container type mappings</h4></div></div></div><p>

424

</p></div><div class="sect3" title="Container type mappings"><div class="titlepage"><div><div><h4 class="title"><a name="glib-container-typemappings"></a>Container type mappings</h4></div></div></div><p>

425

The D-Bus type system also has a number of "container"

426

types, such as <code class="literal">DBUS_TYPE_ARRAY</code> and

427

<code class="literal">DBUS_TYPE_STRUCT</code>. The D-Bus type system

466

At present, only strings are supported. Work is in progress to

467

include more types.

468

</p><div class="informaltable"><table border="1"><colgroup><col><col><col><col><col><col></colgroup><thead><tr><th>D-Bus type signature</th><th>Description</th><th>GType</th><th>C typedef</th><th>Free function</th><th>Notes</th></tr></thead><tbody><tr><td><code class="literal">a{ss}</code></td><td>Dictionary mapping strings to strings</td><td><code class="literal">DBUS_TYPE_G_STRING_STRING_HASHTABLE</code></td><td><code class="literal">GHashTable *</code></td><td>g_hash_table_destroy</td><td>�</td></tr></tbody></table></div><p>

469

</p></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="glib-generic-typemappings"></a>Arbitrarily recursive type mappings</h4></div></div></div><p>

469

</p></div><div class="sect3" title="Arbitrarily recursive type mappings"><div class="titlepage"><div><div><h4 class="title"><a name="glib-generic-typemappings"></a>Arbitrarily recursive type mappings</h4></div></div></div><p>

470

Finally, it is possible users will want to write or invoke D-Bus

471

methods which have arbitrarily complex type signatures not

472

directly supported by these bindings. For this case, we have a

476

<code class="literal">DBUS_TYPE_G_VALUE</code>.

477

</p><p>

478

TODO insert usage of <code class="literal">DBUS_TYPE_G_VALUE</code> here.

479

</p></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="sample-program-1"></a>A sample program</h3></div></div></div><p>Here is a D-Bus program using the GLib bindings.

479

</p></div></div><div class="sect2" title="A sample program"><div class="titlepage"><div><div><h3 class="title"><a name="sample-program-1"></a>A sample program</h3></div></div></div><p>Here is a D-Bus program using the GLib bindings.

480

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

481

int

482

main (int argc, char **argv)

538

return 0;

539

}

540

</pre><p>

541

</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="glib-program-setup"></a>Program initalization</h3></div></div></div><p>

541

</p></div><div class="sect2" title="Program initalization"><div class="titlepage"><div><div><h3 class="title"><a name="glib-program-setup"></a>Program initalization</h3></div></div></div><p>

542

A connection to the bus is acquired using

543

<code class="literal">dbus_g_bus_get</code>. Next, a proxy

544

is created for the object "/org/freedesktop/DBus" with

545

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

546

on the service <code class="literal">org.freedesktop.DBus</code>.

547

This is a proxy for the message bus itself.

548

</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="glib-method-invocation"></a>Understanding method invocation</h3></div></div></div><p>

548

</p></div><div class="sect2" title="Understanding method invocation"><div class="titlepage"><div><div><h3 class="title"><a name="glib-method-invocation"></a>Understanding method invocation</h3></div></div></div><p>

549

You have a number of choices for method invocation. First, as

550

used above, <code class="literal">dbus_g_proxy_call</code> sends a

551

method call to the remote object, and blocks until a reply is

559

<code class="literal">DBusGPendingCall</code> object; you may then set a

560

notification function using

561

<code class="literal">dbus_g_pending_call_set_notify</code>.

562

</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="glib-signal-connection"></a>Connecting to object signals</h3></div></div></div><p>

562

</p></div><div class="sect2" title="Connecting to object signals"><div class="titlepage"><div><div><h3 class="title"><a name="glib-signal-connection"></a>Connecting to object signals</h3></div></div></div><p>

563

You may connect to signals using

564

<code class="literal">dbus_g_proxy_add_signal</code> and

565

<code class="literal">dbus_g_proxy_connect_signal</code>. You must

572

case, you must generate a marshaller yourself by using

573

<span class="application">glib-genmarshal</span>, and then register

574

it using <code class="literal">dbus_g_object_register_marshaller</code>.

575

</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="glib-error-handling"></a>Error handling and remote exceptions</h3></div></div></div><p>

575

</p></div><div class="sect2" title="Error handling and remote exceptions"><div class="titlepage"><div><div><h3 class="title"><a name="glib-error-handling"></a>Error handling and remote exceptions</h3></div></div></div><p>

576

All of the GLib binding methods such as

577

<code class="literal">dbus_g_proxy_end_call</code> return a

578

<code class="literal">GError</code>. This <code class="literal">GError</code> can

579

represent two different things:

580

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

580

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

581

An internal D-Bus error, such as an out-of-memory

582

condition, an I/O error, or a network timeout. Errors

583

generated by the D-Bus library itself have the domain

585

such as <code class="literal">DBUS_GERROR_NO_MEMORY</code>. It will

586

not be typical for applications to handle these errors

587

specifically.

588

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

588

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

589

A remote D-Bus exception, thrown by the peer, bus, or

590

service. D-Bus remote exceptions have both a textual

591

"name" and a "message". The GLib bindings store this

603

exception detailed message is accessible via the regular

604

GError <code class="literal">message</code> member.

605

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

606

</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="glib-more-examples"></a>More examples of method invocation</h3></div></div></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="glib-sending-stuff"></a>Sending an integer and string, receiving an array of bytes</h4></div></div></div><p>

606

</p></div><div class="sect2" title="More examples of method invocation"><div class="titlepage"><div><div><h3 class="title"><a name="glib-more-examples"></a>More examples of method invocation</h3></div></div></div><div class="sect3" title="Sending an integer and string, receiving an array of bytes"><div class="titlepage"><div><div><h4 class="title"><a name="glib-sending-stuff"></a>Sending an integer and string, receiving an array of bytes</h4></div></div></div><p>

607

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

608

GArray *arr;

609

618

g_assert (arr != NULL);

619

printf ("got back %u values", arr->len);

620

</pre><p>

621

</p></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="glib-sending-hash"></a>Sending a GHashTable</h4></div></div></div><p>

621

</p></div><div class="sect3" title="Sending a GHashTable"><div class="titlepage"><div><div><h4 class="title"><a name="glib-sending-hash"></a>Sending a GHashTable</h4></div></div></div><p>

622

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

623

GHashTable *hash = g_hash_table_new (g_str_hash, g_str_equal);

624

guint32 ret;

636

g_assert (ret == 2);

637

g_hash_table_destroy (hash);

638

</pre><p>

639

</p></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="glib-receiving-bool-int"></a>Receiving a boolean and a string</h4></div></div></div><p>

639

</p></div><div class="sect3" title="Receiving a boolean and a string"><div class="titlepage"><div><div><h4 class="title"><a name="glib-receiving-bool-int"></a>Receiving a boolean and a string</h4></div></div></div><p>

640

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

641

gboolean boolret;

642

char *strret;

653

printf ("%s %s", boolret ? "TRUE" : "FALSE", strret);

654

g_free (strret);

655

</pre><p>

656

</p></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="glib-sending-str-arrays"></a>Sending two arrays of strings</h4></div></div></div><p>

656

</p></div><div class="sect3" title="Sending two arrays of strings"><div class="titlepage"><div><div><h4 class="title"><a name="glib-sending-str-arrays"></a>Sending two arrays of strings</h4></div></div></div><p>

657

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

658

/* NULL terminate */

659

char *strs_static[] = {"foo", "bar", "baz", NULL};

679

}

680

g_strfreev (strs_dynamic);

681

</pre><p>

682

</p></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="glib-getting-str-array"></a>Sending a boolean, receiving an array of strings</h4></div></div></div><p>

682

</p></div><div class="sect3" title="Sending a boolean, receiving an array of strings"><div class="titlepage"><div><div><h4 class="title"><a name="glib-getting-str-array"></a>Sending a boolean, receiving an array of strings</h4></div></div></div><p>

683

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

684

char **strs;

685

char **strs_p;

699

printf ("got string: \"%s\"", *strs_p);

700

g_strfreev (strs);

701

</pre><p>

702

</p></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="glib-sending-variant"></a>Sending a variant</h4></div></div></div><p>

702

</p></div><div class="sect3" title="Sending a variant"><div class="titlepage"><div><div><h4 class="title"><a name="glib-sending-variant"></a>Sending a variant</h4></div></div></div><p>

703

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

704

GValue val = {0, };

705

716

g_assert (ret == 2);

717

g_value_unset (&val);

718

</pre><p>

719

</p></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="glib-receiving-variant"></a>Receiving a variant</h4></div></div></div><p>

719

</p></div><div class="sect3" title="Receiving a variant"><div class="titlepage"><div><div><h4 class="title"><a name="glib-receiving-variant"></a>Receiving a variant</h4></div></div></div><p>

720

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

721

GValue val = {0, };

722

734

...

735

g_value_unset (&val);

736

</pre><p>

737

</p></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="glib-generated-bindings"></a>Generated Bindings</h3></div></div></div><p>

737

</p></div></div><div class="sect2" title="Generated Bindings"><div class="titlepage"><div><div><h3 class="title"><a name="glib-generated-bindings"></a>Generated Bindings</h3></div></div></div><p>

738

By using the Introspection XML files, convenient client-side bindings

739

can be automatically created to ease the use of a remote DBus object.

740

</p><p>

802

rapid method calls where there are no "out" arguments, and not knowing

803

if the method succeeded is an acceptable compromise to half the traffic

804

on the bus.

805

</p></div></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="glib-server"></a>GLib API: Implementing Objects</h2></div></div></div><p>

805

</p></div></div><div class="sect1" title="GLib API: Implementing Objects"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="glib-server"></a>GLib API: Implementing Objects</h2></div></div></div><p>

806

At the moment, to expose a GObject via D-Bus, you must

807

write XML by hand which describes the methods exported

808

by the object. In the future, this manual step will

855

<code class="literal">my_object_many_args</code> in the same file as the info

856

header is included. At the moment, it is required that this function

857

conform to the following rules:

858

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

858

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

859

The function must return a value of type <code class="literal">gboolean</code>;

860

<code class="literal">TRUE</code> on success, and <code class="literal">FALSE</code>

861

otherwise.

862

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

862

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

863

The first parameter is a pointer to an instance of the object.

864

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

864

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

865

Following the object instance pointer are the method

866

input values.

867

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

867

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

868

Following the input values are pointers to return values.

869

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

869

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

870

The final parameter must be a <code class="literal">GError **</code>.

871

If the function returns <code class="literal">FALSE</code> for an

872

error, the error parameter must be initalized with

879

"/com/foo/MyObject",

880

obj);

881

</pre><p>

882

</p><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="glib-annotations"></a>Server-side Annotations</h3></div></div></div><p>

882

</p><div class="sect2" title="Server-side Annotations"><div class="titlepage"><div><div><h3 class="title"><a name="glib-annotations"></a>Server-side Annotations</h3></div></div></div><p>

883

There are several annotations that are used when generating the

884

server-side bindings. The most common annotation is

885

<code class="literal">org.freedesktop.DBus.GLib.CSymbol</code> but there are other

898

When a method is asynchronous, the function prototype is

899

different. It is required that the function conform to the

900

following rules:

901

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

901

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

902

The function must return a value of type <code class="literal">gboolean</code>;

903

<code class="literal">TRUE</code> on success, and <code class="literal">FALSE</code>

904

otherwise. TODO: the return value is currently ignored.

905

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

905

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

906

The first parameter is a pointer to an instance of the object.

907

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

907

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

908

Following the object instance pointer are the method

909

input values.

910

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

910

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

911

The final parameter must be a

912

<code class="literal">DBusGMethodInvocation *</code>. This is used

913

when sending the response message back to the client, by

977

my_object_increment_retval_error (MyObject *obj, gint32 x, GError **error)

978

</pre><p>

979

</p></dd></dl></div><p>

980

</p></div></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="python-client"></a>Python API</h2></div></div></div><p>

980

</p></div></div><div class="sect1" title="Python API"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="python-client"></a>Python API</h2></div></div></div><p>

981

The Python API, dbus-python, is now documented separately in

982

<a class="ulink" href="http://dbus.freedesktop.org/doc/dbus-python/doc/tutorial.html" target="_top">the dbus-python tutorial</a> (also available in doc/tutorial.txt,

983

and doc/tutorial.html if built with python-docutils, in the dbus-python

984

source distribution).

985

</p></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="qt-client"></a>Qt API: Using Remote Objects</h2></div></div></div><p>

985

</p></div><div class="sect1" title="Qt API: Using Remote Objects"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="qt-client"></a>Qt API: Using Remote Objects</h2></div></div></div><p>

986

987

The Qt bindings are not yet documented.

988

989

</p></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="qt-server"></a>Qt API: Implementing Objects</h2></div></div></div><p>

989

</p></div><div class="sect1" title="Qt API: Implementing Objects"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="qt-server"></a>Qt API: Implementing Objects</h2></div></div></div><p>

990

The Qt bindings are not yet documented.

991

</p></div></div></body></html>