Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
GDBUS-CODEGEN(1)		 User Commands		      GDBUS-CODEGEN(1)

       gdbus-codegen - D-Bus code and documentation generator

       gdbus-codegen [-h, --help] [--interface-prefix org.project.Prefix]
		     [--generate-c-code	OUTFILES] [--c-namespace YourProject]
		     [--c-generate-autocleanup none|objects|all]
		     [--output-directory OUTDIR] [--generate-docbook OUTFILES]
		     [--pragma-once] [--xml-files FILE]	[--header] [--body]
		     [--output OUTFILE]	[--annotate ELEMENT KEY	VALUE]...
		     FILE [FILE...]

       gdbus-codegen is	used to	generate code and/or documentation for one or
       more D-Bus interfaces.

       gdbus-codegen reads D-Bus Introspection XML[1] from files passed	as
       additional arguments on the command line	and generates output files. It
       currently supports generating C source code (via	--body)	or header (via
       --header) and Docbook XML (via --generate-docbook).

       When generating C code, a #GInterface -derived type is generated	for
       each D-Bus interface. Additionally, for every generated type, FooBar,
       two concrete instantiable types,	FooBarProxy and	FooBarSkeleton,
       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 #GDBusInterfaceSkeleton type making it easy
       to export on a #GDBusConnection either directly or via a
       #GDBusObjectManagerServer instance.

       For C code generation either --body that	generates source code, or
       --header	that generates headers,	can be used. These options must	be
       used along with --output, which is used to specify the file to output

       Both files can be generated at the same time by using
       --generate-c-code, but this option is deprecated. In this case --output
       cannot be used due to the generation of multiple	files. Instead pass
       --output-directory to specify the directory to put the output files in.
       By default the current directory	will be	used.

       The name	of each	generated C type is derived from the D-Bus interface
       name stripped with the prefix given with	--interface-prefix and with
       the dots	removed	and initial characters capitalized. For	example, for
       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, if not specified, the name
       defaults	to the name of the method, signal or property.

       Two forms of the	name are used -	the CamelCase form and the lower-case
       form. The CamelCase form	is used	for the	#GType and struct name,	while
       lower-case form is used in function names. The lower-case form is
       calculated by converting	from CamelCase to lower-case and inserting
       underscores at word boundaries (using certain heuristics).

       If the value given by the org.gtk.GDBus.C.Name annotation or the
       --c-namespace option contains an	underscore (sometimes called
       Ugly_Case), then	the camel-case name is derived by removing all
       underscores, and	the lower-case name is derived by lower-casing the
       string. This is useful in some situations where abbreviations are used.
       For example, if the annotation is used on the interface
       net.MyCorp.MyApp.iSCSITarget with the value iSCSI_Target	the CamelCase
       form is iSCSITarget while the lower-case	form is	iscsi_target. If the
       annotation is used on the method	EjectTheiPod with the value
       Eject_The_iPod, the lower-case form is eject_the_ipod.

       Each generated Docbook XML file (see the	--generate-docbook option for
       details)	is a RefEntry[2] article describing the	D-Bus interface.

       The following options are supported:

       -h, --help
	   Show	help and exit.

       --xml-files FILE
	   This	option is deprecated; use positional arguments instead.	The
	   D-Bus introspection XML file.

       --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[3].

       --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.

	   Pass	--output-directory to specify the directory to put the output
	   files in. By	default	the current directory will be used.

       --generate-c-code OUTFILES
	   Generate C code for all D-Bus interfaces and	put it in OUTFILES.c
	   and OUTFILES.h including any	sub-directories. If you	want the files
	   to be output	in a different location	use --output-directory as
	   OUTFILES.h including	sub-directories	will be	referenced from

	   The full paths would	then be	$(OUTDIR)/$(dirname
	   $OUTFILES)/$(basename $OUTFILES).{c,h}.

       --c-namespace YourProject
	   The namespace to use	for generated C	code. This is expected to be
	   in CamelCase[4] or Ugly_Case	(see above).

	   If this option is passed, the #pragma once[5] preprocessor
	   directive is	used instead of	include	guards.

	   If this option is passed, suitable #GDBusObject, #GDBusObjectProxy,
	   #GDBusObjectSkeleton	and #GDBusObjectManagerClient subclasses are

       --c-generate-autocleanup	none|objects|all
	   This	option influences what types autocleanup functions are
	   generated for. 'none' means to not generate any autocleanup
	   functions. 'objects'	means to generate them for object types, and
	   'all' means to generate them	for object types and interfaces. The
	   default is 'objects'	due to a corner	case in	backwards
	   compatibility with a	few projects, but you should likely switch
	   your	project	to use 'all'. This option was added in GLib 2.50.

       --output-directory OUTDIR
	   Directory to	output generated source	to. Equivalent to changing
	   directory before generation.

	   This	option cannot be used with neither --body nor --header,	and
	   --output must be used.

	   If this option is passed, it	will generate the header code and
	   write it to the disk	by using the path and file name	provided by

	   Using --generate-c-code, --generate-docbook or --output-directory
	   are not allowed to be used along with --header and --body options,
	   because these options are used to generate only one file.

	   If this option is passed, it	will generate the source code and
	   write it to the disk	by using the path and file name	provided by

	   Using --generate-c-code, --generate-docbook or --output-directory
	   are not allowed to be used along with --header and --body options,
	   because these options are used to generate only one file.

       --output	OUTFILE
	   The full path where the header (--header) or	the source code
	   (--body) will be written, using the path and	filename provided by
	   --output. The full path could be something like $($OUTFILE).{c,h}.

	   Using --generate-c-code, --generate-docbook or --output-directory
	   is not allowed along	with --output, because the latter is used to
	   generate only one file.

       --annotate ELEMENT KEY VALUE
	   Used	to inject D-Bus	annotations into the given XML files. It can
	   be used with	interfaces, methods, signals, properties and arguments
	   in the following way:

	       gdbus-codegen --c-namespace MyApp			   \
		 --generate-c-code myapp-generated			   \
		 --annotate "org.project.InterfaceName"			   \
		   org.gtk.GDBus.C.Name	MyFrobnicator			   \
		 --annotate "org.project.InterfaceName:Property"	   \
		   bar bat						   \
		 --annotate "org.project.InterfaceName.Method()"	   \
		   org.freedesktop.DBus.Deprecated true			   \
		 --annotate "org.project.InterfaceName.Method()[arg_name]" \
		   snake hiss						   \
		 --annotate "org.project.InterfaceName::Signal"		   \
		   cat meow						   \
		 --annotate "org.project.InterfaceName::Signal[arg_name]"  \
		   dog wuff						   \
	   Any UTF-8 string can	be used	for KEY	and VALUE.

       The following D-Bus annotations are supported by	gdbus-codegen:

	   Can be used on any <interface>, <method>, <signal> and <property>
	   element to specify that the element is deprecated if	its value is
	   true. Note that this	annotation is defined in the D-Bus
	   specification[1] and	can only assume	the values true	and false. In
	   particular, you cannot specify the version that the element was
	   deprecated in nor any helpful deprecation message. Such information
	   should be added to the element documentation	instead.

	   When	generating C code, this	annotation is used to add
	   #G_GNUC_DEPRECATED to generated functions for the element.

	   When	generating Docbook XML,	a deprecation warning will appear
	   along the documentation for the element.

	   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, see the section called

	   When	generating Docbook XML,	the value of this tag appears in the

	   A string with Docbook content for documentation. This annotation
	   can be used on <interface>, <method>, <signal>, <property> and
	   <arg> elements.

	   A string with Docbook content for short/brief documentation.	This
	   annotation can only be used on <interface> elements.

	   Can be used on any <interface>, <method>, <signal> and <property>
	   element to specify the name to use when generating C	code. The
	   value is expected to	be in CamelCase[4] or Ugly_Case	(see above).

	   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.

	   If set to a non-empty string, the generated code will include
	   parameters to exchange file descriptors using the #GUnixFDList
	   type. This annotation can be	used on	<method> elements.

       As an easier alternative	to using the org.gtk.GDBus.DocString
       annotation, note	that parser used by gdbus-codegen parses XML comments
       in a way	similar	to gtk-doc[6]:

       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. Additionally,
       substrings starting with	@ and %	characters are rendered	as
       parameter[7] and	constant[8] respectively.

       If both XML comments and	org.gtk.GDBus.DocString	or
       org.gtk.GDBus.DocString.Short annotations are present, the latter wins.

       Consider	the following D-Bus Introspection XML.

	     <interface	name="net.Corp.MyApp.Frobber">
	       <method name="HelloWorld">
		 <arg name="greeting" direction="in" type="s"/>
		 <arg name="response" direction="out" type="s"/>

	       <signal name="Notification">
		 <arg name="icon_blob" type="ay"/>
		 <arg name="height" type="i"/>
		 <arg name="messages" type="as"/>

	       <property name="Verbose"	type="b" access="readwrite"/>

       If gdbus-codegen	is used	on this	file like this:

	   gdbus-codegen --generate-c-code myapp-generated	 \
			 --c-namespace MyApp			 \
			 --interface-prefix net.corp.MyApp.	 \

       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 Skeleton. The generated file, roughly, contains the following

	   /* GType macros for the three generated types */
	   #define MY_APP_TYPE_FROBBER (my_app_frobber_get_type	())
	   #define MY_APP_TYPE_FROBBER_SKELETON	(my_app_frobber_skeleton_get_type ())
	   #define MY_APP_TYPE_FROBBER_PROXY (my_app_frobber_proxy_get_type ())

	   typedef struct _MyAppFrobber	MyAppFrobber; /* Dummy typedef */

	   typedef struct
	     GTypeInterface parent_iface;

	     /*	Signal handler for the ::notification signal */
	     void (*notification) (MyAppFrobber	*proxy,
				   GVariant *icon_blob,
				   gint	height,
				   const gchar*	const *messages);

	     /*	Signal handler for the ::handle-hello-world signal */
	     gboolean (*handle_hello_world) (MyAppFrobber *proxy,
					     GDBusMethodInvocation *invocation,
					     const gchar *greeting);
	   } MyAppFrobberIface;

	   /* Asynchronously calls HelloWorld()	*/
	   my_app_frobber_call_hello_world (MyAppFrobber *proxy,
					    const gchar	*greeting,
					    GCancellable *cancellable,
					    GAsyncReadyCallback	callback,
					    gpointer user_data);
	   my_app_frobber_call_hello_world_finish (MyAppFrobber	*proxy,
						   gchar **out_response,
						   GAsyncResult	*res,
						   GError **error);

	   /* Synchronously calls HelloWorld().	Blocks calling thread. */
	   my_app_frobber_call_hello_world_sync	(MyAppFrobber *proxy,
						 const gchar *greeting,
						 gchar **out_response,
						 GCancellable *cancellable,
						 GError	**error);

	   /* Completes	handling the HelloWorld() method call */
	   my_app_frobber_complete_hello_world (MyAppFrobber *object,
						GDBusMethodInvocation *invocation,
						const gchar *response);

	   /* Emits the	::notification signal /	Notification() D-Bus signal */
	   my_app_frobber_emit_notification (MyAppFrobber *object,
					     GVariant *icon_blob,
					     gint height,
					     const gchar* const	*messages);

	   /* Gets the :verbose	GObject	property / Verbose D-Bus property.
	    * Does no blocking I/O.
	   gboolean my_app_frobber_get_verbose (MyAppFrobber *object);

	   /* Sets the :verbose	GObject	property / Verbose D-Bus property.
	    * Does no blocking I/O.
	   void	my_app_frobber_set_verbose (MyAppFrobber *object,
					    gboolean	  value);

	   /* Gets the interface info */
	   GDBusInterfaceInfo *my_app_frobber_interface_info (void);

	   /* Creates a	new skeleton object, ready to be exported */
	   MyAppFrobber	*my_app_frobber_skeleton_new (void);

	   /* Client-side proxy	constructors.
	    * Additionally, _new_for_bus(), _new_for_bus_finish() and
	    * _new_for_bus_sync() proxy	constructors are also generated.
	   my_app_frobber_proxy_new	   (GDBusConnection	*connection,
					    GDBusProxyFlags	 flags,
					    const gchar		*name,
					    const gchar		*object_path,
					    GCancellable	*cancellable,
					    GAsyncReadyCallback	 callback,
					    gpointer		 user_data);
	   MyAppFrobber	*
	   my_app_frobber_proxy_new_finish (GAsyncResult	*res,
					    GError	       **error);
	   MyAppFrobber	*
	   my_app_frobber_proxy_new_sync   (GDBusConnection	*connection,
					    GDBusProxyFlags	 flags,
					    const gchar		*name,
					    const gchar		*object_path,
					    GCancellable	*cancellable,
					    GError	       **error);

       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		 | Any type			|
       |	   | MyAppFrobberProxy	 | implementing	the		|
       |	   |			 | MyAppFrobber			|
       |	   |			 | interface			|
       |Methods	   | Use		 | Receive via the		|
       |	   | m_a_f_hello_world() | handle_hello_world()		|
       |	   | to	call.		 | signal handler.		|
       |	   |			 | Complete the	call		|
       |	   |			 | with				|
       |	   |			 | m_a_f_complete_hello_world()	|
       |Signals	   | Connect to	the	 | Use				|
       |	   | ::notification	 | m_a_f_emit_notification() to	|
       |	   | GObject signal.	 | emit	signal.			|
       |Properties | Use		 | Implement #GObject's		|
       |(Reading)  | m_a_f_get_verbose() | get_property() vfunc.	|
       |	   | or	:verbose.	 |				|
       |Properties | Use		 | Implement #GObject's		|
       |(writing)  | m_a_f_set_verbose() | set_property() vfunc.	|
       |	   | or	:verbose.	 |				|

   Client-side usage
       You can use the generated proxy type with the generated constructors:

	       MyAppFrobber *proxy;
	       GError *error;

	       error = NULL;
	       proxy = my_app_frobber_proxy_new_for_bus_sync (
			   "net.Corp.MyApp",		  /* bus name */
			   "/net/Corp/MyApp/SomeFrobber", /* object */
			   NULL,			  /* GCancellable* */
	       /* do stuff with	proxy */
	       g_object_unref (proxy);

       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
       ::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

       Note that all property access is	via #GDBusProxy	's property cache so
       no I/O is ever done when	reading	properties. Also note that setting a
       property	will cause the org.freedesktop.DBus.Properties.Set[9] 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.

   Server-side usage
       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
       MyAppFrobberSkeleton 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

	   static gboolean
	   on_handle_hello_world (MyAppFrobber		 *interface,
				  GDBusMethodInvocation	 *invocation,
				  const	gchar		 *greeting,
				  gpointer		  user_data)
	     if	(g_strcmp0 (greeting, "Boo") !=	0)
		 gchar *response;
		 response = g_strdup_printf ("Word! You	said `%s'.", greeting);
		 my_app_complete_hello_world (interface, invocation, response);
		 g_free	(response);
		 g_dbus_method_invocation_return_error (invocation,
			    "Hey, %s, there will be no whining!",
			    g_dbus_method_invocation_get_sender	(invocation));
	     return TRUE;


	     interface = my_app_frobber_skeleton_new ();
	     my_app_frobber_set_verbose	(interface, TRUE);

	     g_signal_connect (interface,
			       G_CALLBACK (on_handle_hello_world),


	     error = NULL;
	     if	(!g_dbus_interface_skeleton_export (G_DBUS_INTERFACE_SKELETON (interface),
		 /* handle error */

       To facilitate 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 (which is called from the
       thread-default main loop	of the thread where the	skeleton object	was
       contructed) and will cause emissions of the
       org.freedesktop.DBus.Properties::PropertiesChanged[9] signal with all
       the properties that have	changed. Use g_dbus_interface_skeleton_flush()
       or g_dbus_object_skeleton_flush() to empty the queue immediately. Use
       g_object_freeze_notify()	and g_object_thaw_notify() for atomic
       changesets if on	a different thread.

       Scalar types (type-strings 'b', 'y', 'n', 'q', 'i', 'u',	'x', 't' and
       'd') ), strings (type-strings 's', 'ay',	'o' and	'g') and arrays	of
       string (type-strings 'as', 'ao' 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.

       The generated C functions are guaranteed	to not change their ABI	that
       is, if a	method,	signal or property does	not change its signature in
       the introspection XML, the generated C functions	will not change	its C
       ABI either. The ABI of the generated instance and class structures will
       be preserved as well.

       The ABI of the generated	#GType s will be preserved only	if the
       org.gtk.GDBus.Since annotation is used judiciously -- this is because
       the VTable for the #GInterface relies on	functions pointers for signal
       handlers. Specifically, if a D-Bus method, property or signal or	is
       added to	a D-Bus	interface, then	ABI of the generated #GInterface type
       is preserved if,	and only if, each added	method,	property signal	is
       annotated with they org.gtk.GDBus.Since annotation using	a greater
       version number than previous versions.

       The generated C code currently happens to be annotated with gtk-doc[6]
       / GObject Introspection[10] comments / annotations. The layout and
       contents	might change in	the future so no guarantees about e.g.
       SECTION usage etc. is given.

       While the generated Docbook for D-Bus interfaces	isn't expected to
       change, no guarantees are given at this point.

       It is important to note that the	generated code should not be checked
       into revision control systems, nor it should be included	in distributed
       source archives.

       Please send bug reports to either the distribution bug tracker or the
       upstream	bug tracker at


	1. D-Bus Introspection XML

	2. RefEntry

	3. sortas attribute

	4. CamelCase

	5. #pragma once

	6. gtk-doc

	7. parameter

	8. constant

	9. org.freedesktop.DBus.Properties.Set

       10. GObject Introspection

GIO							      GDBUS-CODEGEN(1)


Want to link to this manual page? Use this URL:

home | help