A Language for describing D-Bus interfaces

A long time ago, while working on D-Bus accessibility, I becamefrustrated with the existing methods for specifying the interfaces. D-Businterfaces are normally specified using an XML format. Although this formatdescribes the D-Bus protocol perfectly well, it is lacking lots ofinformation that would be useful for D-Bus bindings and for documentation.To deal with this the D-Bus wizards decided that the XML could be litteredwith ‘annotations’, to extend the format and number of standard annotationssprang up around specific D-Bus bindings: EggDBus,Telepathy and QtDBus.

These annotation formats are difficult to read and edit. XML is moderatelyacceptable, but some restrictions of D-Bus XML make keeping the documentconsistent vey hard. The fact that they are limited to specific D-Buslibraries is also not ideal. I started work on a language for describingD-Bus interfaces that would address these issues. My idea was to have areadable syntax, enough features to clearly document a D-Bus interface, andtools to generate XML or code for the different D-Bus libraries.

After a long hiatus dbuf is finally in a state where the language parser iscomplete, and generation of D-Bus XML is supported. The source can be foundat http://github.com/doffm/dbuf. There is adecent tutorial located in the doc folder, but a taste of what thelanguage is like follows. The code is part of a real example; the AT-SPID-Bus interface translated into dbuf.

using Attributes = org.freestandards.atspi.Attributes;
using Reference = org.freestandards.atspi.Reference;
/*  The base interface which is implemented by all  accessible objects.*/
interface org.freestandards.atspi.Accessible {    
  enum  Role { ROLE_INVALID = 0
                                            ROLE_ACCELERATOR_LABEL,
                                            ROLE_ALERT,
                                            ROLE_ANIMATION,
                                            ROLE_ARROW,
                                            ROLE_CALENDAR,
                                            ROLE_CANVAS,
                                            ROLE_CHECK_BOX,
                                            ROLE_CHECK_MENU_ITEM,
}
/*      Represents a bit-field of currently held states.      TODO Could just be a uint64?    */
typedef uint32[] State;
/* A short string representing the object's name. */    
read property string Name;
/*The accessible object which is this objects containing parent.*/
read property Reference Parent;
/*Access this objects non-hierarchical relationships to other accessible objects.*/
method GetRelationSet reply { RelationSet relations; } 
/*Get the Role indicating the type of UI role played by this object*/  
method GetRole reply { Role role; }
/* Access the states currently held by this object. */
method GetState reply { State state }
/* Get a properties applied to this object as a whole, as an set name-value pairs. As such these attributes may be considered weakly-typed properties or annotations, as      distinct from the strongly-typed interface instance data.*/
method GetAttributes reply { Attributes attributes;}}

There is lots more work to do with dbuf, but even in its current state Ithink it is a useful tool for describing complex D-Bus interfaces.

One thought on “A Language for describing D-Bus interfaces”

Comments are closed.