Introduction
************

The aim of this manual is to familiarise the reader with the concepts and tools necessary to successfully integrate a GNUstep application into a desktop environment based around message exchange through the D-Bus messaging bus facilities. The manual tries to give succinct explanation of the concepts involved, providing illustrative examples whenever possible.

It will be most useful to a reader who has basic working knowledge of the Objective-C programming language and the OpenStep APIs (either from the GNUstep implementation or from Apple's Cocoa). In depth knowledge of the Distributed Objects system or D-Bus is also beneficial but not required.

An IPC primer
=============

A typical modern computer system executes multiple units of computation at the same time. Even with a single-core CPU, the operating system will constantly switch between different units of computation by employing different multitasking strategies. This approach has a number of advantages, e.g.:

  * It facilitates isolation of processes from one another: A malignant process cannot easily modify the memory of other processes on the system.

  * It allows privilege separation: It is not necessary that a web-browser has the same rights as a partitioning utility. Running both in different processes allows the operating system to assign different privileges to both.

  * It increases modularity: You can easily change one part of the software on your computer without disturbing the other parts.

  * If the computer has more than one CPU, computation can be sped up by running more than one process (or thread) in parallel.

To leverage these advantages effectively, different processes or applications need a mechanism for inter-process communication (IPC) that allows them to exchange information (and ensure synchronisation if needed).

One way to implement an IPC mechanism is by using the message passing paradigm. Entities in a message passing system communicate by exchanging messages with each other, which makes it a natural fit for object oriented languages, where the basic abstraction is the object.

The message passing paradigm is also used in Objective-C (actually Objective-C inherited it from Smalltalk), where you interact with objects by sending messages to them. E.g. the intended meaning of

     [alice greet];

would be sending the -greet message to the alice object, which is referred to as the receiver of the message. This idiom can be quite easily extended beyond the single process case, which the NeXT did by including the Distributed Objects system in the OpenStep specification that GNUstep implements. The message passing paradigm is also employed by D-Bus, and we will look at the similarities and differences of both systems in the following sections.

Distributed Objects
===================

The GNUstep Distributed Objects (DO) System is designed to go out of a programmer's way. Since ordinary (intra-process) usage Objective-C already has message passing semantics, Distributed Objects simply extends these semantics to objects in other processes.

This works by usage of the proxy design pattern. A proxy is a stand-in object that receives messages in lieu of another object and forwards them (most likely after processing them as it sees fit). In the case of Distributed Objects, the proxy will take the message that is being sent to the remote object, encode it a NSInvocation object and send a serialised version of the invocation to the remote process where it is invoked on the receiver it was initially intended for.

Establishing a connection to a remote object using DO is thus a simple three step process:

 1. Look up a process that exposes ('vends', in DO parlance) an object.

 2. Establish a communication channel to the process.

 3. Create a proxy object to send messages to the remote object.

Afterwards, the generated proxy can be used just like any in-process object.

Task 1. involves the NSPortNameServer class which can be used to obtain a communication endpoint (NSPort) to a service with a specific name:

     NSPort *sendPort = [[NSPortNameServer systemDefaultPortNameServer]
       portForName: @"MyService"];

Task 2. involves NSPort and NSConnection. While the former is concerned with the low-level details of encoding messages to a wire format, the latter manages sending messages over ports. A connection to the above MyService using the created sendPort could be obtained like this:

     NSConnection *c = [NSConnection connectionWithReceivePort: [NSPort port]
                                                      sendPort: sendPort];

Task 3. is done by calling -rootProxy on the NSConnection object. This will return an instance of NSDistantObject: A proxy that will use NSConnection and NSPort to forward messages to the remote object.

     id remoteObject = [c rootProxy];

The DO mode of operation has a few notable advantages:

  * Usual message passing semantics apply.

  * The native Objective-C type system is used in both processes. No type conversion is necessary.

  * New objects can be vended implicitly by returning them from the root proxy. New proxies will be created automatically for them.

  * DO can make intelligent decisions about the remote objects: If process A has vended object O to process B (yielding the proxy P(O)), and B  latter vends P(O) to A, A will not use P(P(O)), but its local reference to O.

It goes without saying that DO is pretty useful and GNUstep uses it in many places. It drives, for example, the services architecture, the pasteboard server, or the distributed notification system. For further information about DO, please consult the Objective-C GNUstep Base Programming Manual (../../Base/ProgrammingManual/manual_7.html). We will now turn our attention to the D-Bus IPC system.

D-Bus
=====

Distributed Objects has already been part of NeXT's OpenStep Specification, which appeared in 1994 and thus predates the D-Bus IPC system for quite some time.  But while DO is only useful in an Objective-C context, D-Bus was created to suit the needs of desktop environments such as KDE or GNOME, which use (among others) C or C++ as their core programming languages.

Message Busses
--------------

One core concept of D-Bus is that of the message bus. A standard desktop system that uses D-Bus usually has two active message buses, dubbed the well-known buses. One is the system bus, to which system-wide services connect, the other is the session bus which is started per user session and allows applications on the user's desktop to communicate.

The purpose of a bus, which is running as a separate process (the dbus-daemon), is to provide name-services to the connected applications and route messages between them.

Services
--------

A process that connects to a message bus is considered to be a service, even if it will not expose any object to the bus. A unique name, which starts with a colon (e.g. :1.1) and is required for message routing, will be assigned to every service by the bus. The service can also request further names from the bus. A text editor might, for example, want to request the name org.gnustep.TextEditor from the bus. These names are referred to as well-known names and usually utilise reverse-DNS notation.

These names can be subject to different assignment policies. A service can specify that it wants to be queued for a name that has already be assigned. It will then become the owner of the name when the last previous owner exits or releases the name. Alternatively, the service can request to replace an existing name, a feature that can be used to ensure that only one application of a specific type is running (as would be the case for, e.g., a screensaver).

Object Paths
------------

When using DO, the object graph vended by a service is generated implicitly: If a message send to a remote object returns another object, that object will implicitly be vended and wrapped in a proxy for use by the other process. D-Bus operates quite differently in that respect: Every object needs to be assigned a name that can be used by remote processes to interact with the object. These object names are organised in the directory-like structure, where each object is uniquely identified by its object path. The UDisks service (org.freedesktop.UDisks) on the system bus does, for example, expose different disks of a computer at different paths:

     /org/freedesktop/UDisks/devices/sda
     /org/freedesktop/UDisks/devices/sdb

It is worth noting that it is a D-Bus convention to have the root object of the service not reside at the root path (``/'') but at one that corresponds to the service name with all dots replaced by the path separator. Thus you don not access the root object of org.freedesktop.UDisks at ``/'' but at ``/org/freedesktop/UDisks''. The reason for this is to ensure proper name-spacing if different code modules in a single process have registered multiple names on the bus (which will all point to the same unique name).

Interfaces
----------

D-Bus object-path nodes are the receivers and senders of D-Bus messages. They receive calls to methods and emit signals, which are broadcast by the bus and can be watched for by other applications. These methods and signals can be aggregated into interfaces, which are a bit, but not quite, like Objective-C protocols. One interface that almost every D-Bus object implements is org.freedesktop.Introspectable, which has as its sole member the Introspect()-method. This will return XML-encoded information about all methods, signals, and properties the object exposes.

Interfaces are also used as namespaces for their members: Identically named methods with different implementations are allowed to appear in multiple interfaces, something that is not possible with Objective-C protocols.

Type System
-----------

For arguments and values of methods, signals, and properties, D-Bus defines its own type system, which is similar to the C type system. It contains integer and floating point types of different sizes as well as array and structure types. The type system represents dictionaries as arrays of ordered pairs. Additionally, there is a type available for references to objects (but these references are only valid within a single service) and a variant type that, just like Objective-C's id, allows for values of arbitrary types. This type system has to be adopted by any application that wants to interface with D-Bus.

Comparison
==========

Feature   Distributed Objects   D-Bus
IPC paradigm   message passing   message passing
type system   native Objective-C type system   custom D-Bus
type system (C-like)
supported programming languages   Objective-C (Please
note that the GNUstep and Apple implementations of Distributed Objects
are incompatible.)   many languages through bindings
polymorphism   no special provisions   through overloaded method names in
different interfaces
object-graph generation   implicit   explicit with named
objects
name service   provided by separate nameserver objects   integrated
delivery of broadcast information   distributed notification
system implemented on top of DO   integrated as D-Bus signals