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.Since Can be used on any <interface>, <method>, <signal> and <property> element to specify the version (any free-form string but compared using a version-aware sort function) the element appeared in. When generating C code, this field is used to ensure function pointer order for preserving ABI/API. When generating Docbook XML, the value of this tag appears in the documentation. 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. --> ]]> Note that since can be used in any inline documentation bit (e.g. for interfaces, methods, signals and properties) to set the org.gtk.GDBus.Since annotation. 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