gdbus-codegen 1 User Commands gdbus-codegen GLib D-Bus code and documentation generator gdbus-codegen --interface-prefix org.project.Prefix --generate-c-code OUTFILES --c-namespace YourProject --c-generate-object-manager --generate-docbook OUTFILES --annotate element --key key --value key FILE FILE gdbus-codegen is used to generate code and/or documentation for one or more D-Bus interfaces. The tool reads D-Bus Introspection XML files and generates output files. The tool currently supports generating C code (via --generate-c-code) and Docbook XML (via --generate-docbook). When generating C code, an abstract #GTypeInterface-derived type is generated for each D-Bus interface. Additionally, for every generated type, FooBar, two concrete instantiable types, FooBarProxy and FooBarStub, implementing said interface are also generated. The former is derived from #GDBusProxy and intended for use on the client side while the latter is derived from the #GDBusInterfaceStub type making it easy to export on a #GDBusConnection either directly or via a #GDBusObjectManagerServer instance. Each generated Docbook XML file (see the --generate-docbook option for details) is a RefEntry article describing the D-Bus interface. The following options are supported: --interface-prefix org.project.Prefix. A prefix to strip from all D-Bus interface names when calculating the typename for the C binding and the Docbook sortas attribute. --generate-docbook OUTFILES Generate Docbook Documentation for each D-Bus interface and put it in OUTFILES-NAME.xml where NAME is a place-holder for the interface name, e.g. net.Corp.FooBar and so on. --generate-c-code OUTFILES Generate C code for all D-Bus interfaces and put it in OUTFILES.c and OUTFILES.h. --c-namespace YourProject The namespace to use for generated C code. This must be provided in CamelCase format. --c-generate-object-manager If this option is passed a #GDBusObjectManagerClient subclass with an appropriate #GDBusProxyTypeFunc is generated. --annotate Used together with --key and --value to annotate the given XML files. It can be used with interfaces, methods, signals, properties and arguments in the following way: The following D-Bus annotations are supported by gdbus-codegen: org.gtk.GDBus.Name Can be used on any <interface>, <method>, <signal> and <property> element to specify the name to use. For interfaces where this annotation is not specified, the name used is the D-Bus interface name stripped with the prefix given with --interface-prefix and with the dots removed and initial characters capitalized. For example the D-Bus interface com.acme.Coyote the name used is ComAcmeCoyote. For the D-Bus interface org.project.Bar.Frobnicator with --interface-prefix org.project., the name used is BarFrobnicator. For methods, signals and properties the name used is calculated by transforming NameGivenThisWay into name_given_this_way, e.g. roughly converting from camel-case to lower-case with underscores using certain heuristics. org.gtk.GDBus.C.ForceGVariant If set to a non-empty string, a #GVariant instance will be used instead of the natural C type. This annotation can be used on any <arg> and <property> element. org.gtk.GDBus.DocString A string with Docbook content for documentation. This annotation can be used on <interface>, <method>, <signal>, <property> and <arg> elements. org.gtk.GDBus.DocString.Short A string with Docbook content for short/brief documentation. This annotation can only be used on <interface> elements. As an easier alternative to using the org.gtk.GDBus.DocString annotation, note that XML parser used by gdbus-codegen parses XML comments in a way similar to gtk-doc: longer description. This is a new paragraph. --> ]]> For the org.gtk.GDBus.DocString annotation (and inline comments), note that substrings of the form #net.Corp.Bar, net.Corp.Bar.FooMethod(), #net.Corp.Bar::BarSignal and #net.Corp.InlineDocs:BazProperty are all expanded to links to the respective interface, method, signal and property. Consider the following D-Bus Introspection XML. ]]> If gdbus-codegen is used on this file like this: two files called myapp-generated.[ch] are generated. The files provide an abstract #GTypeInterface-derived type called MyAppFrobber as well as two instantiable types with the same name but suffixed with Proxy and Stub. The generated file, roughly, contains the following facilities: Thus, for every D-Bus method, there will be three C functions for calling the method, one #GObject signal for handling an incoming call and one C function for completing an incoming call. For every D-Bus signal, there's one #GObject signal and one C function for emitting it. For every D-Bus property, two C functions are generated (one setter, one getter) and one #GObject property. The following table summarizes the generated facilities and where they are applicable: Client Server Types Use MyAppFrobberProxy Any type implementing the MyAppFrobber interface Methods Use m_a_f_hello_world() to call. Receive via the handle_hello_world() signal handler. Complete the call with m_a_f_complete_hello_world() Signals Connect to the ::notification GObject signal. Use m_a_f_emit_notification() to emit signal. Properties (Reading) Use m_a_f_get_verbose() or :verbose. Implement #GObject's get_property() vfunc. Properties (writing) Use m_a_f_set_verbose() or :verbose. Implement #GObject's set_property() vfunc. You can use the generated proxy type with the generated constructors: Instead of using the generic #GDBusProxy facilities, one can use the generated methods such as my_app_frobber_call_hello_world() to invoke the net.Corp.MyApp.Frobber.HelloWorld() D-Bus method, connect to the the ::notification GObject signal to receive the net.Corp.MyApp.Frobber::Notication D-Bus signal and get/set the net.Corp.MyApp.Frobber:Verbose D-Bus Property using either the GObject property :verbose or the my_app_get_verbose() and my_app_set_verbose() methods. Use the standard #GObject::notify signal to listen to property changes. Note that all property access is via #GDBusProxy's property cache so no IO is ever done when reading properties. Also note that setting a property will cause the org.freedesktop.DBus.Properties.Set method to be called on the remote object. This call, however, is asynchronous so setting a property won't block. Further, the change is delayed and no error checking is possible. The generated MyAppFrobber interface is designed so it is easy to implement it in a #GObject subclass. For example, to handle HelloWorld() method invocations, set the vfunc for handle_hello_hello_world() in the MyAppFrobberIface structure. Similary, to handle the net.Corp.MyApp.Frobber:Verbose property override the :verbose #GObject property from the subclass. To emit a signal, use e.g. my_app_emit_signal() or g_signal_emit_by_name(). Instead of subclassing, it is often easier to use the generated MyAppFrobberStub subclass. To handle incoming method calls, use g_signal_connect() with the ::handle-* signals and instead of overriding #GObject's get_property() and set_property() vfuncs, use g_object_get() and g_object_set() or the generated property getters and setters (the generated class has an internal property bag implementation). To facility atomic changesets (multiple properties changing at the same time), #GObject::notify signals are queued up when received. The queue is drained in an idle handler and will cause emissions of the org.freedesktop.DBus.Properties::PropertiesChanged signal with all the properties that has changed. Use g_dbus_interface_stub_flush() or g_dbus_object_stub_flush() to empty the queue immediately. Scalar types (type-strings 'b', 'y', 'n', 'q', 'i', 'u', 'x', 't', 'h' and 'd') ), strings (type-strings 's', 'ay', 'o' and 'g') and arrays of string (type-strings 'as' and 'aay') are mapped to the natural types, e.g. #gboolean, #gdouble, #gint, gchar*, gchar** and so on. Everything else is mapped to the #GVariant type. This automatic mapping can be turned off by using the annotation org.gtk.GDBus.C.ForceGVariant - if used then a #GVariant is always exchanged instead of the corresponding native C type. This annotation may be convenient to use when using bytestrings (type-string 'ay') for data that could have embedded NUL bytes. No guarantees about the API and ABI of the code generated by gdbus-codegen are given. This means that code generated by future versions of this program may have a different API or ABI even if the underlying D-Bus interface hasn't changed. As such, always include the generated code in distribution tarballs and never expose the code in any stable interfaces. Future versions of gdbus-codegen will provide ABI and API guarantees on the generated code. Written by David Zeuthen zeuthen(at)gmail.com with a lot of help from many others. Please send bug reports to either the distribution bug tracker or the upstream bug tracker at . gdbus1