mono/README

   1 D-BUS Mono Bindings
   2 ===
   3
   4 These bindings are a 'thick' wrapper around the D-BUS API. For now
   5 they rely on the main loop provided by the GLib bindings but this
   6 dependancy will be removed in the near future.
   7
   8 The wrapper serves two main functions: firstly, it has the know-how to
   9 introspect live objects passed to it by a server and service requests
  10 to those objects via the D-BUS. Secondly, it can create a proxy for
  11 clients who can pretend they are making calls to the regular
  12 objects. This latter piece of magic is implemented using
  13 Reflection.Emit to create an assembly on-the-fly containing
  14 sub-classes of the classes the client thinks it's really using. These
  15 sub-classes simply marshal each method's parameters off to the D-BUS,
  16 demarshal the results and return them to the client as if nothing
  17 happened.
  18
  19 Usage
  20 ===
  21
  22 A server do should something like this:
  23
  24         namespace Foo
  25         {
  26         using System;
  27         using DBus;
  28         using Gtk;
  29
  30         public class MyServer
  31         {
  32         public static int Main(string [] args)
  33         {
  34                 Application.Init();
  35
  36 1               Connection connection = Bus.GetSessionBus();
  37 2               Service service = new Service(connection, "org.foo");
  38 3               MyObject myObject = new MyObject();
  39 4               service.RegisterObject(myObject, "/org/foo/MyObject");
  40
  41                 Application.Run();
  42
  43                 return 0;
  44         }
  45         }
  46         }
  47
  48 In line 1 we get a connection to the session bus. Then, in line 2 we
  49 create a service which will listen for requests to org.foo to
  50 service. In line 3 we create a MyObject object and register it with an
  51 object path in line 4. It's almost that simple. All that's missing is
  52 to mark MyObject in such a way that dbus-sharp knows how to export
  53 it. This is done using the attributes, Interface and Method,
  54 as in the following example:
  55
  56         namespace Foo
  57         {
  58         using System;
  59         using DBus;
  60
  61         [Interface("org.foo.MyObject")]
  62         public class MyObject
  63         {
  64         [Method]
  65         public virtual string Echo(string message)
  66         {
  67                 return "Reply: " + message;
  68         }
  69         }
  70         }
  71
  72 Note that the Methods should also be declared virtual in order for
  73 the client to use same class declaration.
  74
  75 Now for the client:
  76
  77         namespace Foo
  78         {
  79         using System;
  80         using DBus;
  81
  82         public class MyClient
  83         {
  84         public static int Main(string [] args)
  85         {
  86 1               Connection connection = Bus.GetSessionBus();
  87 2               Service service = Service.Get(connection, "org.foo");
  88 3               MyObject myObject = (MyObject)
  89                    service.GetObject(typeof(MyObject), "/org/foo/MyObject");
  90 4               System.Console.WriteLine(testObject.Echo("Hello world!"));
  91
  92                 return 0;
  93         }
  94         }
  95         }
  96
  97 Here we start off the same by getting a connection to the session
  98 bus. This time though, in line 2, we get the existing service rather
  99 than creating it. In line 3, we ask the service to get the object
 100 "/org/foo/MyObject" as registered by the server and that return it as
 101 a MyObject. Once obtained we can use it like any normal object as in
 102 line 4. This supposes, of course, that you've just written MyObject
 103 and happen to have it readily available. If that were not the case,
 104 for example if you wanted to call a method on one of the well-known
 105 services, then you will need to write a stub class, like the MyObject
 106 class above, which has the method calls you need correctly defined but
 107 needn't actually have any implementation.
 108
 109
 110 Working Example
 111 ===
 112
 113 The example directory contains a working example similar to that
 114 described above. It uses the session bus so first run dbus-launch and
 115 then export DBUS_SESSION_BUS_ADDRESS, as displayed by dbus-launch, to
 116 two terminals, one to run the server and one for the client. Then,
 117 start the server in one terminal, the client in the other and cross
 118 your fingers.