DBus Documentation

From NDesk

(Difference between revisions)

Revision as of 00:52, 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<Key,Value> 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.

Exceptions and error messages

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"

 == NDesk.DBus Documentation ==
-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. [http://git.ndesk.org/?p=dbus-sharp;a=blob;f=examples/TestExportInterface.cs TestExportInterface.cs] provides examples of exported and imported interfaces, methods and properties. [http://git.ndesk.org/?p=dbus-sharp-glib;a=blob;f=examples/TestUI.cs 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.
+This page is a work in progress as of early 2009. ''ndesk.org'' editors are invited to update and enhance it.
-NDesk.DBus maps all primitive CLR types as well as arrays, generic IDictionary<Key,Value> types and structs to their equivalent D-Bus types, while primitives boxed in System.Object are mapped to D-Bus variants. Managed events are mapped to D-Bus signals (keep in mind that the event delegate type's parameters must correspond directly to the D-Bus signal -- EventArgs parameters are not supported). All of these mappings are transparent and fully interoperable with other languages and platforms implementing the D-Bus specification.
+=== 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 [[DBus|Managed D-Bus]] page for source code tarball and repository details.
+<pre>
+using NDesk.DBus;
+</pre>
+=== Connecting to a D-Bus daemon ===
+=== Main loop ===
+[http://git.ndesk.org/?p=dbus-sharp-glib;a=blob;f=examples/TestUI.cs 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:
+<pre>
+  public static void Main ()
+  {
+    BusG.Init ();
+    Application.Init ();
+    ...
+  }
+</pre>
 === Interfaces ===
+[[DBus|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. [http://git.ndesk.org/?p=dbus-sharp;a=blob;f=examples/TestExportInterface.cs 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<Key,Value> 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 ===
-=== D-Bus Connections ===
+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.
-=== Main loop ===
+=== Exceptions and error messages ===
+=== 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 ===
+[http://git.ndesk.org/?p=dbus-sharp;a=tree;f=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.
-=== Examples ===
+There is a list of applications on the main [[DBus|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.