blob: c0643fda42c015984b8475d60274bda1630dc543 [file] [log] [blame]
'\" t
.\" Title: gdbus-codegen
.\" Author: David Zeuthen <zeuthen@gmail.com>
.\" Generator: DocBook XSL Stylesheets v1.79.1 <http://docbook.sf.net/>
.\" Date: 07/20/2016
.\" Manual: User Commands
.\" Source: GIO
.\" Language: English
.\"
.TH "GDBUS\-CODEGEN" "1" "" "GIO" "User Commands"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
gdbus-codegen \- D\-Bus code and documentation generator
.SH "SYNOPSIS"
.HP \w'\fBgdbus\-codegen\fR\ 'u
\fBgdbus\-codegen\fR [\fB\-h\fR,\ \fB\-\-help\fR] [\fB\-\-interface\-prefix\fR\ \fIorg\&.project\&.Prefix\fR] [\fB\-\-generate\-c\-code\fR\ \fIOUTFILES\fR] [\fB\-\-c\-namespace\fR\ \fIYourProject\fR] [\fB\-\-c\-generate\-object\-manager\fR] [\fB\-\-c\-generate\-autocleanup\fR\ none|objects|all] [\fB\-\-generate\-docbook\fR\ \fIOUTFILES\fR] [\fB\-\-xml\-files\fR\ \fIFILE\fR] [\fB\-\-annotate\fR\ \fIELEMENT\fR\ \fIKEY\fR\ \fIVALUE\fR]... FILE [FILE...]
.SH "DESCRIPTION"
.PP
\fBgdbus\-codegen\fR
is used to generate code and/or documentation for one or more D\-Bus interfaces\&. The tool reads
\m[blue]\fBD\-Bus Introspection XML\fR\m[]\&\s-2\u[1]\d\s+2
files and generates output files\&. The tool currently supports generating C code (via
\fB\-\-generate\-c\-code\fR) and Docbook XML (via
\fB\-\-generate\-docbook\fR)\&.
.SH "GENERATING C CODE"
.PP
When generating C code, a #GInterface
\-derived type is generated for each D\-Bus interface\&. Additionally, for every generated type,
\fBFooBar\fR, two concrete instantiable types,
\fBFooBarProxy\fR
and
\fBFooBarSkeleton\fR, 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\&.
.PP
The name of each generated C type is derived from the D\-Bus interface name stripped with the prefix given with
\fB\-\-interface\-prefix\fR
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
\fB\-\-interface\-prefix\fR
org\&.project\&., the name used is
BarFrobnicator\&.
.PP
For methods, signals and properties, if not specified, the name defaults to the name of the method, signal or property\&.
.PP
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)\&.
.PP
If the value given by the
org\&.gtk\&.GDBus\&.C\&.Name
annotation or the
\fB\-\-c\-namespace\fR
option contains an underscore (sometimes called
\fIUgly_Case\fR), 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\&.
.SH "GENERATING DOCBOOK DOCUMENTATION"
.PP
Each generated Docbook XML file (see the
\fB\-\-generate\-docbook\fR
option for details) is a
\m[blue]\fBRefEntry\fR\m[]\&\s-2\u[2]\d\s+2
article describing the D\-Bus interface\&.
.SH "OPTIONS"
.PP
The following options are supported:
.PP
\fB\-h\fR, \fB\-\-help\fR
.RS 4
Show help and exit\&.
.RE
.PP
\fB\-\-xml\-files\fR \fIFILE\fR
.RS 4
The D\-Bus introspection XML file\&.
.RE
.PP
\fB\-\-interface\-prefix\fR \fIorg\&.project\&.Prefix\&.\fR
.RS 4
A prefix to strip from all D\-Bus interface names when calculating the typename for the C binding and the Docbook
\m[blue]\fBsortas attribute\fR\m[]\&\s-2\u[3]\d\s+2\&.
.RE
.PP
\fB\-\-generate\-docbook\fR \fIOUTFILES\fR
.RS 4
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\&.
.RE
.PP
\fB\-\-generate\-c\-code\fR \fIOUTFILES\fR
.RS 4
Generate C code for all D\-Bus interfaces and put it in
OUTFILES\&.c
and
OUTFILES\&.h\&.
.RE
.PP
\fB\-\-c\-namespace\fR \fIYourProject\fR
.RS 4
The namespace to use for generated C code\&. This is expected to be in
\m[blue]\fBCamelCase\fR\m[]\&\s-2\u[4]\d\s+2
or
\fIUgly_Case\fR
(see above)\&.
.RE
.PP
\fB\-\-c\-generate\-object\-manager\fR
.RS 4
If this option is passed, suitable #GDBusObject, #GDBusObjectProxy, #GDBusObjectSkeleton and #GDBusObjectManagerClient subclasses are generated\&.
.RE
.PP
\fB\-\-c\-generate\-autocleanup\fR none|objects|all
.RS 4
This option influences what types autocleanup functions are generated for\&. \*(Aqnone\*(Aq means to not generate any autocleanup functions\&. \*(Aqobjects\*(Aq means to generate them for object types, and \*(Aqall\*(Aq means to generate them for object types and interfaces\&. The default is \*(Aqobjects\*(Aq due to a corner case in backwards compatibility with a few projects, but you should likely switch your project to use \*(Aqall\*(Aq\&. This option was added in GLib 2\&.50\&.
.RE
.PP
\fB\-\-annotate\fR \fIELEMENT\fR \fIKEY\fR \fIVALUE\fR
.RS 4
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:
.sp
.if n \{\
.RS 4
.\}
.nf
gdbus\-codegen \-\-c\-namespace MyApp \e
\-\-generate\-c\-code myapp\-generated \e
\-\-annotate "org\&.project\&.InterfaceName" \e
org\&.gtk\&.GDBus\&.C\&.Name MyFrobnicator \e
\-\-annotate "org\&.project\&.InterfaceName:Property" \e
bar bat \e
\-\-annotate "org\&.project\&.InterfaceName\&.Method()" \e
org\&.freedesktop\&.DBus\&.Deprecated true \e
\-\-annotate "org\&.project\&.InterfaceName\&.Method()[arg_name]" \e
snake hiss \e
\-\-annotate "org\&.project\&.InterfaceName::Signal" \e
cat meow \e
\-\-annotate "org\&.project\&.InterfaceName::Signal[arg_name]" \e
dog wuff \e
myapp\-dbus\-interfaces\&.xml
.fi
.if n \{\
.RE
.\}
Any UTF\-8 string can be used for
\fIKEY\fR
and
\fIVALUE\fR\&.
.RE
.SH "SUPPORTED D\-BUS ANNOTATIONS"
.PP
The following D\-Bus annotations are supported by
\fBgdbus\-codegen\fR:
.PP
org\&.freedesktop\&.DBus\&.Deprecated
.RS 4
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
\m[blue]\fBD\-Bus specification\fR\m[]\&\s-2\u[1]\d\s+2
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\&.
.sp
When generating C code, this annotation is used to add #G_GNUC_DEPRECATED to generated functions for the element\&.
.sp
When generating Docbook XML, a deprecation warning will appear along the documentation for the element\&.
.RE
.PP
org\&.gtk\&.GDBus\&.Since
.RS 4
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\&.
.sp
When generating C code, this field is used to ensure function pointer order for preserving ABI/API, see
the section called \(lqSTABILITY GUARANTEES\(rq\&.
.sp
When generating Docbook XML, the value of this tag appears in the documentation\&.
.RE
.PP
org\&.gtk\&.GDBus\&.DocString
.RS 4
A string with Docbook content for documentation\&. This annotation can be used on
<interface>,
<method>,
<signal>,
<property>
and
<arg>
elements\&.
.RE
.PP
org\&.gtk\&.GDBus\&.DocString\&.Short
.RS 4
A string with Docbook content for short/brief documentation\&. This annotation can only be used on
<interface>
elements\&.
.RE
.PP
org\&.gtk\&.GDBus\&.C\&.Name
.RS 4
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
\m[blue]\fBCamelCase\fR\m[]\&\s-2\u[4]\d\s+2
or
\fIUgly_Case\fR
(see above)\&.
.RE
.PP
org\&.gtk\&.GDBus\&.C\&.ForceGVariant
.RS 4
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\&.
.RE
.PP
org\&.gtk\&.GDBus\&.C\&.UnixFD
.RS 4
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\&.
.RE
.PP
As an easier alternative to using the
org\&.gtk\&.GDBus\&.DocString
annotation, note that parser used by
\fBgdbus\-codegen\fR
parses XML comments in a way similar to
\m[blue]\fBgtk\-doc\fR\m[]\&\s-2\u[5]\d\s+2:
.sp .if n \{\ .RS 4 .\} .nf <!\-\- net\&.Corp\&.Bar: @short_description: A short description A <emphasis>longer</emphasis> description\&. This is a new paragraph\&. \-\-> <interface name="net\&.corp\&.Bar"> <!\-\- FooMethod: @greeting: The docs for greeting parameter\&. @response: The docs for response parameter\&. The docs for the actual method\&. \-\-> <method name="FooMethod"> <arg name="greeting" direction="in" type="s"/> <arg name="response" direction="out" type="s"/> </method> <!\-\- BarSignal: @blah: The docs for blah parameter\&. @boo: The docs for boo parameter\&. @since: 2\&.30 The docs for the actual signal\&. \-\-> <signal name="BarSignal"> <arg name="blah" type="s"/> <arg name="boo" type="s"/> </signal> <!\-\- BazProperty: The docs for the property\&. \-\-> <property name="BazProperty" type="s" access="read"/> </interface> .fi .if n \{\ .RE .\}
.PP
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
\m[blue]\fBparameter\fR\m[]\&\s-2\u[6]\d\s+2
and
\m[blue]\fBconstant\fR\m[]\&\s-2\u[7]\d\s+2
respectively\&.
.PP
If both XML comments and
org\&.gtk\&.GDBus\&.DocString
or
org\&.gtk\&.GDBus\&.DocString\&.Short
annotations are present, the latter wins\&.
.SH "EXAMPLE"
.PP
Consider the following D\-Bus Introspection XML\&.
.sp
.if n \{\
.RS 4
.\}
.nf
<node>
<interface name="net\&.Corp\&.MyApp\&.Frobber">
<method name="HelloWorld">
<arg name="greeting" direction="in" type="s"/>
<arg name="response" direction="out" type="s"/>
</method>
<signal name="Notification">
<arg name="icon_blob" type="ay"/>
<arg name="height" type="i"/>
<arg name="messages" type="as"/>
</signal>
<property name="Verbose" type="b" access="readwrite"/>
</interface>
</node>
.fi
.if n \{\
.RE
.\}
.PP
If
\fBgdbus\-codegen\fR
is used on this file like this:
.sp
.if n \{\
.RS 4
.\}
.nf
gdbus\-codegen \-\-generate\-c\-code myapp\-generated \e
\-\-c\-namespace MyApp \e
\-\-interface\-prefix net\&.corp\&.MyApp\&. \e
net\&.Corp\&.MyApp\&.Frobber\&.xml
.fi
.if n \{\
.RE
.\}
.PP
two files called
myapp\-generated\&.[ch]
are generated\&. The files provide an abstract #GTypeInterface
\-derived type called
\fBMyAppFrobber\fR
as well as two instantiable types with the same name but suffixed with
\fBProxy\fR
and
\fBSkeleton\fR\&. The generated file, roughly, contains the following facilities:
.sp
.if n \{\
.RS 4
.\}
.nf
/* 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() */
void
my_app_frobber_call_hello_world (MyAppFrobber *proxy,
const gchar *greeting,
GCancellable *cancellable,
GAsyncReadyCallback callback,
gpointer user_data);
gboolean
my_app_frobber_call_hello_world_finish (MyAppFrobber *proxy,
gchar **out_response,
GAsyncResult *res,
GError **error);
/* Synchronously calls HelloWorld()\&. Blocks calling thread\&. */
gboolean
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 */
void
my_app_frobber_complete_hello_world (MyAppFrobber *object,
GDBusMethodInvocation *invocation,
const gchar *response);
/* Emits the ::notification signal / Notification() D\-Bus signal */
void
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\&.
*/
void
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);
.fi
.if n \{\
.RE
.\}
.PP
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\*(Aqs 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:
.TS
allbox tab(:);
lB lB lB.
T{
\ \&
T}:T{
Client
T}:T{
Server
T}
.T&
l l l
l l l
l l l
l l l
l l l.
T{
Types
T}:T{
Use \fBMyAppFrobberProxy\fR
T}:T{
Any type implementing the \fBMyAppFrobber\fR interface
T}
T{
Methods
T}:T{
Use \fBm_a_f_hello_world()\fR to call\&.
T}:T{
Receive via the \fBhandle_hello_world()\fR signal handler\&. Complete the call with \fBm_a_f_complete_hello_world()\fR
T}
T{
Signals
T}:T{
Connect to the \fB::notification\fR GObject signal\&.
T}:T{
Use \fBm_a_f_emit_notification()\fR to emit signal\&.
T}
T{
Properties (Reading)
T}:T{
Use \fBm_a_f_get_verbose()\fR or \fI:verbose\fR\&.
T}:T{
Implement #GObject\*(Aqs \fBget_property()\fR vfunc\&.
T}
T{
Properties (writing)
T}:T{
Use \fBm_a_f_set_verbose()\fR or \fI:verbose\fR\&.
T}:T{
Implement #GObject\*(Aqs \fBset_property()\fR vfunc\&.
T}
.TE
.sp 1
.SS "Client\-side usage"
.PP
You can use the generated proxy type with the generated constructors:
.sp
.if n \{\
.RS 4
.\}
.nf
MyAppFrobber *proxy;
GError *error;
error = NULL;
proxy = my_app_frobber_proxy_new_for_bus_sync (
G_BUS_TYPE_SESSION,
G_DBUS_PROXY_FLAGS_NONE,
"net\&.Corp\&.MyApp", /* bus name */
"/net/Corp/MyApp/SomeFrobber", /* object */
NULL, /* GCancellable* */
&error);
/* do stuff with proxy */
g_object_unref (proxy);
.fi
.if n \{\
.RE
.\}
.PP
Instead of using the generic #GDBusProxy facilities, one can use the generated methods such as
\fBmy_app_frobber_call_hello_world()\fR
to invoke the
\fBnet\&.Corp\&.MyApp\&.Frobber\&.HelloWorld()\fR
D\-Bus method, connect to the
\fB::notification\fR
GObject signal to receive the
\fBnet\&.Corp\&.MyApp\&.Frobber::Notication\fR
D\-Bus signal and get/set the
\fInet\&.Corp\&.MyApp\&.Frobber:Verbose\fR
D\-Bus Property using either the GObject property
\fI:verbose\fR
or the
\fBmy_app_get_verbose()\fR
and
\fBmy_app_set_verbose()\fR
methods\&. Use the standard #GObject::notify signal to listen to property changes\&.
.PP
Note that all property access is via #GDBusProxy
\*(Aqs property cache so no I/O is ever done when reading properties\&. Also note that setting a property will cause the
\m[blue]\fBorg\&.freedesktop\&.DBus\&.Properties\&.Set\fR\m[]\&\s-2\u[8]\d\s+2
method to be called on the remote object\&. This call, however, is asynchronous so setting a property won\*(Aqt block\&. Further, the change is delayed and no error checking is possible\&.
.SS "Server\-side usage"
.PP
The generated
\fBMyAppFrobber\fR
interface is designed so it is easy to implement it in a #GObject subclass\&. For example, to handle
\fBHelloWorld()\fR
method invocations, set the vfunc for
\fBhandle_hello_hello_world()\fR
in the
\fBMyAppFrobberIface\fR
structure\&. Similary, to handle the
\fInet\&.Corp\&.MyApp\&.Frobber:Verbose\fR
property override the
\fI:verbose\fR
#GObject property from the subclass\&. To emit a signal, use e\&.g\&.
\fBmy_app_emit_signal()\fR
or g_signal_emit_by_name()\&.
.PP
Instead of subclassing, it is often easier to use the generated
\fBMyAppFrobberSkeleton\fR
subclass\&. To handle incoming method calls, use
\fBg_signal_connect()\fR
with the
\fB::handle\-*\fR
signals and instead of overriding #GObject
\*(Aqs
\fBget_property()\fR
and
\fBset_property()\fR
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)\&.
.sp
.if n \{\
.RS 4
.\}
.nf
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\*(Aq\&.", greeting);
my_app_complete_hello_world (interface, invocation, response);
g_free (response);
}
else
{
g_dbus_method_invocation_return_error (invocation,
MY_APP_ERROR,
MY_APP_ERROR_NO_WHINING,
"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,
"handle\-hello\-world",
G_CALLBACK (on_handle_hello_world),
some_user_data);
[\&.\&.\&.]
error = NULL;
if (!g_dbus_interface_skeleton_export (G_DBUS_INTERFACE_SKELETON (interface),
connection,
"/path/of/dbus_object",
&error))
{
/* handle error */
}
.fi
.if n \{\
.RE
.\}
.PP
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
\m[blue]\fBorg\&.freedesktop\&.DBus\&.Properties::PropertiesChanged\fR\m[]\&\s-2\u[8]\d\s+2
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\&.
.SH "C TYPE MAPPING"
.PP
Scalar types (type\-strings
\*(Aqb\*(Aq,
\*(Aqy\*(Aq,
\*(Aqn\*(Aq,
\*(Aqq\*(Aq,
\*(Aqi\*(Aq,
\*(Aqu\*(Aq,
\*(Aqx\*(Aq,
\*(Aqt\*(Aq
and
\*(Aqd\*(Aq) ), strings (type\-strings
\*(Aqs\*(Aq,
\*(Aqay\*(Aq,
\*(Aqo\*(Aq
and
\*(Aqg\*(Aq) and arrays of string (type\-strings
\*(Aqas\*(Aq,
\*(Aqao\*(Aq
and
\*(Aqaay\*(Aq) are mapped to the natural types, e\&.g\&. #gboolean, #gdouble, #gint,
gchar*,
gchar**
and so on\&. Everything else is mapped to the #GVariant type\&.
.PP
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
\*(Aqay\*(Aq) for data that could have embedded NUL bytes\&.
.SH "STABILITY GUARANTEES"
.PP
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\&.
.PP
The ABI of the generated #GType
s will be preserved only if the
org\&.gtk\&.GDBus\&.Since
annotation is used judiciously \(em 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\&.
.PP
The generated C code currently happens to be annotated with
\m[blue]\fBgtk\-doc\fR\m[]\&\s-2\u[5]\d\s+2
/
\m[blue]\fBGObject Introspection\fR\m[]\&\s-2\u[9]\d\s+2
comments / annotations\&. The layout and contents might change in the future so no guarantees about e\&.g\&.
SECTION
usage etc\&. is given\&.
.PP
While the generated Docbook for D\-Bus interfaces isn\*(Aqt expected to change, no guarantees are given at this point\&.
.PP
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\&.
.SH "BUGS"
.PP
Please send bug reports to either the distribution bug tracker or the upstream bug tracker at
\m[blue]\fBhttps://bugzilla\&.gnome\&.org/enter_bug\&.cgi?product=glib\fR\m[]\&.
.SH "SEE ALSO"
.PP
\fBgdbus\fR(1)
.SH "NOTES"
.IP " 1." 4
D-Bus Introspection XML
.RS 4
\%http://dbus.freedesktop.org/doc/dbus-specification.html#introspection-format
.RE
.IP " 2." 4
RefEntry
.RS 4
\%http://www.docbook.org/tdg/en/html/refentry.html
.RE
.IP " 3." 4
sortas attribute
.RS 4
\%http://www.docbook.org/tdg/en/html/primary.html
.RE
.IP " 4." 4
CamelCase
.RS 4
\%http://en.wikipedia.org/wiki/CamelCase
.RE
.IP " 5." 4
gtk-doc
.RS 4
\%http://www.gtk.org/gtk-doc/
.RE
.IP " 6." 4
parameter
.RS 4
\%http://www.docbook.org/tdg/en/html/parameter.html
.RE
.IP " 7." 4
constant
.RS 4
\%http://www.docbook.org/tdg/en/html/constant.html
.RE
.IP " 8." 4
org.freedesktop.DBus.Properties.Set
.RS 4
\%http://dbus.freedesktop.org/doc/dbus-specification.html#standard-interfaces-properties
.RE
.IP " 9." 4
GObject Introspection
.RS 4
\%https://wiki.gnome.org/Projects/GObjectIntrospection
.RE