D-BUS and D-BUS CIDL

This is the main web site for my contributions involving D-BUS, especially D-BUS CIDL. This page is intended for software developers who are using D-BUS.

"CIDL" ("CORBA-like IDL"), pronounced "sid--el", is an interface definition language (IDL) for D-BUS. If you're developing software that other programs can contact using D-BUS, you can define your software interfaces in CIDL, which is intended to be easier for developers of those other programs to read and debug. The program dbus-cidl is a filter program that takes files in CIDL format and generates the equivalent D-BUS XML introspection format. CIDL and dbus-cidl were first inflicted on the world on Feb 5, 2005 and this webpage providing their updates was first posted on Feb 15, 2005. You're welcome to use this material; the program dbus-cidl is released under the same terms as D-BUS itself (GPL 2 or more, or AFL 1.1 or more).

I'll claim that CIDL is the "sample format" used in the D-BUS specification, with some extensions to handle more of its XML Introspection format. The dbus-cidl program should run nearly everywhere; it's implemented in the widely-available combination of flex/lex, bison/yacc, and C, and the only library it uses is glib.

Here's a trivial example; you could place in a file a small test interface definition like this:

  interface test1 {
    void x(in int a, out int b);
    attribute int px;
   };
You could then pass that through dbus-cidl to produce this:
 <!DOCTYPE node PUBLIC "-//freedesktop//DTD D-BUS Object Introspection 1.0//EN"
 "http://www.freedesktop.org/standards/dbus/1.0/introspect.dtd">
 <interface name="test1">
    <method name="x">
      <arg name="a" type="int" direction="in"/>
      <arg name="b" type="int" direction="out"/>
    </method>
    <property name="px" type="int" access="readwrite"/>
 </interface>

For a real-life example, look at the D-BUS specification (version 0.11) expressed in CIDL, and then look at the XML generated by dbus-cidl. For another example, see test.cidl. I find the CIDL specification much easier to read than the generated XML; the XML is much longer and makes it harder to see the "big picture". It's my hope that CIDL will make it easier for software developers to express their programs' interfaces to D-BUS.

If you want to try out the program dbus-cidl, just download the dbus-cidl.l (lex/flex spec), dbus-cidl.y (yacc/bison spec), and the trivial makefile. Feel free to try out the test file test.cidl.

The format of CIDL is defined in dbus-cidl.y. Here's the summary; you need to pass dbus-cidl a "specification", which is defined as follows in this BNF (which uses as many of the same CORBA spec nonterminal names as was reasonable to do):

 specification = definition+
 definition = interface_spec
 interface_spec = [ "deprecated" ] "interface" IDENTIFIER "{"
                  ( op_dcl | attr_dcl | signal_dcl )* "}" ";"
 attr_dcl = [ "read" | "write" ] ( "property" | "attribute" )
             param_type_spec IDENTIFIER ( "," IDENTIFIER )* ";"
 op_dcl: [ "oneway" ] op_type_spec IDENTIFIER '(' parameter_list ')' ";"
 parameter_list = [ param_dcl ( "," param_dcl )* ]
 param_dcl = [ "in" | "out" | "inout" ] param_type_spec IDENTIFIER
 signal_dcl = "signal" IDENTIFIER "(" out_parameter_list ")" ";"
 out_parameter_list = [ out_param_dcl ( "," out_parameter_dcl )* ]
 out_param_dcl:  param_type_spec IDENTIFIER
 param_type_spec:  IDENTIFIER  // INT32, STRING, etc.
                   | "array" "of" param_type_spec

I don't know if I'll do anything more with this. This was an experiment, in part to see if there were any critical pieces of CORBA that were missing in D-BUS. If the D-BUS developers want to include this code in the D-BUS distribution, I'd be delighted. If no one picks this up, then it's still done its job, since I've been able to examine the specification in a better way by having to write a program (I find that if I write a program to handle something, I end up learning a lot about it). But if someone DOES pick this work up, then great!