Main Page DBusSharp

From NDesk

(Difference between revisions)
Jump to: navigation, search
Revision as of 00:56, 6 April 2007 (edit)
Alp (Talk | contribs)

← Previous diff		 Revision as of 10:40, 15 April 2007 (edit) (undo)
Alp (Talk | contribs)

Next diff →
Line 65: Line 65:
* [http://mono.dcsharp.com/ dcsharp] file sharing client using the Direct Connect protocol, for notifications, single instance and remote control * [http://mono.dcsharp.com/ dcsharp] file sharing client using the Direct Connect protocol, for notifications, single instance and remote control
* [http://dev.mmgsecurity.com/projects/lat/ LAT] LDAP Administration Tool * [http://dev.mmgsecurity.com/projects/lat/ LAT] LDAP Administration Tool
-* VMX Manager (Virtual Machine Manager), GNOME CVS+* [http://www.snorp.net/log/2006/12/08/im-in-ur-virtual-machines-managing-them/ VMX Manager], Virtual Machine Manager), GNOME CVS(?)
* GNOME [http://www.k-d-w.org/clipboard/NewStuffManager/ NewStuffManager], a plugin update/download service * GNOME [http://www.k-d-w.org/clipboard/NewStuffManager/ NewStuffManager], a plugin update/download service
* [http://folks.o-hand.com/iain/last-exit/ last-exit], a music player for Last.fm * [http://folks.o-hand.com/iain/last-exit/ last-exit], a music player for Last.fm

Revision as of 10:40, 15 April 2007

dbus-sharp is a C# implementation of D-Bus. It's often referred to as "managed D-Bus" to avoid confusion with existing bindings (which wrap libdbus).

D-Bus is an inter-process communication framework that lets applications interface with the system event bus as well as allowing them to talk to one another in a peer-to-peer configuration.

Contents

Status

This software is under development but is already used by a wide range of applications for tasks as simple as maintaining a single instance of the GUI to whole instant messaging frameworks and hardware detection APIs.

It provides a tested, high-performance bridge to and from all systems that are exposed via D-Bus, regardless of programming language, UI toolkit or license. The source code is MIT X11 licensed (Free Software/Open Source), allowing integration into other projects with very few restrictions.

The code is a clean-room implementation based on the D-Bus Specification Version 0.11 and study of the wire protocol of existing tools.

It aims for compatibility with Mono and Microsoft .NET frameworks supporting the 2.0 profile. Backward compatibility with 1.0 will not be a consideration. Ongoing work to ensure CLS compliance means that managed D-Bus can be used by any language that can target the CLR.

Cross platform support

Supported platforms

A standard build of managed D-Bus will work across a wide range of platforms:

  • x86
  • 64-bit (eg. AMD64)
  • Big endian (eg. PPC)
  • ARM (eg. Nokia 770)
  • Mono 1.1.13 or newer
  • GNU/Linux
  • FreeBSD
  • Mac OS X
  • Microsoft Windows / .NET runtime (in the 0.5 development branch)

Soon to be supported

Users

A few projects bundle the source code for managed D-Bus with their applications. This kind of arrangement can work if you're on good terms with someone who can maintain dbus-sharp, but ideally you should depend on stable releases.

Contact

Support can be found on the #managed-dbus IRC channel on irc.gnome.org

There is no mailing list or email contact address.

Bundling guidelines

"Bundling" involves including the sources for managed D-Bus in an application's source tree to avoid the external dependency.

  • Make sure the AssemblyInfo.cs files are included in the build
  • Make sure the libraries are not installed to the GAC
  • Make sure you include the same source files as used by the official Makefile and exclude other source code files that are not part of the build (eg. IntrospectionSchemas.cs and others)
  • Try to keep up to date with the latest stable releases -- stable releases contain minimal changes required to keep the libraries working well on a variety of ever-changing platforms
  • Try to provide a configure option allowing the application to be build against versions of the library in the GAC instead of the bundled versions

Packaging guidelines

  • Only package stable releases
  • Name the packages along the lines of "ndesk-dbus" and "ndesk-dbus-glib" rather than "dbus-sharp" -- the source package name will soon be changed to reflect this
  • If in doubt, follow the conventions set by the Debian packages

As a dependency

This documentation does not yet apply but will become relevant when the libraries become installable.

To determine CSFLAGS to pass to your C# compiler: 

pkg-config --libs ndesk-dbus-1.0 ndesk-dbus-glib-1.0

or with gmcs: 

gmcs -pkg:ndesk-dbus-1.0 -pkg:ndesk-dbus-glib-1.0 ...

To determine where .service files should be installed: 

pkg-config --define-variable=prefix=$prefix --variable=session_bus_services_dir ndesk-dbus-1.0

or 

pkg-config --define-variable=datadir=$datadir --variable=session_bus_services_dir ndesk-dbus-1.0

Download

See the managed D-Bus release archive.

0.4.x is the stable branch, while 0.5.x features ongoing performance, portability and thread safety work.

dbus-sharp-glib 0.3 is the current stable release for GLib integration.

2007-03-12

This is a stable release with backported fixes. See dbus-sharp-0.4.y for patch details. All users are advised to upgrade, as previous releases depend on buggy Mono behaviour that was recently fixed and may cease to function correctly.

Important patches:

  • Avoid recursing interfaces: Prevents handlers from being hooked up twice in certain corner cases and fixes introspection output in those same cases
  • Workaround for Mono bug #81035 (memory leak)
  • Workaround for old Mono: Don't use SortedDictionary: This fixes the build with older Mono releases
  • Various minor correctness fixes to make sure this will build and work well on newer Mono releases when they become available

2007-03-07

This release enables faster compiled write marshalers and a workaround for a small memory leak in Mono bug #81035. Applications bunding managed D-Bus need not upgrade to this release. There will shortly be a 0.4 series release with the most important changes backported.

0.5 also features Makefile and code fixes for MS .NET. There is still one issue that prevents it from working out of the box due to CAS security. This issue will be addressed in soon.

2007-02-20

New source files: MatchRule.cs

Fixes:

  • Exported properties now work (they could only be imported before). Note that this has nothing to do with the org.freedesktop.DBus.Properties interface.
  • Objects can now be unregistered. Unregister was before just a no-op.
  • Compiled proxy methods/marshalers for incoming signals are now cached, so registering many objects of the same type should not leak or have much overhead.
  • Optimization for incoming byte arrays.
  • More robust match rule logic.

The unregistration support and working exported properties makes this the first feature-complete release.

There is no urgent need to upgrade 0.4 bundled with applications unless you need the new features.

2007-02-05

"make install" does not yet work out of the box, but assemblies are strongly named. Distributors may optionally ship this package if they complete the installation manually. Bundling is still recommended with this release.

Both APIs are both cleaned up to only expose API that is meant to be public.

Notable dbus-sharp fixes include a fix that makes event exporting through interfaces work (noticed by the Muine team). Methods can now be overloaded in both imported and exported interfaces based on parameters, and method selection on multiple exported interfaces by a single object is improved. This fix also provides a slight performance boost.

dbus-sharp-glib was fixed to avoid a spontaneous exception when the bus is unexpectedly disconnected.

If you are bundling the code, you should not use ndesk.snk or define STRONG_NAME.

For your exported D-Bus service to be properly activatable, you should register objects _before_ requesting names or making any other calls. To make sure your program can be activated, make sure it's not running and that the service file is installed. Then run this, substituting $bus_name to your service's name eg. org.gnome.Banshee: 

dbus-send --print-reply=literal --dest=$bus_name / org.freedesktop.DBus.Introspectable.Introspect

The program should start, and the introspection data should contain a dump of the main application object rather than an empty node tag.

0.3.1

FreeBSD support introduced in 0.3 broke 64-bit Linux. This point-release provides a fix.

It also provides minor cleanups and the ability to parse more complex object trees as variants.

Notes to integrators:

  • The DType enumeration will soon become internal although it is not changed in this release. Please remove use of this enum in your code or make your own copy. Keep in mind that's there's no sensible reason for applications to use DType or something similar because other message parsing machinery in managed D-Bus is not public, and that D-Bus has a recursive type system, so the enum should have been called DToken or similar anyway.
  • Remember to run your application with DBUS_VERBOSE=1 when testing. Some of the warnings may indicate serious bugs in your interfaces, particularly the "expected signature mismatch" warning. Some of these warnings will become hard exceptions in future releases, while others are usually harmless (such as the missing handler warnings). If in doubt, ask on the IRC channel.

0.3

Official release notes

Notes to integrators:

  • API change: The NameReply enum is now RequestNameReply
  • New files: UnixTransport.cs, SocketTransport.cs should be included when bundling the code
  • As always, UnixMonoTransport.cs and IntrospectionSchemas.cs should not be included unless you have specific needs
  • If you use dbus-sharp-glib, you must upgrade to the latest release
  • the -unsafe gmcs/csc compiler flag has been required since 0.2

0.2

Support was added for reading non-native endian messages. ObjectPaths and Signatures were made more robust and several exception messages were improved. A complete list of changes is available in the version control system. There have been no changes in the high-level or the low-level public API in this release. dbus-sharp-glib remains stable at version 0.1.

0.1

This is an emergency release to provide a working alternative for applications stuck with the unmaintained dbus-sharp binding for libdbus. The API/ABI may change in future releases, and it hasn't been audited for security, which means that it shouldn't be used to provide services to an untrusted audience over TCP. However, a number of applications are successfully using this code base already. Event handlers must be manually removed (foo.MyEvent -= HandleMyEvent;) to avoid flooding the daemon with match rules. MarshalByRefObject may not be supported in future releases, so you should stick to using interfaces to define dbus API. Exceptions are not consistently mapped but should work both in exported and imported API.

Development

See the development roadmap for a detailed list of remaining tasks.

git-clone git://git.ndesk.org/pub/scm/dbus-sharp

The dbus-sharp API is not stable. In particular, please don't check this into your cvs/svn repository or bundle it with your program. And don't even think about installing it in the user's GAC or packaging it for your distribution yet.

There is also a module which provides GLib integration as an optional extra:

git-clone git://git.ndesk.org/pub/scm/dbus-sharp-glib

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