diff options
Diffstat (limited to 'gtk+-mingw/share/gtk-doc/html/gio/gdbus-codegen.html')
| -rw-r--r-- | gtk+-mingw/share/gtk-doc/html/gio/gdbus-codegen.html | 799 |
1 files changed, 0 insertions, 799 deletions
diff --git a/gtk+-mingw/share/gtk-doc/html/gio/gdbus-codegen.html b/gtk+-mingw/share/gtk-doc/html/gio/gdbus-codegen.html deleted file mode 100644 index 527cf1f..0000000 --- a/gtk+-mingw/share/gtk-doc/html/gio/gdbus-codegen.html +++ /dev/null @@ -1,799 +0,0 @@ -<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> -<html> -<head> -<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> -<title>gdbus-codegen</title> -<meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> -<link rel="home" href="index.html" title="GIO Reference Manual"> -<link rel="up" href="tools.html" title="GIO Tools"> -<link rel="prev" href="gdbus.html" title="gdbus"> -<link rel="next" href="gresource-tool.html" title="gresource"> -<meta name="generator" content="GTK-Doc V1.18 (XML mode)"> -<link rel="stylesheet" href="style.css" type="text/css"> -</head> -<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> -<table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="2"><tr valign="middle"> -<td><a accesskey="p" href="gdbus.html"><img src="left.png" width="24" height="24" border="0" alt="Prev"></a></td> -<td><a accesskey="u" href="tools.html"><img src="up.png" width="24" height="24" border="0" alt="Up"></a></td> -<td><a accesskey="h" href="index.html"><img src="home.png" width="24" height="24" border="0" alt="Home"></a></td> -<th width="100%" align="center">GIO Reference Manual</th> -<td><a accesskey="n" href="gresource-tool.html"><img src="right.png" width="24" height="24" border="0" alt="Next"></a></td> -</tr></table> -<div lang="en" class="refentry"> -<a name="gdbus-codegen"></a><div class="titlepage"></div> -<div class="refnamediv"><table width="100%"><tr> -<td valign="top"> -<h2><span class="refentrytitle">gdbus-codegen</span></h2> -<p>gdbus-codegen — D-Bus code and documentation generator</p> -</td> -<td valign="top" align="right"></td> -</tr></table></div> -<div class="refsynopsisdiv"> -<h2>Synopsis</h2> -<div class="cmdsynopsis"><p><code class="command">gdbus-codegen</code> [<code class="option">--interface-prefix</code> <em class="replaceable"><code>org.project.Prefix</code></em>] [<code class="option">--generate-c-code</code> <em class="replaceable"><code>OUTFILES</code></em>] [<code class="option">--c-namespace</code> <em class="replaceable"><code>YourProject</code></em>] [<code class="option">--c-generate-object-manager</code>] [<code class="option">--generate-docbook</code> <em class="replaceable"><code>OUTFILES</code></em>] [ - <code class="option">--annotate</code> - <em class="replaceable"><code>ELEMENT</code></em> - <em class="replaceable"><code>KEY</code></em> - <em class="replaceable"><code>VALUE</code></em> - ]... FILE [ - FILE... - ]</p></div> -</div> -<div class="refsect1"> -<a name="idp42663568"></a><h2>Description</h2> -<p> - <span class="command"><strong>gdbus-codegen</strong></span> is used to generate code and/or - documentation for one or more D-Bus interfaces. The tool reads - <a class="ulink" href="http://dbus.freedesktop.org/doc/dbus-specification.html#introspection-format" target="_top">D-Bus - Introspection XML</a> files and generates output files. The - tool currently supports generating C code (via - <code class="option">--generate-c-code</code>) and Docbook XML (via - <code class="option">--generate-docbook</code>). - </p> -</div> -<div class="refsect1"> -<a name="idp47411232"></a><h2>Generating C code</h2> -<p> - When generating C code, a - <span class="type">GInterface</span>-derived type is generated for each D-Bus - interface. Additionally, for every generated type, - <span class="type">FooBar</span>, two concrete instantiable types, - <span class="type">FooBarProxy</span> and <span class="type">FooBarSkeleton</span>, implementing - said interface are also generated. The former is derived from - <a class="link" href="GDBusProxy.html" title="GDBusProxy"><span class="type">GDBusProxy</span></a> and intended for use on the client side - while the latter is derived from the - <a class="link" href="GDBusInterfaceSkeleton.html" title="GDBusInterfaceSkeleton"><span class="type">GDBusInterfaceSkeleton</span></a> type making it easy to export on a - <a class="link" href="GDBusConnection.html" title="GDBusConnection"><span class="type">GDBusConnection</span></a> either directly or via a - <a class="link" href="GDBusObjectManagerServer.html" title="GDBusObjectManagerServer"><span class="type">GDBusObjectManagerServer</span></a> instance. - </p> -<p> - The name of each generated C type is derived from the D-Bus - interface name stripped with the prefix given with - <code class="option">--interface-prefix</code> and with the dots removed and - initial characters capitalized. For example, for the D-Bus - interface <code class="literal">com.acme.Coyote</code> the name used is - <code class="literal">ComAcmeCoyote</code>. For the D-Bus interface - <code class="literal">org.project.Bar.Frobnicator</code> with - <code class="option">--interface-prefix</code> - <code class="literal">org.project.</code>, the name used is - <code class="literal">BarFrobnicator</code>. - </p> -<p> - For methods, signals and properties, if not specified, the name - defaults to the name of the method, signal or property. - </p> -<p> - Two forms of the name are used - the CamelCase form and the - lower-case form. The CamelCase form is used for the <a href="./../gobject/gobject/gobject-Type-Information.html#GType"><span class="type">GType</span></a> 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). - </p> -<p> - If the value given by the <code class="literal">org.gtk.GDBus.C.Name</code> - annotation or the <code class="option">--c-namespace</code> option contains - an underscore (sometimes called <span class="emphasis"><em>Ugly_Case</em></span>), - 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 - <code class="literal">net.MyCorp.MyApp.iSCSITarget</code> with the value - <code class="literal">iSCSI_Target</code> the CamelCase form is - <code class="literal">iSCSITarget</code> while the lower-case form is - <code class="literal">iscsi_target</code>. If the annotation is used on the - method <code class="literal">EjectTheiPod</code> with the value - <code class="literal">Eject_The_iPod</code>, the lower-case form is - <code class="literal">eject_the_ipod</code>. - </p> -</div> -<div class="refsect1"> -<a name="idp63262256"></a><h2>Generating Docbook documentation</h2> -<p> - Each generated Docbook XML file (see the - <code class="option">--generate-docbook</code> option for details) is a <a class="ulink" href="http://www.docbook.org/tdg/en/html/refentry.html" target="_top"><code class="literal">RefEntry</code></a> - article describing the D-Bus interface. - </p> -</div> -<div class="refsect1"> -<a name="idp63311472"></a><h2>Options</h2> -<p> - The following options are supported: - </p> -<div class="variablelist"><table border="0"> -<col align="left" valign="top"> -<tbody> -<tr> -<td><p><span class="term"><code class="option">--interface-prefix</code> <em class="replaceable"><code>org.project.Prefix.</code></em></span></p></td> -<td><p> - A prefix to strip from all D-Bus interface names when - calculating the typename for the C binding and the Docbook - <a class="ulink" href="http://www.docbook.org/tdg/en/html/primary.html" target="_top">sortas - attribute</a>. - </p></td> -</tr> -<tr> -<td><p><span class="term"><code class="option">--generate-docbook</code> <em class="replaceable"><code>OUTFILES</code></em></span></p></td> -<td><p> - Generate Docbook Documentation for each D-Bus interface and - put it in <code class="filename">OUTFILES-NAME.xml</code> where - <code class="literal">NAME</code> is a place-holder for the interface - name, e.g. <code class="literal">net.Corp.FooBar</code> and so on. - </p></td> -</tr> -<tr> -<td><p><span class="term"><code class="option">--generate-c-code</code> <em class="replaceable"><code>OUTFILES</code></em></span></p></td> -<td><p> - Generate C code for all D-Bus interfaces and put it in - <code class="filename">OUTFILES.c</code> and - <code class="filename">OUTFILES.h</code>. - </p></td> -</tr> -<tr> -<td><p><span class="term"><code class="option">--c-namespace</code> <em class="replaceable"><code>YourProject</code></em></span></p></td> -<td><p> - The namespace to use for generated C code. This is expected - to be in <a class="ulink" href="http://en.wikipedia.org/wiki/CamelCase" target="_top">CamelCase</a> - or <span class="emphasis"><em>Ugly_Case</em></span> (see above). - </p></td> -</tr> -<tr> -<td><p><span class="term"><code class="option">--c-generate-object-manager</code></span></p></td> -<td><p> - If this option is passed, suitable <a class="link" href="GDBusObject.html" title="GDBusObject"><span class="type">GDBusObject</span></a>, - <a class="link" href="GDBusObjectProxy.html" title="GDBusObjectProxy"><span class="type">GDBusObjectProxy</span></a>, <a class="link" href="GDBusObjectSkeleton.html" title="GDBusObjectSkeleton"><span class="type">GDBusObjectSkeleton</span></a> and - <a class="link" href="GDBusObjectManagerClient.html" title="GDBusObjectManagerClient"><span class="type">GDBusObjectManagerClient</span></a> subclasses are generated. - </p></td> -</tr> -<tr> -<td><p><span class="term"><code class="option">--annotate</code> <em class="replaceable"><code>ELEMENT</code></em> <em class="replaceable"><code>KEY</code></em> <em class="replaceable"><code>VALUE</code></em></span></p></td> -<td> -<p> - 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: - </p> -<div class="informalexample"><pre class="programlisting"> -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 \ - myapp-dbus-interfaces.xml -</pre></div> -<p> - Any UTF-8 string can be used for <em class="replaceable"><code>KEY</code></em> and <em class="replaceable"><code>VALUE</code></em>. - </p> -</td> -</tr> -</tbody> -</table></div> -</div> -<div class="refsect1"> -<a name="idp59925120"></a><h2>Supported D-Bus Annotations</h2> -<p> - The following D-Bus annotations are supported by - <span class="command"><strong>gdbus-codegen</strong></span>: - </p> -<div class="variablelist"><table border="0"> -<col align="left" valign="top"> -<tbody> -<tr> -<td><p><span class="term"><code class="literal">org.freedesktop.DBus.Deprecated</code></span></p></td> -<td> -<p> - Can be used on any <code class="literal"><interface></code>, - <code class="literal"><method></code>, - <code class="literal"><signal></code> and - <code class="literal"><property></code> element to specify that - the element is deprecated if its value is - <code class="literal">true</code>. Note that this annotation is - defined in the <a class="ulink" href="http://dbus.freedesktop.org/doc/dbus-specification.html#introspection-format" target="_top">D-Bus - specification</a> and can only assume the values - <code class="literal">true</code> and <code class="literal">false</code>. 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. - </p> -<p> - When generating C code, this annotation is used to add - <a href="./../glib/glib/glib-Miscellaneous-Macros.html#G-GNUC-DEPRECATED:CAPS"><span class="type">G_GNUC_DEPRECATED</span></a> to generated functions for the element. - </p> -<p> - When generating Docbook XML, a deprecation warning will - appear along the documentation for the element. - </p> -</td> -</tr> -<tr> -<td><p><span class="term"><code class="literal">org.gtk.GDBus.Since</code></span></p></td> -<td> -<p> - Can be used on any <code class="literal"><interface></code>, - <code class="literal"><method></code>, - <code class="literal"><signal></code> and - <code class="literal"><property></code> element to specify the - version (any free-form string but compared using a - version-aware sort function) the element appeared in. - </p> -<p> - When generating C code, this field is used to ensure - function pointer order for preserving ABI/API, see <a class="xref" href="gdbus-codegen.html#gdbus-code-stability" title="Stability Guarantees">the section called “Stability Guarantees”</a>. - </p> -<p> - When generating Docbook XML, the value of this tag appears - in the documentation. - </p> -</td> -</tr> -<tr> -<td><p><span class="term"><code class="literal">org.gtk.GDBus.DocString</code></span></p></td> -<td><p> - A string with Docbook content for documentation. This annotation can - be used on <code class="literal"><interface></code>, - <code class="literal"><method></code>, - <code class="literal"><signal></code>, - <code class="literal"><property></code> and - <code class="literal"><arg></code> elements. - </p></td> -</tr> -<tr> -<td><p><span class="term"><code class="literal">org.gtk.GDBus.DocString.Short</code></span></p></td> -<td><p> - A string with Docbook content for short/brief - documentation. This annotation can only be used on - <code class="literal"><interface></code> elements. - </p></td> -</tr> -<tr> -<td><p><span class="term"><code class="literal">org.gtk.GDBus.C.Name</code></span></p></td> -<td><p> - Can be used on any <code class="literal"><interface></code>, - <code class="literal"><method></code>, - <code class="literal"><signal></code> and - <code class="literal"><property></code> element to specify the - name to use when generating C code. The value is expected to - be in <a class="ulink" href="http://en.wikipedia.org/wiki/CamelCase" target="_top">CamelCase</a> - or <span class="emphasis"><em>Ugly_Case</em></span> (see above). - </p></td> -</tr> -<tr> -<td><p><span class="term"><code class="literal">org.gtk.GDBus.C.ForceGVariant</code></span></p></td> -<td><p> - If set to a non-empty string, a <a href="./../glib/glib/glib-GVariant.html#GVariant"><span class="type">GVariant</span></a> instance will - be used instead of the natural C type. This annotation can - be used on any <code class="literal"><arg></code> and - <code class="literal"><property></code> element. - </p></td> -</tr> -<tr> -<td><p><span class="term"><code class="literal">org.gtk.GDBus.C.UnixFD</code></span></p></td> -<td><p> - If set to a non-empty string, the generated code will - include parameters to exchange file descriptors using the - <a class="link" href="GUnixFDList.html" title="GUnixFDList"><span class="type">GUnixFDList</span></a> type. This annotation can be used on - <code class="literal"><method></code> elements. - </p></td> -</tr> -</tbody> -</table></div> -<p> - As an easier alternative to using the - <code class="literal">org.gtk.GDBus.DocString</code> annotation, note that - parser used by <span class="command"><strong>gdbus-codegen</strong></span> parses XML - comments in a way similar to <a class="ulink" href="http://www.gtk.org/gtk-doc/" target="_top">gtk-doc</a>: -</p> -<div class="informalexample"><pre class="programlisting"> -<!-- - 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> -</pre></div> -<p> - </p> -<p> - Note that <code class="literal">@since</code> can be used in any inline - documentation bit (e.g. for interfaces, methods, signals and - properties) to set the <code class="literal">org.gtk.GDBus.Since</code> - annotation. For the <code class="literal">org.gtk.GDBus.DocString</code> - annotation (and inline comments), note that substrings of the form - <code class="literal">#net.Corp.Bar</code>, - <code class="literal">net.Corp.Bar.FooMethod()</code>, - <code class="literal">#net.Corp.Bar::BarSignal</code> and - <code class="literal">#net.Corp.InlineDocs:BazProperty</code> are all - expanded to links to the respective interface, method, signal and - property. - Additionally, substrings starting with <code class="literal">@</code> and <code class="literal">%</code> characters are rendered as - <a class="ulink" href="http://www.docbook.org/tdg/en/html/parameter.html" target="_top">parameter</a> and - <a class="ulink" href="http://www.docbook.org/tdg/en/html/constant.html" target="_top">constant</a> respectively. - </p> -<p> - If both XML comments and - <code class="literal">org.gtk.GDBus.DocString</code> or - <code class="literal">org.gtk.GDBus.DocString.Short</code> annotations are - present, the latter wins. - </p> -</div> -<div class="refsect1"> -<a name="idp7269136"></a><h2>Example</h2> -<p> - Consider the following D-Bus Introspection XML. - </p> -<div class="informalexample"><pre class="programlisting"> -<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> -</pre></div> -<p> - If <span class="command"><strong>gdbus-codegen</strong></span> is used on this file like this: - </p> -<div class="informalexample"><pre class="programlisting"> -gdbus-codegen --generate-c-code myapp-generated \ - --c-namespace MyApp \ - --interface-prefix net.corp.MyApp. \ - net.Corp.MyApp.Frobber.xml -</pre></div> -<p> - two files called - <code class="filename">myapp-generated.[ch]</code> are - generated. The files provide an abstract - <a href="./../gobject/gobject/gobject-Type-Information.html#GTypeInterface"><span class="type">GTypeInterface</span></a>-derived type called - <span class="type">MyAppFrobber</span> as well as two instantiable types with - the same name but suffixed with <span class="type">Proxy</span> and - <span class="type">Skeleton</span>. The generated file, roughly, contains the - following facilities: - </p> -<div class="informalexample"><pre class="programlisting"> -/* 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); -</pre></div> -<p> - Thus, for every D-Bus method, there will be three C functions for - calling the method, one <a href="./../gobject/gobject/gobject-The-Base-Object-Type.html#GObject"><span class="type">GObject</span></a> signal for handling an incoming - call and one C function for completing an incoming call. For every - D-Bus signal, there's one <a href="./../gobject/gobject/gobject-The-Base-Object-Type.html#GObject"><span class="type">GObject</span></a> signal and one C function for - emitting it. For every D-Bus property, two C functions are - generated (one setter, one getter) and one <a href="./../gobject/gobject/gobject-The-Base-Object-Type.html#GObject"><span class="type">GObject</span></a> property. The - following table summarizes the generated facilities and where they - are applicable: - </p> -<div class="informaltable"><table border="1"> -<colgroup> -<col> -<col> -<col> -</colgroup> -<thead><tr> -<th> </th> -<th>Client</th> -<th>Server</th> -</tr></thead> -<tbody> -<tr> -<td>Types</td> -<td>Use <span class="type">MyAppFrobberProxy</span> -</td> -<td>Any type implementing the <span class="type">MyAppFrobber</span> interface</td> -</tr> -<tr> -<td>Methods</td> -<td>Use <code class="function"><code class="function">m_a_f_hello_world()</code></code> to call.</td> -<td>Receive via the <code class="function"><code class="function">handle_hello_world()</code></code> signal handler. Complete the call with <code class="function"><code class="function">m_a_f_complete_hello_world()</code></code> -</td> -</tr> -<tr> -<td>Signals</td> -<td>Connect to the <code class="function">::notification</code> GObject signal.</td> -<td>Use <code class="function"><code class="function">m_a_f_emit_notification()</code></code> to emit signal.</td> -</tr> -<tr> -<td>Properties (Reading)</td> -<td>Use <code class="function"><code class="function">m_a_f_get_verbose()</code></code> or <em class="parameter"><code>:verbose</code></em>.</td> -<td>Implement <a href="./../gobject/gobject/gobject-The-Base-Object-Type.html#GObject"><span class="type">GObject</span></a>'s <code class="function"><code class="function">get_property()</code></code> vfunc.</td> -</tr> -<tr> -<td>Properties (writing)</td> -<td>Use <code class="function"><code class="function">m_a_f_set_verbose()</code></code> or <em class="parameter"><code>:verbose</code></em>.</td> -<td>Implement <a href="./../gobject/gobject/gobject-The-Base-Object-Type.html#GObject"><span class="type">GObject</span></a>'s <code class="function"><code class="function">set_property()</code></code> vfunc.</td> -</tr> -</tbody> -</table></div> -<div class="refsect2"> -<a name="idp7529248"></a><h3>Client-side usage</h3> -<p> - You can use the generated proxy type with the generated - constructors: - </p> -<div class="informalexample"><pre class="programlisting"> - 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); -</pre></div> -<p> - Instead of using the generic <a class="link" href="GDBusProxy.html" title="GDBusProxy"><span class="type">GDBusProxy</span></a> facilities, one can use - the generated methods such as - <code class="function"><code class="function">my_app_frobber_call_hello_world()</code></code> to invoke - the <code class="function">net.Corp.MyApp.Frobber.HelloWorld()</code> - D-Bus method, connect to the the - <code class="function">::notification</code> GObject signal to receive - the <code class="function">net.Corp.MyApp.Frobber::Notication</code> - D-Bus signal and get/set the - <em class="parameter"><code>net.Corp.MyApp.Frobber:Verbose</code></em> D-Bus - Property using either the GObject property - <em class="parameter"><code>:verbose</code></em> or the - <code class="function"><code class="function">my_app_get_verbose()</code></code> and - <code class="function"><code class="function">my_app_set_verbose()</code></code> methods. Use the - standard <a href="./../gobject/gobject/gobject-The-Base-Object-Type.html#GObject-notify"><span class="type">"notify"</span></a> signal to listen to property changes. - </p> -<p> - Note that all property access is via <a class="link" href="GDBusProxy.html" title="GDBusProxy"><span class="type">GDBusProxy</span></a>'s - property cache so no I/O is ever done when reading properties. - Also note that setting a property will cause the - <a class="ulink" href="http://dbus.freedesktop.org/doc/dbus-specification.html#standard-interfaces-properties" target="_top">org.freedesktop.DBus.Properties.Set</a> 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. - </p> -</div> -<hr> -<div class="refsect2"> -<a name="idp28095488"></a><h3>Server-side usage</h3> -<p> - The generated <span class="type">MyAppFrobber</span> interface is designed so - it is easy to implement it in a <a href="./../gobject/gobject/gobject-The-Base-Object-Type.html#GObject"><span class="type">GObject</span></a> - subclass. For example, to handle - <code class="function"><code class="function">HelloWorld()</code></code> method invocations, set the - vfunc for <code class="function"><code class="function">handle_hello_hello_world()</code></code> in the - <span class="type">MyAppFrobberIface</span> structure. Similary, to handle - the <em class="parameter"><code>net.Corp.MyApp.Frobber:Verbose</code></em> - property override the <em class="parameter"><code>:verbose</code></em> <a href="./../gobject/gobject/gobject-The-Base-Object-Type.html#GObject"><span class="type">GObject</span></a> - property from the subclass. To emit a signal, use - e.g. <code class="function"><code class="function">my_app_emit_signal()</code></code> or - <a href="./../gobject/gobject/gobject-Signals.html#g-signal-emit-by-name"><code class="function">g_signal_emit_by_name()</code></a>. - </p> -<p> - Instead of subclassing, it is often easier to use the generated - <span class="type">MyAppFrobberSkeleton</span> subclass. To handle incoming - method calls, use <code class="function"><a href="./../gobject/gobject/gobject-Signals.html#g-signal-connect"><code class="function">g_signal_connect()</code></a></code> with - the <code class="function">::handle-*</code> signals and instead of - overriding <a href="./../gobject/gobject/gobject-The-Base-Object-Type.html#GObject"><span class="type">GObject</span></a>'s - <code class="function"><code class="function">get_property()</code></code> and - <code class="function"><code class="function">set_property()</code></code> vfuncs, use - <a href="./../gobject/gobject/gobject-The-Base-Object-Type.html#g-object-get"><code class="function">g_object_get()</code></a> and - <a href="./../gobject/gobject/gobject-The-Base-Object-Type.html#g-object-set"><code class="function">g_object_set()</code></a> or the generated property - getters and setters (the generated class has an internal - property bag implementation). - </p> -<div class="informalexample"><pre class="programlisting"> -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); - } - 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 */ - } -</pre></div> -<p> - To facilitate atomic changesets (multiple properties changing at - the same time), <a href="./../gobject/gobject/gobject-The-Base-Object-Type.html#GObject-notify"><span class="type">"notify"</span></a> signals are queued up when - received. The queue is drained in an idle handler (which is called from the - <a href="./../glib/glib/glib-The-Main-Event-Loop.html#g-main-context-push-thread-default">thread-default main loop</a> - of the thread where the skeleton object was - contructed) and will cause emissions of the <a class="ulink" href="http://dbus.freedesktop.org/doc/dbus-specification.html#standard-interfaces-properties" target="_top">org.freedesktop.DBus.Properties::PropertiesChanged</a> - signal with all the properties that have changed. Use - <a class="link" href="GDBusInterfaceSkeleton.html#g-dbus-interface-skeleton-flush" title="g_dbus_interface_skeleton_flush ()"><code class="function">g_dbus_interface_skeleton_flush()</code></a> or - <a class="link" href="GDBusObjectSkeleton.html#g-dbus-object-skeleton-flush" title="g_dbus_object_skeleton_flush ()"><code class="function">g_dbus_object_skeleton_flush()</code></a> to empty the queue - immediately. Use <a href="./../gobject/gobject/gobject-The-Base-Object-Type.html#g-object-freeze-notify"><code class="function">g_object_freeze_notify()</code></a> and - <a href="./../gobject/gobject/gobject-The-Base-Object-Type.html#g-object-thaw-notify"><code class="function">g_object_thaw_notify()</code></a> for atomic changesets if on a different - thread. - </p> -</div> -</div> -<div class="refsect1"> -<a name="idp12935040"></a><h2>C Type Mapping</h2> -<p> - Scalar types - (type-strings - <a href="./../glib/glib/glib-GVariantType.html#G-VARIANT-TYPE-BOOLEAN:CAPS">'b'</a>, - <a href="./../glib/glib/glib-GVariantType.html#G-VARIANT-TYPE-BYTE:CAPS">'y'</a>, - <a href="./../glib/glib/glib-GVariantType.html#G-VARIANT-TYPE-INT16:CAPS">'n'</a>, - <a href="./../glib/glib/glib-GVariantType.html#G-VARIANT-TYPE-UINT16:CAPS">'q'</a>, - <a href="./../glib/glib/glib-GVariantType.html#G-VARIANT-TYPE-INT32:CAPS">'i'</a>, - <a href="./../glib/glib/glib-GVariantType.html#G-VARIANT-TYPE-UINT32:CAPS">'u'</a>, - <a href="./../glib/glib/glib-GVariantType.html#G-VARIANT-TYPE-INT64:CAPS">'x'</a>, - <a href="./../glib/glib/glib-GVariantType.html#G-VARIANT-TYPE-UINT64:CAPS">'t'</a> and - <a href="./../glib/glib/glib-GVariantType.html#G-VARIANT-TYPE-DOUBLE:CAPS">'d'</a>) - ), - strings (type-strings - <a href="./../glib/glib/glib-GVariantType.html#G-VARIANT-TYPE-STRING:CAPS">'s'</a>, - <a href="./../glib/glib/glib-GVariantType.html#G-VARIANT-TYPE-BYTESTRING:CAPS">'ay'</a>, - <a href="./../glib/glib/glib-GVariantType.html#G-VARIANT-TYPE-OBJECT-PATH:CAPS">'o'</a> and - <a href="./../glib/glib/glib-GVariantType.html#G-VARIANT-TYPE-SIGNATURE:CAPS">'g'</a>) and - arrays of string (type-strings - <a href="./../glib/glib/glib-GVariantType.html#G-VARIANT-TYPE-STRING-ARRAY:CAPS">'as'</a>, - <a href="./../glib/glib/glib-GVariantType.html#G-VARIANT-TYPE-OBJECT-PATH-ARRAY:CAPS">'ao'</a> and - <a href="./../glib/glib/glib-GVariantType.html#G-VARIANT-TYPE-BYTESTRING-ARRAY:CAPS">'aay'</a>) - are mapped to the natural types, - e.g. <a href="./../glib/glib/glib-Basic-Types.html#gboolean"><span class="type">gboolean</span></a>, <a href="./../glib/glib/glib-Basic-Types.html#gdouble"><span class="type">gdouble</span></a>, <a href="./../glib/glib/glib-Basic-Types.html#gint"><span class="type">gint</span></a>, <a href="./../gobject/gobject/gobject-Standard-Parameter-and-Value-Types.html#gchararray">gchar*</a>, - <a href="./../gobject/gobject/gobject-Boxed-Types.html#GStrv">gchar**</a> and - so on. Everything else is mapped to the <a href="./../glib/glib/glib-GVariant.html#GVariant"><span class="type">GVariant</span></a> - type. - </p> -<p> - This automatic mapping can be turned off by using the annotation - <code class="literal">org.gtk.GDBus.C.ForceGVariant</code> - if used then a - <a href="./../glib/glib/glib-GVariant.html#GVariant"><span class="type">GVariant</span></a> is always exchanged instead of the - corresponding native C type. This annotation may be convenient to - use when using - bytestrings (type-string <a href="./../glib/glib/glib-GVariantType.html#G-VARIANT-TYPE-BYTESTRING:CAPS">'ay'</a>) - for data that could have embedded NUL bytes. - </p> -</div> -<div class="refsect1"> -<a name="gdbus-code-stability"></a><h2>Stability Guarantees</h2> -<p> - 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. - </p> -<p> - The ABI of the generated <a href="./../gobject/gobject/gobject-Type-Information.html#GType"><span class="type">GType</span></a>s will be preserved only if - the <code class="literal">org.gtk.GDBus.Since</code> annotation is used - judiciously — this is because the VTable for the <span class="type">GInterface</span> - 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 <span class="type">GInterface</span> type is preserved - if, and only if, each added method, property signal is annotated - with they <code class="literal">org.gtk.GDBus.Since</code> annotation using - a greater version number than previous versions. - </p> -<p> - The generated C code currently happens to be annotated with <a class="ulink" href="http://www.gtk.org/gtk-doc/" target="_top">gtk-doc</a> / <a class="ulink" href="https://live.gnome.org/GObjectIntrospection" target="_top">GObject - Introspection</a> comments / annotations. The layout and - contents might change in the future so no guarantees about - e.g. <code class="literal">SECTION</code> usage etc. is given. - </p> -<p> - While the generated Docbook for D-Bus interfaces isn't expected to - change, no guarantees are given at this point. - </p> -</div> -<div class="refsect1"> -<a name="idp11286048"></a><h2>Bugs</h2> -<p> - Please send bug reports to either the distribution bug tracker - or the upstream bug tracker at - <a class="ulink" href="https://bugzilla.gnome.org/enter_bug.cgi?product=glib" target="_top">https://bugzilla.gnome.org/enter_bug.cgi?product=glib</a>. - </p> -</div> -<div class="refsect1"> -<a name="idp22011648"></a><h2>See also</h2> -<p> - <span class="citerefentry"><span class="refentrytitle">gdbus</span>(1)</span> - </p> -</div> -</div> -<div class="footer"> -<hr> - Generated by GTK-Doc V1.18</div> -</body> -</html>
\ No newline at end of file |