DBus Documentation

From NDesk

(Difference between revisions)

Revision as of 02:29, 30 January 2009

1 NDesk.DBus Documentation

NDesk.DBus Documentation

This page is a work in progress as of early 2009. ndesk.org editors are invited to update and enhance it.

Getting started

Managed D-Bus exists in the NDesk.DBus namespace. It requires a 2.0 or later CLR implementation due to extensive use of generics. D-Bus is typically used in Unix-like desktop environments and is included in Linux distributions. See the main Managed D-Bus page for source code tarball and repository details.

using NDesk.DBus;

Connecting to a D-Bus daemon

Main loop

TestUI.cs demonstrates how the additional NDesk.DBus.GLib library can be used to provide main loop integration with GLib and GTK+ applications. Main loop integration is essential for anything but the simplest uses of D-Bus. Alternatively, message processing can be driven using NDesk.DBus.Connection.Iterate () and related methods.

NDesk.DBus.GLib provides a single static method for hooking NDesk.DBus to the GLib main loop. This method should be called early within the lifetime of the application:

  public static void Main ()
  {
    BusG.Init ();
    Application.Init ();
    ...
  }

Interfaces

Managed D-Bus exports and imports objects implementing interfaces marked with the NDesk.DBus.Interface attribute. This allows developers to either extend existing code with inter-process and network transparency or develop new code to proxy the state of the application. TestExportInterface.cs provides examples of exported and imported interfaces, methods and properties.

NDesk.DBus maps all primitive CLR types as well as arrays, generic IDictionary<TKey,TValue> types and structs to their equivalent D-Bus types, while primitives boxed in System.Object are mapped to D-Bus variants. All of these mappings are transparent and fully interoperable with other languages and platforms implementing the D-Bus specification.

Signals / Events

Managed events are mapped to D-Bus signals. The event delegate type's parameters must correspond directly to the D-Bus signal -- this means that System.EventHandler / System.EventArgs parameters are not supported.

Properties

Managed properties are mapped to D-Bus properties. This mapping was/is(?) not standardized by the specification.

The convention used is to map properties to Get/Set method calls. The org.freedesktop.DBus.Properties interface is not supported automatically but a managed interface description is available for developers wishing to support this interface explicitly (org.freedesktop.DBus.Properties in NDesk.DBus).

Object paths

Introspection

Knowledge of D-Bus introspection is not necessary to use managed D-Bus, however we will describe here how managed D-Bus supports introspection internally.

Exported managed objects implicitly support D-Bus introspection. Managed D-Bus does not make use of introspection data for imported objects but instead relies on the managed interface descriptions which must accurately represent the remote interface (with the exception that the managed interfaces need only cover the methods, properties and events that are desired for use in the application).

Exceptions and error messages

When calling a remote method, if the method call returns a D-Bus error message instead of a reply, the error will be mapped to a managed exception which is raised and can be caught or allowed to halt execution of the application as with any exception. Similarly, exceptions thrown by exported methods will be mapped to a D-Bus error message which is sent to the caller. In both cases, exception handling is supported as part of the core D-Bus mapping, thus message handling can continue without interruption during and after the exception.

Note however that managed D-Bus exceptions do not round-trip in the current implementation. That is to say, if you throw a FooException on one end, it will be raised as a System.Exception on the calling end. The exception message may or may not contain an indication as to the name of the original exception which may still be helpful to developers who really need this information.

Multi-threaded use

NDesk.DBus is fully thread-safe. Incoming method calls and signals are raised on the main UI thread and main loop. Outgoing method calls receive their replies as expected on the calling thread without blocking the main loop and without blocking any other pending calls. This is currently the primary technique for making asynchronous method calls.

Further examples

Examples in the source code repository. Note that some of these examples are intentionally complex or obtuse to test corner cases in the implementation -- you don't need to do things exactly the same way in your application.

There is a list of applications on the main Managed D-Bus page, many of which are open source. Keep in mind that some of these applications use managed D-Bus in slightly awkward ways, either because the code was ported from older, obsolete D-Bus libraries or because they were developed for very old versions of the library.

Retrieved from "http://ndesk.org/DBus_Documentation"

 Managed events are mapped to D-Bus signals. The event delegate type's parameters must correspond directly to the D-Bus signal -- this means that System.EventHandler / System.EventArgs parameters are ''not'' supported.
+=== Properties ===
+Managed properties are mapped to D-Bus properties. This mapping was/is(?) not standardized by the specification.
+The convention used is to map properties to Get/Set method calls. The ''org.freedesktop.DBus.Properties'' interface is ''not supported'' automatically but a managed interface description is available for developers wishing to support this interface explicitly (''org.freedesktop.DBus.Properties'' in NDesk.DBus).
+=== Object paths ===
+=== Introspection ===
+Knowledge of D-Bus introspection is not necessary to use managed D-Bus, however we will describe here how managed D-Bus supports introspection internally.
+Exported managed objects implicitly support D-Bus introspection. Managed D-Bus does not make use of introspection data for imported objects but instead relies on the managed interface descriptions which must accurately represent the remote interface (with the exception that the managed interfaces need only cover the methods, properties and events that are desired for use in the application).
 === Exceptions and error messages ===