1<?xml version="1.0" standalone="no"?> 2<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" 3"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" 4[ 5]> 6 7<article id="index"> 8 <articleinfo> 9 <title>D-Bus FAQ</title> 10 <releaseinfo>Version 0.3</releaseinfo> 11 <date>17 November 2006</date> 12 <authorgroup> 13 <author> 14 <firstname>Havoc</firstname> 15 <surname>Pennington</surname> 16 <affiliation> 17 <orgname>Red Hat, Inc.</orgname> 18 <address> 19 <email>hp@pobox.com</email> 20 </address> 21 </affiliation> 22 </author> 23 <author> 24 <firstname>David</firstname> 25 <othername role="mi">A</othername> 26 <surname>Wheeler</surname> 27 </author> 28 </authorgroup> 29 </articleinfo> 30 31 <qandaset id="faq"> 32 33 <qandaentry> 34 <question> 35 <para> 36 What is D-Bus? 37 </para> 38 </question> 39 <answer> 40 <para> 41 This is probably best answered by reading the D-Bus <ulink url="dbus-tutorial.html">tutorial</ulink> or 42 the introduction to the <ulink url="dbus-specification.html">specification</ulink>. In 43 short, it is a system consisting of 1) a wire protocol for exposing a 44 typical object-oriented language/framework to other applications; and 45 2) a bus daemon that allows applications to find and monitor one another. 46 Phrased differently, D-Bus is 1) an interprocess communication (IPC) system and 2) some higher-level 47 structure (lifecycle tracking, service activation, security policy) provided by two bus daemons, 48 one systemwide and one per-user-session. 49 </para> 50 </answer> 51 </qandaentry> 52 53 <qandaentry> 54 <question> 55 <para> 56 Is D-Bus stable/finished? 57 </para> 58 </question> 59 <answer> 60 <para> 61 The low-level library "libdbus" and the protocol specification are considered 62 ABI stable. The <ulink url="README">README</ulink> 63 file has a discussion of the API/ABI stability guarantees. 64 Higher-level bindings (such as those for Qt, GLib, Python, Java, C#) each 65 have their own release schedules and degree of maturity, not linked to 66 the low-level library and bus daemon release. Check the project page for 67 the binding you're considering to understand that project's policies. 68 </para> 69 </answer> 70 </qandaentry> 71 72 <qandaentry> 73 <question> 74 <para> 75 How is the reference implementation licensed? Can I use it in 76 proprietary applications? 77 </para> 78 </question> 79 <answer> 80 <para> 81 The short answer is yes, you can use it in proprietary applications. 82 You should read the <ulink url="COPYING">COPYING</ulink> file, which 83 offers you the choice of two licenses. These are the GPL and the 84 AFL. The GPL requires that your application be licensed under the GPL 85 as well. The AFL is an "X-style" or "BSD-style" license compatible 86 with proprietary licensing, but it does have some requirements; in 87 particular it prohibits you from filing a lawsuit alleging that the 88 D-Bus software infringes your patents <emphasis>while you continue to 89 use D-Bus</emphasis>. If you're going to sue, you have to stop using 90 the software. Read the licenses to determine their meaning, this FAQ 91 entry is not intended to change the meaning or terms of the licenses. 92 </para> 93 </answer> 94 </qandaentry> 95 96 <qandaentry> 97 <question> 98 <para> 99 What is the difference between a bus name, and object path, 100 and an interface? 101 </para> 102 </question> 103 <answer> 104 <para> 105 If you imagine a C++ program that implements a network service, then 106 the bus name is the hostname of the computer running this C++ program, 107 the object path is a C++ object instance pointer, and an interface is 108 a C++ class (a pure virtual or abstract class, to be exact). 109 </para> 110 <para> 111 In Java terms, the object path is an object reference, 112 and an interface is a Java interface. 113 </para> 114 <para> 115 People get confused because if they write an application 116 with a single object instance and a single interface, 117 then the bus name, object path, and interface look 118 redundant. For example, you might have a text editor 119 that uses the bus name <literal>org.freedesktop.TextEditor</literal>, 120 has a global singleton object called 121 <literal>/org/freedesktop/TextEditor</literal>, and 122 that singleton object could implement the interface 123 <literal>org.freedesktop.TextEditor</literal>. 124 </para> 125 <para> 126 However, a text editor application could as easily own multiple bus 127 names (for example, <literal>org.kde.KWrite</literal> in addition to 128 generic <literal>TextEditor</literal>), have multiple objects (maybe 129 <literal>/org/kde/documents/4352</literal> where the number changes 130 according to the document), and each object could implement multiple 131 interfaces, such as <literal>org.freedesktop.DBus.Introspectable</literal>, 132 <literal>org.freedesktop.BasicTextField</literal>, 133 <literal>org.kde.RichTextDocument</literal>. 134 </para> 135 </answer> 136 </qandaentry> 137 138 139 <qandaentry id="service"> 140 <question> 141 <para> 142 What is a "service"? 143 </para> 144 </question> 145 <answer> 146 <para> 147 A service is a program that can be launched by the bus daemon 148 to provide some functionality to other programs. Services 149 are normally launched according to the bus name they will 150 have. 151 </para> 152 <para> 153 People often misuse the word "service" for any 154 bus name, but this tends to be ambiguous and confusing so is discouraged. 155 In the D-Bus docs we try to use "service" only when talking about 156 programs the bus knows how to launch, i.e. a service always has a 157 .service file. 158 </para> 159 </answer> 160 </qandaentry> 161 162 <qandaentry id="components"> 163 <question> 164 <para> 165 Is D-Bus a "component system"? 166 </para> 167 </question> 168 <answer> 169 <para> 170 It helps to keep these concepts separate in your mind: 171 <orderedlist> 172 <listitem> 173 <para> 174 Object/component system 175 </para> 176 </listitem> 177 <listitem> 178 <para> 179 GUI control/widget embedding interfaces 180 </para> 181 </listitem> 182 <listitem> 183 <para> 184 Interprocess communication system or wire protocol 185 </para> 186 </listitem> 187 </orderedlist> 188 </para> 189 <para> 190 D-Bus is not a component system. "Component system" was originally 191 defined by COM, and was essentially a workaround for the limitations 192 of the C++ object system (adding introspection, runtime location of 193 objects, ABI guarantees, and so forth). With the C# language and CLR, 194 Microsoft added these features to the primary object system, leaving 195 COM obsolete. Similarly, Java has much less need for something like 196 COM than C++ did. Even QObject (from Qt) and GObject (from GLib) offer 197 some of the same features found in COM. 198 </para> 199 <para> 200 Component systems are not about GUI control embedding. Embedding 201 a spreadsheet in a word processor document is a matter of defining 202 some specific <emphasis>interfaces</emphasis> that objects 203 can implement. These interfaces provide methods related to 204 GUI controls. So an object implementing those interfaces 205 can be embedded. 206 </para> 207 <para> 208 The word "component" just means "object with some fancy features" and 209 in modern languages all objects are effectively "components." 210 </para> 211 <para> 212 So components are fancy objects, and some objects are GUI controls. 213 </para> 214 <para> 215 A third, unrelated feature is interprocess communication or IPC. 216 D-Bus is an IPC system. Given an object (or "component" if you must), 217 you can expose the functionality of that object over an IPC system. 218 Examples of IPC systems are DCOM, CORBA, SOAP, XML-RPC, and D-Bus. 219 You can use any of these IPC systems with any object/component system, 220 though some of them are "tuned" for specific object systems. 221 You can think of an IPC system primarily as a wire protocol. 222 </para> 223 <para> 224 If you combine an IPC system with a set of GUI control interfaces, 225 then you can have an out-of-process or dynamically-loaded GUI control. 226 </para> 227 <para> 228 Another related concept is the <firstterm>plugin</firstterm> or 229 <firstterm>extension</firstterm>. Generic plugin systems such as the 230 <ulink url="http://eclipse.org">Eclipse</ulink> system are not so different 231 from component/object systems, though perhaps a "plugin" tends to be a 232 bundle of objects with a user-visible name and can be 233 downloaded/packaged as a unit. 234 </para> 235 </answer> 236 </qandaentry> 237 238 <qandaentry id="speed"> 239 <question> 240 <para> 241 How fast is the D-Bus reference implementation? 242 </para> 243 </question> 244 <answer> 245 <para> 246 Of course it depends a bit on what you're doing. 247 <ulink url="http://lists.freedesktop.org/pipermail/dbus/2004-November/001779.html"> 248 This mail</ulink> contains some benchmarking. At the time of that 249 benchmark, D-Bus one-to-one communication was about 2.5x slower than 250 simply pushing the data raw over a socket. After the recent rewrite of 251 the marshaling code, D-Bus is slower than that because a lot of 252 optimization work was lost. But it can probably be sped up again. 253 </para> 254 <para> 255 D-Bus communication with the intermediate bus daemon should be 256 (and as last profiled, was) about twice as slow as one-to-one 257 mode, because a round trip involves four socket reads/writes rather 258 than two socket reads/writes. 259 </para> 260 <para> 261 The overhead comes from a couple of places; part of it is simply 262 "abstraction penalty" (there are layers of code to support 263 multiple main loops, multiple transport types, security, etc.). 264 Probably the largest part comes from data validation 265 (because the reference implementation does not trust incoming data). 266 It would be simple to add a "no validation" mode, but probably 267 not a good idea all things considered. 268 </para> 269 <para> 270 Raw bandwidth isn't the only concern; D-Bus is designed to 271 enable asynchronous communication and avoid round trips. 272 This is frequently a more important performance issue 273 than throughput. 274 </para> 275 </answer> 276 </qandaentry> 277 278 279 <qandaentry id="size"> 280 <question> 281 <para> 282 How large is the D-Bus reference implementation? 283 </para> 284 </question> 285 <answer> 286 <para> 287 A production build (with assertions, unit tests, and verbose logging 288 disabled) is on the order of a 150K shared library. 289 </para> 290 <para> 291 A much, much smaller implementation would be possible by omitting out 292 of memory handling, hardcoding a main loop (or always using blocking 293 I/O), skipping validation, and otherwise simplifying things. 294 </para> 295 </answer> 296 </qandaentry> 297 298 <qandaentry id="other-ipc"> 299 <question> 300 <para> 301 How does D-Bus differ from other interprocess communication 302 or networking protocols? 303 </para> 304 </question> 305 <answer> 306 <para> 307 Keep in mind, it is not only an IPC system; it also includes 308 lifecycle tracking, service activation, security policy, and other 309 higher-level structure and assumptions. 310 </para> 311 <para> 312 The best place to start is to read the D-Bus <ulink url="dbus-tutorial.html">tutorial</ulink>, so 313 you have a concrete idea what D-Bus actually is. If you 314 understand other protocols on a wire format level, you 315 may also want to read the D-Bus <ulink url="dbus-specification.html">specification</ulink> to see what 316 D-Bus looks like on a low level. 317 </para> 318 <para> 319 As the <ulink url="dbus-tutorial.html">tutorial</ulink> and <ulink url="dbus-specification.html">specification</ulink> both explain, D-Bus is tuned 320 for some specific use cases. Thus, it probably isn't tuned 321 for what you want to do, unless you are doing the things 322 D-Bus was designed for. Don't make the mistake of thinking 323 that any system involving "IPC" is the same thing. 324 </para> 325 <para> 326 The D-Bus authors would not recommend using D-Bus 327 for applications where it doesn't make sense. 328 The following questions compare D-Bus to some other 329 protocols primarily to help you understand D-Bus 330 and decide whether it's appropriate; D-Bus is neither intended 331 nor claimed to be the right choice for every application. 332 </para> 333 <para> 334 It should be possible to bridge D-Bus to other IPC systems, 335 just as D-Bus can be bridged to object systems. 336 </para> 337 <para> 338 Note: the D-Bus mailing list subscribers are <emphasis>very much not 339 interested</emphasis> in debating which IPC system is the One True 340 System. So if you want to discuss that, please use another forum. 341 </para> 342 </answer> 343 </qandaentry> 344 345 346 <qandaentry id="corba"> 347 <question> 348 <para> 349 How does D-Bus differ from CORBA? 350 </para> 351 </question> 352 <answer> 353 <para> 354 Start by reading <xref linkend="other-ipc"/>. 355 </para> 356 <para> 357 <ulink url="http://www.omg.org">CORBA</ulink> is designed to support 358 object-oriented IPC between objects, automatically marshalling 359 parameters as necessary. CORBA is strongly supported by the <ulink 360 url="http://www.omg.org">Open Management Group (OMG)</ulink>, which 361 produces various standards and supporting documents for CORBA and has 362 the backing of many large organizations. There are many CORBA ORBs 363 available, both proprietary ORBs and free / open source software ORBs 364 (the latter include <ulink 365 url="http://orbit-resource.sourceforge.net/">ORBit</ulink>, <ulink 366 url="http://www.mico.org/">MICO</ulink>, and <ulink 367 url="http://www.theaceorb.com/">The ACE Orb (TAO)</ulink>). Many 368 organizations continue to use CORBA ORBs for various kinds of IPC. 369 </para> 370 <para> 371 Both GNOME and KDE have used CORBA and then moved away from it. KDE 372 had more success with a system called DCOP, and GNOME layered a system 373 called Bonobo on top of CORBA. Without custom extensions, CORBA does 374 not support many of the things one wants to do in a desktop 375 environment with the GNOME/KDE architecture. 376 </para> 377 <para> 378 CORBA on the other hand has a number of features of interest for 379 enterprise and web application development, though XML systems such as 380 SOAP are the latest fad. 381 </para> 382 <para> 383 Like D-Bus, CORBA uses a fast binary protocol (IIOP). Both systems 384 work in terms of objects and methods, and have concepts such as 385 "oneway" calls. Only D-Bus has direct support for "signals" as in 386 GLib/Qt (or Java listeners, or C# delegates). 387 </para> 388 <para> 389 D-Bus hardcodes and specifies a lot of things that CORBA leaves open-ended, 390 because CORBA is more generic and D-Bus has two specific use-cases in mind. 391 This makes D-Bus a bit simpler. 392 </para> 393 <para> 394 However, unlike CORBA D-Bus does <emphasis>not</emphasis> specify the 395 API for the language bindings. Instead, "native" bindings adapted 396 specifically to the conventions of a framework such as QObject, 397 GObject, C#, Java, Python, etc. are encouraged. The libdbus reference 398 implementation is designed to be a backend for bindings of this 399 nature, rather than to be used directly. The rationale is that an IPC 400 system API should not "leak" all over a program; it should come into 401 play only just before data goes over the wire. As an aside, OMG is 402 apparently working on a simpler C++ binding for CORBA. 403 </para> 404 <para> 405 Many CORBA implementations such as ORBit are faster than the libdbus 406 reference implementation. One reason is that D-Bus considers data 407 from the other end of the connection to be untrusted and extensively 408 validates it. But generally speaking other priorities were placed 409 ahead of raw speed in the libdbus implementation. A fast D-Bus 410 implementation along the lines of ORBit should be possible, of course. 411 </para> 412 <para> 413 On a more trivial note, D-Bus involves substantially fewer acronyms 414 than CORBA. 415 </para> 416 </answer> 417 </qandaentry> 418 419 420 <qandaentry id="xmlrpcsoap"> 421 <question> 422 <para> 423 How does D-Bus differ from XML-RPC and SOAP? 424 </para> 425 </question> 426 <answer> 427 <para> 428 Start by reading <xref linkend="other-ipc"/>. 429 </para> 430 <para> 431 In <ulink url="http://www.w3.org/TR/SOAP/">SOAP</ulink> and <ulink 432 url="http://www.xmlrpc.com">XML-RPC</ulink>, RPC calls are transformed 433 into an XML-based format, then sent over the wire (typically using the 434 HTTP protocol), where they are processed and returned. XML-RPC is the 435 simple protocol (its spec is only a page or two), and SOAP is the 436 full-featured protocol. 437 </para> 438 <para> 439 XML-RPC and SOAP impose XML parsing overhead that is normally 440 irrelevant in the context of the Internet, but significant for 441 constant fine-grained IPC among applications in a desktop session. 442 </para> 443 <para> 444 D-Bus offers persistent connections and with the bus daemon 445 supports lifecycle tracking of other applications connected 446 to the bus. With XML-RPC and SOAP, typically each method call 447 exists in isolation and has its own HTTP connection. 448 </para> 449 </answer> 450 </qandaentry> 451 452 <qandaentry id="dce"> 453 <question> 454 <para> 455 How does D-Bus differ from DCE? 456 </para> 457 </question> 458 <answer> 459 <para> 460 Start by reading <xref linkend="other-ipc"/>. 461 </para> 462 <para> 463 <ulink url="http://www.opengroup.org/dce/">Distributed Computing 464 Environment (DCE)</ulink> is an industry-standard vendor-neutral 465 standard that includes an IPC mechanism. <ulink 466 url="http://www.opengroup.org/comm/press/05-01-12.htm">The Open Group 467 has released an implementation as open source software</ulink>. DCE 468 is quite capable, and includes a vast amount of functionality such as 469 a distributed time service. As the name implies, DCE is intended for 470 use in a large, multi-computer distributed application. D-Bus would 471 not be well-suited for this. 472 </para> 473 </answer> 474 </qandaentry> 475 476 477 <qandaentry id="dcom"> 478 <question> 479 <para> 480 How does D-Bus differ from DCOM and COM? 481 </para> 482 </question> 483 <answer> 484 <para> 485 Start by reading <xref linkend="other-ipc"/>. 486 </para> 487 <para> 488 Comparing D-Bus to COM is apples and oranges; 489 see <xref linkend="components"/>. 490 </para> 491 <para> 492 DCOM (distributed COM) is a Windows IPC system designed for use with 493 the COM object system. It's similar in some ways to DCE and CORBA. 494 </para> 495 </answer> 496 </qandaentry> 497 498 <qandaentry id="internet-communications-engine"> 499 <question> 500 <para> 501 How does D-Bus differ from ZeroC's Internet Communications Engine (Ice) 502 </para> 503 </question> 504 <answer> 505 <para> 506 Start by reading <xref linkend="other-ipc"/>. 507 </para> 508 <para> 509 The <ulink url="http://www.zeroc.com/ice.html"> Internet 510 Communications Engine (Ice)</ulink> is a powerful IPC mechanism more 511 on the level of SOAP or CORBA than D-Bus. Ice has a "dual-license" 512 business around it; i.e. you can use it under the GPL, or pay for a 513 proprietary license. 514 </para> 515 </answer> 516 </qandaentry> 517 518 <qandaentry id="inter-client-exchange"> 519 <question> 520 <para> 521 How does D-Bus differ from Inter-Client Exchange (ICE)? 522 </para> 523 </question> 524 <answer> 525 <para> 526 <ulink url="http://www.x.org/X11R6.8.1/docs/ICE/ice.pdf">ICE</ulink> 527 was developed for the X Session Management protocol (XSMP), as part of 528 the X Window System (X11R6.1). The idea was to allow desktop sessions 529 to contain nongraphical clients in addition to X clients. 530 </para> 531 <para> 532 ICE is a binary protocol designed for desktop use, and KDE's DCOP 533 builds on ICE. ICE is substantially simpler than D-Bus (in contrast 534 to most of the other IPC systems mentioned here, which are more 535 complex). ICE doesn't really define a mapping to objects and methods 536 (DCOP adds that layer). The reference implementation of ICE (libICE) 537 is often considered to be horrible (and horribly insecure). 538 </para> 539 <para> 540 DCOP and XSMP are the only two widely-used applications of ICE, 541 and both could in principle be replaced by D-Bus. (Though whether 542 GNOME and KDE will bother is an open question.) 543 </para> 544 </answer> 545 </qandaentry> 546 547 548 549 <qandaentry id="dcop"> 550 <question> 551 <para> 552 How does D-Bus differ from DCOP? 553 </para> 554 </question> 555 <answer> 556 <para> 557 Start by reading <xref linkend="other-ipc"/>. 558 </para> 559 <para> 560 D-Bus is intentionally pretty similar to <ulink 561 url="http://developer.kde.org/documentation/library/kdeqt/dcop.html">DCOP</ulink>, 562 and can be thought of as a "DCOP the next generation" suitable for 563 sharing between the various open source desktop projects. 564 </para> 565 <para> 566 D-Bus is a bit more complex than DCOP, though the Qt binding for D-Bus 567 should not be more complex for programmers. The additional complexity 568 of D-Bus arises from its separation of object references vs. bus names 569 vs. interfaces as distinct concepts, and its support for one-to-one 570 connections in addition to connections over the bus. The libdbus 571 reference implementation has a lot of API to support multiple bindings 572 and main loops, and performs data validation and out-of-memory handling 573 in order to support secure applications such as the systemwide bus. 574 </para> 575 <para> 576 D-Bus is probably somewhat slower than DCOP due to data validation 577 and more "layers" in the reference implementation. A comparison 578 hasn't been posted to the list though. 579 </para> 580 <para> 581 At this time, KDE has not committed to using D-Bus, but there have 582 been discussions of KDE bridging D-Bus and DCOP, or even changing 583 DCOP's implementation to use D-Bus internally (so that GNOME and KDE 584 would end up using exactly the same bus). See the KDE mailing list 585 archives for some of these discussions. 586 </para> 587 </answer> 588 </qandaentry> 589 590 591 <qandaentry id="yet-more-ipc"> 592 <question> 593 <para> 594 How does D-Bus differ from [yet more IPC mechanisms]? 595 </para> 596 </question> 597 <answer> 598 <para> 599 Start by reading <xref linkend="other-ipc"/>. 600 </para> 601 <para> 602 There are countless uses of network sockets in the world. <ulink 603 url="http://www.mbus.org/">MBUS</ulink>, Sun ONC/RPC, Jabber/XMPP, 604 SIP, are some we can think of quickly. 605 </para> 606 </answer> 607 </qandaentry> 608 609 610 <qandaentry id="which-ipc"> 611 <question> 612 <para> 613 Which IPC mechanism should I use? 614 </para> 615 </question> 616 <answer> 617 <para> 618 Start by reading <xref linkend="other-ipc"/>. 619 </para> 620 <para> 621 If you're writing an Internet or Intranet application, XML-RPC or SOAP 622 work for many people. These are standard, available for most 623 languages, simple to debug and easy to use. 624 </para> 625 <para> 626 If you're writing a desktop application for UNIX, 627 then D-Bus is of course our recommendation for 628 talking to other parts of the desktop session. 629 </para> 630 <para> 631 D-Bus is also designed for communications between system daemons and 632 communications between the desktop and system daemons. 633 </para> 634 <para> 635 If you're doing something complicated such as clustering, 636 distributed swarms, peer-to-peer, or whatever then 637 the authors of this FAQ don't have expertise in these 638 areas and you should ask someone else or try a search engine. 639 D-Bus is most likely a poor choice but could be appropriate 640 for some things. 641 </para> 642 <para> 643 Note: the D-Bus mailing list is probably not the place to 644 discuss which system is appropriate for your application, 645 though you are welcome to ask specific questions about 646 D-Bus <emphasis>after reading this FAQ, the tutorial, and 647 searching the list archives</emphasis>. The best way 648 to search the list archives is probably to use 649 an Internet engine such as Google. On Google, 650 include "site:freedesktop.org" in your search. 651 </para> 652 </answer> 653 </qandaentry> 654 655 656 <qandaentry> 657 <question> 658 <para> 659 How can I submit a bug or patch? 660 </para> 661 </question> 662 <answer> 663 <para> 664 The D-Bus <ulink url="http://dbus.freedesktop.org">web site</ulink> 665 has a link to the bug tracker, which is the best place to store 666 patches. You can also post them to the list, especially if you want 667 to discuss the patch or get feedback. 668 </para> 669 </answer> 670 </qandaentry> 671 672 </qandaset> 673 674</article> 675