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.76.1"></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. 5 </p><p> 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" 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 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 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 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 25 Python. These wrapper libraries are the API most people should use, 26 as they simplify the details of D-Bus programming. libdbus is 27 intended to be a low-level backend for the higher level bindings. 28 Much of the libdbus API is only useful for binding implementation. 29 </p></li></ul></div><p> 30 </p><p> 31 libdbus only supports one-to-one connections, just like a raw network 32 socket. However, rather than sending byte streams over the connection, you 33 send <em class="firstterm">messages</em>. Messages have a header identifying 34 the kind of message, and a body containing a data payload. libdbus also 35 abstracts the exact transport used (sockets vs. whatever else), and 36 handles details such as authentication. 37 </p><p> 38 The message bus daemon forms the hub of a wheel. Each spoke of the wheel 39 is a one-to-one connection to an application using libdbus. An 40 application sends a message to the bus daemon over its spoke, and the bus 41 daemon forwards the message to other connected applications as 42 appropriate. Think of the daemon as a router. 43 </p><p> 44 The bus daemon has multiple instances on a typical computer. The 45 first instance is a machine-global singleton, that is, a system daemon 46 similar to sendmail or Apache. This instance has heavy security 47 restrictions on what messages it will accept, and is used for systemwide 48 communication. The other instances are created one per user login session. 49 These instances allow applications in the user's session to communicate 50 with one another. 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" 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 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 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. 69 </p></li></ul></div><p> 70 </p><p> 71 For the within-desktop-session use case, the GNOME and KDE desktops 72 have significant previous experience with different IPC solutions 73 such as CORBA and DCOP. D-Bus is built on that experience and 74 carefully tailored to meet the needs of these desktop projects 75 in particular. D-Bus may or may not be appropriate for other 76 applications; the FAQ has some comparisons to other IPC systems. 77 </p><p> 78 The problem solved by the systemwide or communication-with-the-OS case 79 is explained well by the following text from the Linux Hotplug project: 80 </p><div class="blockquote"><blockquote class="blockquote"><p> 81 A gap in current Linux support is that policies with any sort of 82 dynamic "interact with user" component aren't currently 83 supported. For example, that's often needed the first time a network 84 adapter or printer is connected, and to determine appropriate places 85 to mount disk drives. It would seem that such actions could be 86 supported for any case where a responsible human can be identified: 87 single user workstations, or any system which is remotely 88 administered. 89 </p><p> 90 This is a classic "remote sysadmin" problem, where in this case 91 hotplugging needs to deliver an event from one security domain 92 (operating system kernel, in this case) to another (desktop for 93 logged-in user, or remote sysadmin). Any effective response must go 94 the other way: the remote domain taking some action that lets the 95 kernel expose the desired device capabilities. (The action can often 96 be taken asynchronously, for example letting new hardware be idle 97 until a meeting finishes.) At this writing, Linux doesn't have 98 widely adopted solutions to such problems. However, the new D-Bus 99 work may begin to solve that problem. 100 </p></blockquote></div><p> 101 </p><p> 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 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 class="listitem"><p> 109 Stateful, reliable connections held open over time. 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 class="listitem"><p> 114 Many implementation and deployment issues are specified rather 115 than left ambiguous/configurable/pluggable. 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 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" 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" 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>. 134 </p><p> 135 The low-level D-Bus protocol, and corresponding libdbus API, does not care about native objects. 136 However, it provides a concept called an 137 <em class="firstterm">object path</em>. The idea of an object path is that 138 higher-level bindings can name native object instances, and allow remote applications 139 to refer to them. 140 </p><p> 141 The object path 142 looks like a filesystem path, for example an object could be 143 named <code class="literal">/org/kde/kspread/sheets/3/cells/4/5</code>. 144 Human-readable paths are nice, but you are free to create an 145 object named <code class="literal">/com/mycompany/c5yo817y0c1y1c5b</code> 146 if it makes sense for your application. 147 </p><p> 148 Namespacing object paths is smart, by starting them with the components 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" 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 156 invoked on an object, with optional input (aka arguments or "in 157 parameters") and output (aka return values or "out parameters"). 158 Signals are broadcasts from the object to any interested observers 159 of the object; signals may contain a data payload. 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" 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 167 <span class="emphasis"><em>type</em></span> of an object instance. 168 </p><p> 169 DBus identifies interfaces with a simple namespaced string, 170 something like <code class="literal">org.freedesktop.Introspectable</code>. 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" 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 178 the method reply message. Higher-level bindings provide proxies as an alternative. 179 Proxies look like a normal native object; but when you invoke a method on the proxy 180 object, the binding converts it into a DBus method call message, waits for the reply 181 message, unpacks the return value, and returns it from the native method.. 182 </p><p> 183 In pseudocode, programming without proxies might look like this: 184 </p><pre class="programlisting"> 185 Message message = new Message("/remote/object/path", "MethodName", arg1, arg2); 186 Connection connection = getBusConnection(); 187 connection.send(message); 188 Message reply = connection.waitForReply(message); 189 if (reply.isError()) { 190 191 } else { 192 Object returnValue = reply.getReturnValue(); 193 } 194 </pre><p> 195 </p><p> 196 Programming with proxies might look like this: 197 </p><pre class="programlisting"> 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" 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 205 reused during the lifetime of the bus daemon - that is, you know 206 a given name will always refer to the same application. 207 An example of a unique name might be 208 <code class="literal">:34-907</code>. The numbers after the colon have 209 no meaning other than their uniqueness. 210 </p><p> 211 When a name is mapped 212 to a particular application's connection, that application is said to 213 <em class="firstterm">own</em> that name. 214 </p><p> 215 Applications may ask to own additional <em class="firstterm">well-known 216 names</em>. For example, you could write a specification to 217 define a name called <code class="literal">com.mycompany.TextEditor</code>. 218 Your definition could specify that to own this name, an application 219 should have an object at the path 220 <code class="literal">/com/mycompany/TextFileManager</code> supporting the 221 interface <code class="literal">org.freedesktop.FileHandler</code>. 222 </p><p> 223 Applications could then send messages to this bus name, 224 object, and interface to execute method calls. 225 </p><p> 226 You could think of the unique names as IP addresses, and the 227 well-known names as domain names. So 228 <code class="literal">com.mycompany.TextEditor</code> might map to something like 229 <code class="literal">:34-907</code> just as <code class="literal">mycompany.com</code> maps 230 to something like <code class="literal">192.168.0.5</code>. 231 </p><p> 232 Names have a second important use, other than routing messages. They 233 are used to track lifecycle. When an application exits (or crashes), its 234 connection to the message bus will be closed by the operating system 235 kernel. The message bus then sends out notification messages telling 236 remaining applications that the application's names have lost their 237 owner. By tracking these notifications, your application can reliably 238 monitor the lifetime of other applications. 239 </p><p> 240 Bus names can also be used to coordinate single-instance applications. 241 If you want to be sure only one 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" 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 249 client-server distinction only matters when setting up the 250 connection. 251 </p><p> 252 If you're using the bus daemon, as you probably are, your application 253 will be a client of the bus daemon. That is, the bus daemon listens 254 for connections and your application initiates a connection to the bus 255 daemon. 256 </p><p> 257 A D-Bus <em class="firstterm">address</em> specifies where a server will 258 listen, and where a client will connect. For example, the address 259 <code class="literal">unix:path=/tmp/abcdef</code> specifies that the server will 260 listen on a UNIX domain socket at the path 261 <code class="literal">/tmp/abcdef</code> and the client will connect to that 262 socket. An address can also specify TCP/IP sockets, or any other 263 transport defined in future iterations of the D-Bus specification. 264 </p><p> 265 When using D-Bus with a message bus daemon, 266 libdbus automatically discovers the address of the per-session bus 267 daemon by reading an environment variable. It discovers the 268 systemwide bus daemon by checking a well-known UNIX domain socket path 269 (though you can override this address with an environment variable). 270 </p><p> 271 If you're using D-Bus without a bus daemon, it's up to you to 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" 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: 279 </p><pre class="programlisting"> 280 Address -> [Bus Name] -> Path -> Interface -> Method 281 </pre><p> 282 The bus name is in brackets to indicate that it's optional -- you only 283 provide a name to route the method call to the right application 284 when using the bus daemon. If you have a direct connection to another 285 application, bus names aren't used; there's no bus daemon. 286 </p><p> 287 The interface is also optional, primarily for historical 288 reasons; DCOP does not require specifying the interface, 289 instead simply forbidding duplicate method names 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" 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 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 class="listitem"><p> 302 Method return messages return the results 303 of invoking a method. 304 </p></li><li class="listitem"><p> 305 Error messages return an exception caused by 306 invoking a method. 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. 311 </p></li></ul></div><p> 312 </p><p> 313 A method call maps very simply to messages: you send a method call 314 message, and receive either a method return message or an error message 315 in reply. 316 </p><p> 317 Each message has a <em class="firstterm">header</em>, including <em class="firstterm">fields</em>, 318 and a <em class="firstterm">body</em>, including <em class="firstterm">arguments</em>. You can think 319 of the header as the routing information for the message, and the body as the payload. 320 Header fields might include the sender bus name, destination bus name, method or signal name, 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" 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 328 reply message includes this number to allow the caller to match replies to calls. 329 </p><p> 330 The call message will contain any arguments to the method. 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 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 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 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 class="listitem"><p> 347 The method call message is sent to the bus daemon. 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 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 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 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 366 of a proxy method, or into an exception. 367 </p></li></ul></div><p> 368 </p><p> 369 The bus daemon never reorders messages. That is, if you send two method call messages to the same recipient, 370 they will be received in the order they were sent. The recipient is not required to reply to the calls 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" 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 378 (see <a class="xref" href="#callprocedure" title="Calling a Method - Behind the Scenes">the section called “Calling a Method - Behind the Scenes”</a>) where the method call message has a matching method reply message. 379 </p><p> 380 The emitter (aka sender) of a signal has no knowledge of the signal recipients. Recipients register 381 with the bus daemon to receive signals based on "match rules" - these rules would typically include the sender and 382 the signal name. The bus daemon sends each signal only to recipients who have expressed interest in that 383 signal. 384 </p><p> 385 A signal in DBus happens as follows: 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 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 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 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 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" 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" 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" 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" 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" 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 428 is fully recursive, so one can for example have an array of 429 array of strings (i.e. type signature 430 <code class="literal">aas</code>). 431 </p><p> 432 However, not all of these types are in common use; for 433 example, at the time of this writing the author knows of no 434 one using <code class="literal">DBUS_TYPE_STRUCT</code>, or a 435 <code class="literal">DBUS_TYPE_ARRAY</code> containing any non-basic 436 type. The approach the GLib bindings take is pragmatic; try 437 to map the most common types in the most obvious way, and 438 let using less common and more complex types be less 439 "natural". 440 </p><p> 441 First, D-Bus type signatures which have an "obvious" 442 corresponding built-in GLib type are mapped using that type: 443 </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">as</code></td><td>Array of strings</td><td><code class="literal">G_TYPE_STRV</code></td><td><code class="literal">char **</code></td><td><code class="literal">g_strfreev</code></td><td>�</td></tr><tr><td><code class="literal">v</code></td><td>Generic value container</td><td><code class="literal">G_TYPE_VALUE</code></td><td><code class="literal">GValue *</code></td><td><code class="literal">g_value_unset</code></td><td>The calling conventions for values expect that method callers have allocated return values; see below.</td></tr></tbody></table></div><p> 444 </p><p> 445 The next most common recursive type signatures are arrays of 446 basic values. The most obvious mapping for arrays of basic 447 types is a <code class="literal">GArray</code>. Now, GLib does not 448 provide a builtin <code class="literal">GType</code> for 449 <code class="literal">GArray</code>. However, we actually need more than 450 that - we need a "parameterized" type which includes the 451 contained type. Why we need this we will see below. 452 </p><p> 453 The approach taken is to create these types in the D-Bus GLib 454 bindings; however, there is nothing D-Bus specific about them. 455 In the future, we hope to include such "fundamental" types in GLib 456 itself. 457 </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">ay</code></td><td>Array of bytes</td><td><code class="literal">DBUS_TYPE_G_BYTE_ARRAY</code></td><td><code class="literal">GArray *</code></td><td>g_array_free</td><td>�</td></tr><tr><td><code class="literal">au</code></td><td>Array of uint</td><td><code class="literal">DBUS_TYPE_G_UINT_ARRAY</code></td><td><code class="literal">GArray *</code></td><td>g_array_free</td><td>�</td></tr><tr><td><code class="literal">ai</code></td><td>Array of int</td><td><code class="literal">DBUS_TYPE_G_INT_ARRAY</code></td><td><code class="literal">GArray *</code></td><td>g_array_free</td><td>�</td></tr><tr><td><code class="literal">ax</code></td><td>Array of int64</td><td><code class="literal">DBUS_TYPE_G_INT64_ARRAY</code></td><td><code class="literal">GArray *</code></td><td>g_array_free</td><td>�</td></tr><tr><td><code class="literal">at</code></td><td>Array of uint64</td><td><code class="literal">DBUS_TYPE_G_UINT64_ARRAY</code></td><td><code class="literal">GArray *</code></td><td>g_array_free</td><td>�</td></tr><tr><td><code class="literal">ad</code></td><td>Array of double</td><td><code class="literal">DBUS_TYPE_G_DOUBLE_ARRAY</code></td><td><code class="literal">GArray *</code></td><td>g_array_free</td><td>�</td></tr><tr><td><code class="literal">ab</code></td><td>Array of boolean</td><td><code class="literal">DBUS_TYPE_G_BOOLEAN_ARRAY</code></td><td><code class="literal">GArray *</code></td><td>g_array_free</td><td>�</td></tr></tbody></table></div><p> 458 </p><p> 459 D-Bus also includes a special type DBUS_TYPE_DICT_ENTRY which 460 is only valid in arrays. It's intended to be mapped to a "dictionary" 461 type by bindings. The obvious GLib mapping here is GHashTable. Again, 462 however, there is no builtin <code class="literal">GType</code> for a GHashTable. 463 Moreover, just like for arrays, we need a parameterized type so that 464 the bindings can communiate which types are contained in the hash table. 465 </p><p> 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" 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 473 <code class="literal">DBusGValue</code> which acts as a kind of special 474 variant value which may be iterated over manually. The 475 <code class="literal">GType</code> associated is 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" 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"> 481int 482main (int argc, char **argv) 483{ 484 DBusGConnection *connection; 485 GError *error; 486 DBusGProxy *proxy; 487 char **name_list; 488 char **name_list_ptr; 489 490 g_type_init (); 491 492 error = NULL; 493 connection = dbus_g_bus_get (DBUS_BUS_SESSION, 494 &error); 495 if (connection == NULL) 496 { 497 g_printerr ("Failed to open connection to bus: %s\n", 498 error->message); 499 g_error_free (error); 500 exit (1); 501 } 502 503 /* Create a proxy object for the "bus driver" (name "org.freedesktop.DBus") */ 504 505 proxy = dbus_g_proxy_new_for_name (connection, 506 DBUS_SERVICE_DBUS, 507 DBUS_PATH_DBUS, 508 DBUS_INTERFACE_DBUS); 509 510 /* Call ListNames method, wait for reply */ 511 error = NULL; 512 if (!dbus_g_proxy_call (proxy, "ListNames", &error, G_TYPE_INVALID, 513 G_TYPE_STRV, &name_list, G_TYPE_INVALID)) 514 { 515 /* Just do demonstrate remote exceptions versus regular GError */ 516 if (error->domain == DBUS_GERROR && error->code == DBUS_GERROR_REMOTE_EXCEPTION) 517 g_printerr ("Caught remote method exception %s: %s", 518 dbus_g_error_get_name (error), 519 error->message); 520 else 521 g_printerr ("Error: %s\n", error->message); 522 g_error_free (error); 523 exit (1); 524 } 525 526 /* Print the results */ 527 528 g_print ("Names on the message bus:\n"); 529 530 for (name_list_ptr = name_list; *name_list_ptr; name_list_ptr++) 531 { 532 g_print (" %s\n", *name_list_ptr); 533 } 534 g_strfreev (name_list); 535 536 g_object_unref (proxy); 537 538 return 0; 539} 540</pre><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" 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 552 recieved. The outgoing arguments are specified in the varargs 553 array, terminated with <code class="literal">G_TYPE_INVALID</code>. 554 Next, pointers to return values are specified, followed again 555 by <code class="literal">G_TYPE_INVALID</code>. 556 </p><p> 557 To invoke a method asynchronously, use 558 <code class="literal">dbus_g_proxy_begin_call</code>. This returns a 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" 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 566 invoke <code class="literal">dbus_g_proxy_add_signal</code> to specify 567 the signature of your signal handlers; you may then invoke 568 <code class="literal">dbus_g_proxy_connect_signal</code> multiple times. 569 </p><p> 570 Note that it will often be the case that there is no builtin 571 marshaller for the type signature of a remote signal. In that 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" 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 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 584 <code class="literal">DBUS_GERROR</code>, and a corresponding code 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 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 592 information in the <code class="literal">GError</code>, but some 593 special rules apply. 594 </p><p> 595 The set error will have the domain 596 <code class="literal">DBUS_GERROR</code> as above, and will also 597 have the code 598 <code class="literal">DBUS_GERROR_REMOTE_EXCEPTION</code>. In order 599 to access the remote exception name, you must use a 600 special accessor, such as 601 <code class="literal">dbus_g_error_has_name</code> or 602 <code class="literal">dbus_g_error_get_name</code>. The remote 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" 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 610 error = NULL; 611 if (!dbus_g_proxy_call (proxy, "Foobar", &error, 612 G_TYPE_INT, 42, G_TYPE_STRING, "hello", 613 G_TYPE_INVALID, 614 DBUS_TYPE_G_UCHAR_ARRAY, &arr, G_TYPE_INVALID)) 615 { 616 /* Handle error */ 617 } 618 g_assert (arr != NULL); 619 printf ("got back %u values", arr->len); 620</pre><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; 625 626 g_hash_table_insert (hash, "foo", "bar"); 627 g_hash_table_insert (hash, "baz", "whee"); 628 629 error = NULL; 630 if (!dbus_g_proxy_call (proxy, "HashSize", &error, 631 DBUS_TYPE_G_STRING_STRING_HASH, hash, G_TYPE_INVALID, 632 G_TYPE_UINT, &ret, G_TYPE_INVALID)) 633 { 634 /* Handle error */ 635 } 636 g_assert (ret == 2); 637 g_hash_table_destroy (hash); 638</pre><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; 643 644 error = NULL; 645 if (!dbus_g_proxy_call (proxy, "GetStuff", &error, 646 G_TYPE_INVALID, 647 G_TYPE_BOOLEAN, &boolret, 648 G_TYPE_STRING, &strret, 649 G_TYPE_INVALID)) 650 { 651 /* Handle error */ 652 } 653 printf ("%s %s", boolret ? "TRUE" : "FALSE", strret); 654 g_free (strret); 655</pre><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}; 660 /* Take pointer to array; cannot pass array directly */ 661 char **strs_static_p = strs_static; 662 char **strs_dynamic; 663 664 strs_dynamic = g_new (char *, 4); 665 strs_dynamic[0] = g_strdup ("hello"); 666 strs_dynamic[1] = g_strdup ("world"); 667 strs_dynamic[2] = g_strdup ("!"); 668 /* NULL terminate */ 669 strs_dynamic[3] = NULL; 670 671 error = NULL; 672 if (!dbus_g_proxy_call (proxy, "TwoStrArrays", &error, 673 G_TYPE_STRV, strs_static_p, 674 G_TYPE_STRV, strs_dynamic, 675 G_TYPE_INVALID, 676 G_TYPE_INVALID)) 677 { 678 /* Handle error */ 679 } 680 g_strfreev (strs_dynamic); 681</pre><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; 686 gboolean blah; 687 688 error = NULL; 689 blah = TRUE; 690 if (!dbus_g_proxy_call (proxy, "GetStrs", &error, 691 G_TYPE_BOOLEAN, blah, 692 G_TYPE_INVALID, 693 G_TYPE_STRV, &strs, 694 G_TYPE_INVALID)) 695 { 696 /* Handle error */ 697 } 698 for (strs_p = strs; *strs_p; strs_p++) 699 printf ("got string: \"%s\"", *strs_p); 700 g_strfreev (strs); 701</pre><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 706 g_value_init (&val, G_TYPE_STRING); 707 g_value_set_string (&val, "hello world"); 708 709 error = NULL; 710 if (!dbus_g_proxy_call (proxy, "SendVariant", &error, 711 G_TYPE_VALUE, &val, G_TYPE_INVALID, 712 G_TYPE_INVALID)) 713 { 714 /* Handle error */ 715 } 716 g_assert (ret == 2); 717 g_value_unset (&val); 718</pre><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 723 error = NULL; 724 if (!dbus_g_proxy_call (proxy, "GetVariant", &error, G_TYPE_INVALID, 725 G_TYPE_VALUE, &val, G_TYPE_INVALID)) 726 { 727 /* Handle error */ 728 } 729 if (G_VALUE_TYPE (&val) == G_TYPE_STRING) 730 printf ("%s\n", g_value_get_string (&val)); 731 else if (G_VALUE_TYPE (&val) == G_TYPE_INT) 732 printf ("%d\n", g_value_get_int (&val)); 733 else 734 ... 735 g_value_unset (&val); 736</pre><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> 741 Here is a sample XML file which describes an object that exposes 742 one method, named <code class="literal">ManyArgs</code>. 743 </p><pre class="programlisting"> 744<?xml version="1.0" encoding="UTF-8" ?> 745<node name="/com/example/MyObject"> 746 <interface name="com.example.MyObject"> 747 <method name="ManyArgs"> 748 <arg type="u" name="x" direction="in" /> 749 <arg type="s" name="str" direction="in" /> 750 <arg type="d" name="trouble" direction="in" /> 751 <arg type="d" name="d_ret" direction="out" /> 752 <arg type="s" name="str_ret" direction="out" /> 753 </method> 754 </interface> 755</node> 756</pre><p> 757 </p><p> 758 Run <code class="literal">dbus-binding-tool --mode=glib-client 759 <em class="replaceable"><code>FILENAME</code></em> > 760 <em class="replaceable"><code>HEADER_NAME</code></em></code> to generate the header 761 file. For example: <span class="command"><strong>dbus-binding-tool --mode=glib-client 762 my-object.xml > my-object-bindings.h</strong></span>. This will generate 763 inline functions with the following prototypes: 764 </p><pre class="programlisting"> 765/* This is a blocking call */ 766gboolean 767com_example_MyObject_many_args (DBusGProxy *proxy, const guint IN_x, 768 const char * IN_str, const gdouble IN_trouble, 769 gdouble* OUT_d_ret, char ** OUT_str_ret, 770 GError **error); 771 772/* This is a non-blocking call */ 773DBusGProxyCall* 774com_example_MyObject_many_args_async (DBusGProxy *proxy, const guint IN_x, 775 const char * IN_str, const gdouble IN_trouble, 776 com_example_MyObject_many_args_reply callback, 777 gpointer userdata); 778 779/* This is the typedef for the non-blocking callback */ 780typedef void 781(*com_example_MyObject_many_args_reply) 782(DBusGProxy *proxy, gdouble OUT_d_ret, char * OUT_str_ret, 783 GError *error, gpointer userdata); 784</pre><p> 785 The first argument in all functions is a <code class="literal">DBusGProxy 786 *</code>, which you should create with the usual 787 <code class="literal">dbus_g_proxy_new_*</code> functions. Following that are the 788 "in" arguments, and then either the "out" arguments and a 789 <code class="literal">GError *</code> for the synchronous (blocking) function, or 790 callback and user data arguments for the asynchronous (non-blocking) 791 function. The callback in the asynchronous function passes the 792 <code class="literal">DBusGProxy *</code>, the returned "out" arguments, an 793 <code class="literal">GError *</code> which is set if there was an error otherwise 794 <code class="literal">NULL</code>, and the user data. 795 </p><p> 796 As with the server-side bindings support (see <a class="xref" href="#glib-server" title="GLib API: Implementing Objects">the section called “GLib API: Implementing Objects”</a>), the exact behaviour of the client-side 797 bindings can be manipulated using "annotations". Currently the only 798 annotation used by the client bindings is 799 <code class="literal">org.freedesktop.DBus.GLib.NoReply</code>, which sets the 800 flag indicating that the client isn't expecting a reply to the method 801 call, so a reply shouldn't be sent. This is often used to speed up 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" 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 809 be obviated by the upcoming GLib introspection support. 810 </p><p> 811 Here is a sample XML file which describes an object that exposes 812 one method, named <code class="literal">ManyArgs</code>. 813</p><pre class="programlisting"> 814<?xml version="1.0" encoding="UTF-8" ?> 815 816<node name="/com/example/MyObject"> 817 818 <interface name="com.example.MyObject"> 819 <annotation name="org.freedesktop.DBus.GLib.CSymbol" value="my_object"/> 820 <method name="ManyArgs"> 821 <!-- This is optional, and in this case is redunundant --> 822 <annotation name="org.freedesktop.DBus.GLib.CSymbol" value="my_object_many_args"/> 823 <arg type="u" name="x" direction="in" /> 824 <arg type="s" name="str" direction="in" /> 825 <arg type="d" name="trouble" direction="in" /> 826 <arg type="d" name="d_ret" direction="out" /> 827 <arg type="s" name="str_ret" direction="out" /> 828 </method> 829 </interface> 830</node> 831</pre><p> 832 </p><p> 833 This XML is in the same format as the D-Bus introspection XML 834 format. Except we must include an "annotation" which give the C 835 symbols corresponding to the object implementation prefix 836 (<code class="literal">my_object</code>). In addition, if particular 837 methods symbol names deviate from C convention 838 (i.e. <code class="literal">ManyArgs</code> -> 839 <code class="literal">many_args</code>), you may specify an annotation 840 giving the C symbol. 841 </p><p> 842 Once you have written this XML, run <code class="literal">dbus-binding-tool --mode=glib-server <em class="replaceable"><code>FILENAME</code></em> > <em class="replaceable"><code>HEADER_NAME</code></em>.</code> to 843 generate a header file. For example: <span class="command"><strong>dbus-binding-tool --mode=glib-server my-object.xml > my-object-glue.h</strong></span>. 844 </p><p> 845 Next, include the generated header in your program, and invoke 846 <code class="literal">dbus_g_object_class_install_info</code> in the class 847 initializer, passing the object class and "object info" included in the 848 header. For example: 849 </p><pre class="programlisting"> 850 dbus_g_object_type_install_info (COM_FOO_TYPE_MY_OBJECT, &com_foo_my_object_info); 851 </pre><p> 852 This should be done exactly once per object class. 853 </p><p> 854 To actually implement the method, just define a C function named e.g. 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 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 class="listitem"><p> 863 The first parameter is a pointer to an instance of the object. 864 </p></li><li class="listitem"><p> 865 Following the object instance pointer are the method 866 input values. 867 </p></li><li class="listitem"><p> 868 Following the input values are pointers to return values. 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 873 <code class="literal">g_set_error</code>. 874 </p></li></ul></div><p> 875 </p><p> 876 Finally, you can export an object using <code class="literal">dbus_g_connection_register_g_object</code>. For example: 877 </p><pre class="programlisting"> 878 dbus_g_connection_register_g_object (connection, 879 "/com/foo/MyObject", 880 obj); 881 </pre><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 886 annotations which are often useful. 887 </p><div class="variablelist"><dl><dt><span class="term"><code class="literal">org.freedesktop.DBus.GLib.CSymbol</code></span></dt><dd><p> 888 This annotation is used to specify the C symbol names for 889 the various types (interface, method, etc), if it differs from the 890 name DBus generates. 891 </p></dd><dt><span class="term"><code class="literal">org.freedesktop.DBus.GLib.Async</code></span></dt><dd><p> 892 This annotation marks the method implementation as an 893 asynchronous function, which doesn't return a response straight 894 away but will send the response at some later point to complete 895 the call. This is used to implement non-blocking services where 896 method calls can take time. 897 </p><p> 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 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 class="listitem"><p> 906 The first parameter is a pointer to an instance of the object. 907 </p></li><li class="listitem"><p> 908 Following the object instance pointer are the method 909 input values. 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 914 calling <code class="literal">dbus_g_method_return</code> or 915 <code class="literal">dbus_g_method_return_error</code>. 916 </p></li></ul></div><p> 917 </p></dd><dt><span class="term"><code class="literal">org.freedesktop.DBus.GLib.Const</code></span></dt><dd><p>This attribute can only be applied to "out" 918 <code class="literal"><arg></code> nodes, and specifies that the 919 parameter isn't being copied when returned. For example, this 920 turns a 's' argument from a <code class="literal">char **</code> to a 921 <code class="literal">const char **</code>, and results in the argument not 922 being freed by DBus after the message is sent. 923 </p></dd><dt><span class="term"><code class="literal">org.freedesktop.DBus.GLib.ReturnVal</code></span></dt><dd><p> 924 This attribute can only be applied to "out" 925 <code class="literal"><arg></code> nodes, and alters the expected 926 function signature. It currently can be set to two values: 927 <code class="literal">""</code> or <code class="literal">"error"</code>. The 928 argument marked with this attribute is not returned via a 929 pointer argument, but by the function's return value. If the 930 attribute's value is the empty string, the <code class="literal">GError 931 *</code> argument is also omitted so there is no standard way 932 to return an error value. This is very useful for interfacing 933 with existing code, as it is possible to match existing APIs. 934 If the attribute's value is <code class="literal">"error"</code>, then the 935 final argument is a <code class="literal">GError *</code> as usual. 936 </p><p> 937 Some examples to demonstrate the usage. This introspection XML: 938 </p><pre class="programlisting"> 939<method name="Increment"> 940 <arg type="u" name="x" /> 941 <arg type="u" direction="out" /> 942</method> 943 </pre><p> 944 Expects the following function declaration: 945 </p><pre class="programlisting"> 946gboolean 947my_object_increment (MyObject *obj, gint32 x, gint32 *ret, GError **error); 948 </pre><p> 949 </p><p> 950 This introspection XML: 951 </p><pre class="programlisting"> 952<method name="IncrementRetval"> 953 <arg type="u" name="x" /> 954 <arg type="u" direction="out" > 955 <annotation name="org.freedesktop.DBus.GLib.ReturnVal" value=""/> 956 </arg> 957</method> 958 </pre><p> 959 Expects the following function declaration: 960 </p><pre class="programlisting"> 961gint32 962my_object_increment_retval (MyObject *obj, gint32 x) 963 </pre><p> 964 </p><p> 965 This introspection XML: 966 </p><pre class="programlisting"> 967<method name="IncrementRetvalError"> 968 <arg type="u" name="x" /> 969 <arg type="u" direction="out" > 970 <annotation name="org.freedesktop.DBus.GLib.ReturnVal" value="error"/> 971 </arg> 972</method> 973 </pre><p> 974 Expects the following function declaration: 975 </p><pre class="programlisting"> 976gint32 977my_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" 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" 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" 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> 992
