|
|
| (2 intermediate revisions by one other user not shown) |
| Line 1: |
Line 1: |
| | This tutorial was updated and moved to https://develop.kde.org/docs/features/d-bus/introduction_to_dbus/ |
|
| |
|
| {{TutorialBrowser|
| | [[Category:MovedDevelop]] |
| | |
| series=D-Bus|
| |
| | |
| name=Introduction To D-BUS|
| |
| | |
| next=[[../Accessing Interfaces|Accessing Interfaces]]|
| |
| | |
| reading=[http://www.freedesktop.org/wiki/Software/dbus#head-9e9cf3221a30246219863f1d2366e36cb580debc D-Bus documentation page]
| |
| }}
| |
| | |
| == Abstract ==
| |
| | |
| [http://www.freedesktop.org/wiki/Software/dbus D-Bus] is a Free/Open Source software '''i'''nter-'''p'''rocess '''c'''ommunication (IPC) mechanism that is in widespread use by open source desktop software today. It is part of the [http://freedesktop.org freedesktop.org] project and used in a wide range of applications. Examples include hotplug notifications on Linux, desktop search queries in strigi and as the primary means of IPC in KDE Plasma. This tutorial introduces D-Bus terminology and looks at the basic concepts of D-Bus, from an application developer's perspective.
| |
| | |
| == What Is IPC? ==
| |
| | |
| The term "IPC" can be used to describe any number of methods of getting information from one process to another. The information transmitted may take the form of application data, method invocations or spontaneous signals. The actual communication is usually done over sockets or pipes and sometimes, as is the case with D-Bus, uses a process to perform message routing, service activation and access control.
| |
| | |
| The use cases for IPC on the desktop range from scripting (allowing a user to execute a script in a common environment to interact with or control various running applications), to providing access to centralized services, to coordination between multiple instances of cooperative applications.
| |
| | |
| As a concrete example, file access in KDE applications is usually performed via the KIO virtual file system (VFS) using KIOSlaves. These KIOSlaves are small applications that implement read, write, etc access to data over a given protocol or specification (e.g. http or local filesystem APIs). The slaves are run as independent processes and exchange data with the application — which the user is interacting with — asynchronously via IPC. This not only allows the same slave to be used by multiple applications but it also keeps the slaves themselves simple as they can do things such as perform blocking operations without causing the graphical application itself to block. The graphical application never actually "sees" the IPC occurring as it happens behind the scenes of KIO API.
| |
| | |
| Another example of IPC usage is in KDE's unique application support. When a KUniqueApplication is started it checks first for other running instances of the same application and if there is one it sends a message to the running instance via IPC to show itself.
| |
| | |
| The primary IPC mechanism for applications in KDE Plasma is D-Bus, which is a popular system used by a variety of software today. Qt provides a set of intuitive and stable bindings to D-Bus in the form of C++ classes. This series of tutorials introduces D-Bus as well as covers how to use the Qt D-Bus API. This particular article describes the high-level concepts in D-Bus and leaves the details of how one uses these features and functionality to the articles that follow.
| |
| | |
| == Buses ==
| |
| | |
| D-Bus provides multiple message "buses" for applications to use in communicating with each other. Each bus provides its own connection facilities, which allow for the separation of different categories of messages: messages sent on one bus can not be accessed from another bus, but applications connected to the same bus may all communicate with each other. Multiple applications can be connected to any given bus at any given time, and an application can be connected to multiple buses simultaneously. This allows different security policies to be applied to different buses while also allowing for the efficient sharing of both global and local messages.
| |
| | |
| A system-wide bus for messages from the operating system kernel itself and other system-global services is provided by default and is called, appropriately, the '''system bus'''. This is the bus used to do things such as signal when new hardware is made available to the system, such as when a flash drive is plugged in a or a DVD is inserted into the drive.
| |
| | |
| Each desktop session (e.g. each logged in user) has one or more buses associated with it. These are called '''session buses'''. The default bus for the current session is called ''the'' session bus and is the one that desktop applications will tend to use most often.
| |
| | |
| Additionally, an application may create its own private bus between itself and another application in a peer-to-peer fashion.
| |
| | |
| There is no practical limit to the number of buses the applications associated with a given user may be using. However, it is the ability to share buses — and therefore common messaging — where systems like D-Bus really shine.
| |
| | |
| == Messages ==
| |
| | |
| The base unit of communication on a bus is the '''message'''. All information passed over the bus is done in the form of messages, similar to the way information transmitted using TCP/IP is done via packets. Unlike network packets, however, each D-Bus message is guaranteed to contain the entire set of data being sent or received. In addition to the data being sent, messages also record who the sender and intended receiver are to allow for proper routing.
| |
| | |
| This system maps well to how desktop applications tend to work internally: method calls (messages) result in some action being taken with the possibility of return values. One of the primary additional features of D-Bus messages is that they are asynchronous: a message may be sent while the reply may not happen for an indeterminate period of time (timeouts are provided to prevent 'wait forever' deadlocks). Of course, there are conveniences in the Qt D-Bus API to make calls appear to be synchronous to the calling application.
| |
| | |
| Messages can be sent by an application to itself. These are "short-circuited" and kept local to the application, so it is not necessary for code in an application to worry about whether or not it might actually be calling a remote or local application. This is often useful in highly componentized apps and prevents possible deadlock situations.
| |
| | |
| == Namespaces and Addresses ==
| |
| | |
| Since multiple applications can be on the same bus, and one application may provide multiple objects to which messages can be sent, it is necessary to have a means to effectively and unambiguously address any given object on any given bus, similar to the way a street address uniquely identifies any given residence or office. There are 3 pieces of information which, when taken together, create a unique address for any given object on a bus: interface, service and object name.
| |
| | |
| === Interfaces ===
| |
| | |
| An '''interface''' is a set of callable methods and signals that are advertised on the bus. An interface provides a "contract" between the applications passing messages that defines the name, parameters (if any) and return values (if any) of the interface. These methods may not map directly in a one-to-one fashion to methods or API in the application that is advertising the interface, though they often do. This allows multiple applications to provide similar or the same interfaces, regardless of internal implementation, while allowing applications to use these interfaces without worrying about the internal design of the applications.
| |
| | |
| Interfaces can be described for documentation and code re-use purposes using XML. Not only can users and programmers reference the XML description of the interface, but developers can use classes that are auto-generated from the XML — making using D-Bus much easier and less error-prone (e.g. the compiler can check the syntax of messages at compile time).
| |
| | |
| === Services ===
| |
| | |
| A '''service''' represents an application connection to a bus.
| |
| | |
| '''Service''' here corresponds to "well-known" [http://dbus.freedesktop.org/doc/dbus-specification.html#message-protocol-names Bus names] in the D-Bus specification terminology. The term "Bus name" is a bit confusing. Regardless of how it sounds like, '''Bus names''' are the names of connections(!) on the bus, not names of buses(!). So here the term '''service''' will be used, as the Qt Documentation calls it.
| |
| | |
| These are kept unique by using a "reverse domain name" approach, as can be seen in many other systems that need to namespace for multiple components. Most services provided by applications from the KDE project itself use the <tt>org.kde</tt> prefix to their service name. So one may find "org.kde.screensaver" advertised on the session bus.
| |
| | |
| You should use the domain name for your organization or application for your service names. For example if your domain is <tt>awesomeapps.org</tt> and the name of your application is <tt>wickedwidget</tt> you would probably use <tt>org.awesomeapps.wickedwidget</tt> as the service name on the bus.
| |
| | |
| If an application has more than one connection to a bus, or if multiple instances of the same application may be active at once, it will need to use a unique service name for each connection. Often this is done by appending the process ID to the service name.
| |
| | |
| === Objects ===
| |
| | |
| Of course, an application is likely to advertise access to more than one object on the bus. This many-to-one relationship between objects and services is accommodated by providing a '''path''' component to the address. Each path associated with a service represents a different, unique object. An example might be <tt>/MainInterface</tt> or <tt>/Documents/Doc1</tt>. The actual path structure is completely arbitrary and is up to the application providing the service as to what the paths should be. These paths simply provide a way to identify and logically group objects for applications that send messages to the application.
| |
| | |
| Some libraries export object paths with their "reverse domain" prepended to it, so as to properly namespace their objects. This is quite common for libraries and plugins that join an arbitrary service and must therefore avoid all clashing with objects exported by the application and other components. However, this practice is not in use in KDE applications and libraries.
| |
| | |
| Objects provide access to interfaces. In fact, a given object can provide access to multiple interfaces at the same time.
| |
| | |
| === Putting It All Together ===
| |
| | |
| A D-Bus message contains an address made up of all the above components so that it can be routed to the correct application, object and method call. Such an address might look like this:
| |
| | |
| <syntaxhighlight lang="text">
| |
| org.kde.krunner /App org.kde.krunner.App.display
| |
| </syntaxhighlight>
| |
| | |
| In this case <tt>org.kde.krunner</tt> is the service, <tt>/App</tt> is the path to the object, <tt>org.kde.krunner.App</tt> is the interface the object exports and <tt>display</tt> is a method in the interface. If the <tt>/Aoo</tt> object only provides the <tt>org.kde.krunner.App</tt> interface (or the <tt>display</tt> method is unique amongst the services it implements) then this would work equally well as an address:
| |
| | |
| <syntaxhighlight lang="text">
| |
| org.kde.krunner /App display
| |
| </syntaxhighlight>
| |
| | |
| In this way each possible destination is uniquely and reliably addressable.
| |
| | |
| == Calling and Being Called ==
| |
| | |
| Now that we have a way to address any given end point on the bus, we can examine the possibilities when it comes to actually sending or receiving messages.
| |
| | |
| === Methods ===
| |
| | |
| Methods are messages that are sent to cause code to be executed in the receiving application. If the method is not available because, for instance, the address was wrong or the requested application is not running, an error will be returned to the calling application. If the method is successfully called, an optional return value will be returned to the calling application. Even if there is no return value provided, a success message will be returned. This round trip does have overhead, and it is important to keep this in mind for performance critical code.
| |
| | |
| Such method calls are always initiated by the calling application and the resulting messages have exactly one source and one destination address.
| |
| | |
| === Signals ===
| |
| | |
| Signals are like method calls except that they happen in the "reverse" direction and are not tied to a single destination. A signal is emitted by the application which is exporting the interface and is available to any application on the same bus. This allows an application to spontaneously advertise changes in state or other events, to any applications which may be interested in tracking those changes.
| |
| | |
| If this sounds a lot like the signal and slots mechanism in Qt, that's because it is. For all intents and purposes it is a non-local version of the same functionality.
| |
| | |
| == Useful Tools ==
| |
| | |
| There are several useful tools for exploring the D-Bus busses as well as developing applications that use D-Bus. We will now look briefly at end-user tools as the articles that follow cover the development tools in greater detail and context.
| |
| | |
| === qdbus ===
| |
| | |
| <tt>qdbus</tt> is a command line tool which can be used to list the services, objects and interfaces on a given bus as well as send messages to a given address on the bus. It can be used to explore both the system and the default session bus. If the <tt>--system</tt> switch is passed, <tt>qdbus</tt> will connect to the system bus, otherwise it uses the session bus.
| |
| | |
| <tt>qdbus</tt> uses the rest of the supplied arguments on the command as an address and, if any, parameters to pass to a given object. If a full address is not supplied, then it lists all the objects available from that point on the bus. For instance, if no addresses are provided a list of available services is listed. If a service name is provided, object paths will be provided. If a path is also provided all methods in all interfaces will be listed. In this way one can quite easily explore and interact with objects on the bus, making <tt>qdbus</tt> very useful for testing, scripting and even idle exploration.
| |
| | |
| === qdbusviewer ===
| |
| | |
| <tt>qdbusviewer</tt> is a Qt application that provides a graphical interface to essentially the same set of features that <tt>qdbus</tt> provides on the command line, thus providing a more user friendly mechanism to interact with the bus. <tt>qdbusviewer</tt> ships with Qt itself and is easy for anyone who is familiar with the basic D-Bus concepts, such as object addresses, to use.
| |
