15995N/A<!
DOCTYPE REFENTRY PUBLIC "-//Sun Microsystems//DTD DocBook V3.0-Based SolBook Subset V2.0//EN" [
15995N/A<!--ArborText, Inc., 1988-1999, v.4002-->
15995N/A<!
ENTITY cmd "dbus-binding-tool">
15995N/A<!
ENTITY suncopy "Copyright (c) 2009 Sun Microsystems, Inc. All Rights Reserved.">
15995N/A<
refentry id="dbus-binding-tool-1">
15995N/A<
refmeta><
refentrytitle>&cmd;</
refentrytitle><
manvolnum>1</
manvolnum>
15995N/A<
refmiscinfo class="date">26 Feb 2009</
refmiscinfo>
15995N/A<
refmiscinfo class="sectdesc">&man1;</
refmiscinfo>
15995N/A<
refmiscinfo class="software">&release;</
refmiscinfo>
15995N/A<
refmiscinfo class="arch">generic</
refmiscinfo>
15995N/A<
refmiscinfo class="copyright">&suncopy;</
refmiscinfo>
15995N/A<
indexterm><
primary>&cmd;</
primary></
indexterm><
indexterm><
primary>
15995N/A<
refnamediv id="dbus-binding-tool-1-name"><
refname>&cmd;</
refname><
refpurpose>
15995N/A<
refsynopsisdiv id="dbus-binding-tool-1-synp"><
title>&synp-tt;</
title>
15995N/A<
cmdsynopsis><
command>&cmd;</
command>
15995N/A<
arg choice="opt"><
option>-force</
option></
arg>
15995N/A<
arg choice="opt"><
option>-help</
option></
arg>
15995N/A<
arg choice="opt"><
option>-ignore-unsupported</
option></
arg>
15995N/A<
arg choice="opt"><
option>-mode=<
replaceable>pretty|glib-client|glib-server</
replaceable></
option></
arg>
15995N/A<
arg choice="opt"><
option>-output=<
replaceable>file</
replaceable></
option></
arg>
15995N/A<
arg choice="opt"><
option>-prefix=<
replaceable>symbol-prefix</
replaceable></
option></
arg>
15995N/A<
arg choice="opt"><
option>-version</
option></
arg>
15995N/A<
arg rep="repeat"><
option role="nodash"><
replaceable>file</
replaceable></
option></
arg>
15995N/A<
refsect1 id="dbus-binding-tool-1-desc"><
title>&desc-tt;</
title>
15995N/A<
command>&cmd;</
command> is used to expose a GObject via D\-Bus. As input,
15995N/A<
command>&cmd;</
command> uses a D\-Bus Introspection XML file. As output,
15995N/Athe client-side or server-side bindings is generated. This output is a header
15995N/Afile which eases the use of a remote D\-Bus object. Output is sent to standard
15995N/Aout or to the filename specified with the <
option>-output</
option> argument.
15995N/A<
refsect1 id="pkg-config-1-exde"><
title>&exde-tt;</
title>
15995N/AThe following is a sample D\-Bus Introspection XML file which describes an
15995N/Aobject that exposes one method, named ManyArgs:
15995N/A<?xml version="1.0" encoding="UTF-8" ?>
15995N/A <method name="ManyArgs">
15995N/A <arg type="u" name="x" direction="in" />
15995N/A <arg type="s" name="str" direction="in" />
15995N/A <arg type="d" name="trouble" direction="in" />
15995N/A <arg type="d" name="d_ret" direction="out" />
15995N/A <arg type="s" name="str_ret" direction="out" />
15995N/A<
command>&cmd;</
command> supports annotations in the XML format to further
15995N/Acontrol how the bindings are generated.
15995N/A<
title>client-side bindings</
title>
15995N/AWhen building client-side bindings, the <
option>-mode=glib-client</
option>
15995N/Aargument is used. The client-side bindings support the
15995N/Awithin the <method> tag to indicate that the client is not expecting
15995N/Aa reply to the method call, so a reply should not be sent. This is
15995N/Aoften used to speed up rapid method calls where there are no "out"
15995N/Aarguments, and not knowing if the method succeeded is an acceptable compromise
15995N/Ato halve the traffic on the bus. For example:
15995N/A<method name "FooMethod">
15995N/A<
title>server-side bindings</
title>
15995N/AWhen building server-side bindings, the <
option>-mode=glib-server</
option>
15995N/Aargument is used. Also the <
option>-prefix</
option> argument must be used when
15995N/Abuilding server-side bindings so that functions in the generated output are
15995N/Aprefexed with the specified value. The server-side bindings support the
15995N/AThis annotation is used to specify the C symbol names for the various types
15995N/A(interface, method, etc.), if it differs from the name D\-Bus generates.
15995N/A <method name "ManyArgs">
15995N/AThis annotation marks the method implementation as an asynchronous function,
15995N/Awhich does not return a response straight away but will send the response at
15995N/Asome later point to complete the call. This is used to implement non-blocking
15995N/Aservices where method calls can take time.
15995N/AWhen a method is asynchronous, the function prototype is different. It is
15995N/Arequired that the function conform to the following rules:
15995N/A<
listitem>The function must return a value of type gboolean; TRUE on success,
15995N/A<
listitem>The first parameter is a pointer to an instance of the object.
15995N/A<listitem>Following the object instance pointer are the method input values.
15995N/A<
listitem>The final parameter must be a (DBusGMethodInvocation *). This is used
15995N/Awhen sending the response message back to the client, by calling
15995N/Adbus_g_method_return or dbus_g_method_return_error.</
listitem>
15995N/A<method name "FooMethod">
15995N/AThis attribute can only be applied to "out" <arg> nodes, and
15995N/Aspecifies that the parameter is not being copied when returned. For example,
15995N/Athis turns a 's' argument from a (char **) to a (const char **), and results in
15995N/Athe argument not being freed by D\-Bus after the message is sent. For example:
15995N/A <arg type="u" name="x" direction="out">
15995N/AThis attribute can only be applied to "out" <arg> nodes, and
15995N/Aalters the expected function signature. It currently can be set to two values:
15995N/A"" or "error". The argument marked with this attribute is
15995N/Anot returned via a pointer argument, but by the function's return value. If the
15995N/Aattribute's value is the empty string, the (GError *) argument is also omitted
15995N/Aso there is no standard way to return an error value. This is very useful for
15995N/Ainterfacing with existing code, as it is possible to match existing APIs. If
15995N/Athe attribute's value is "error", then the final argument is a
15995N/A(GError *) as usual. For example:
15995N/A <arg type="u" name="x" direction="out">
15995N/A<
refsect1 id="dbus-binding-tool-1-opts"><
title>&opts-tt;</
title>
15995N/A<
para>The following options are supported:</
para>
15995N/A<
variablelist termlength="wholeline">
15995N/A<
term><
option>-force</
option></
term>
15995N/AOverwrite the output file if it already exists with a newer timestamp than the
17601N/A</
para></
listitem></
varlistentry>
15995N/A<
term><
option>-help</
option></
term>
17601N/A</
para></
listitem></
varlistentry>
15995N/A<
term><
option>-ignore-unsupported</
option></
term>
15995N/AIf set, then unsupported signatures for <method> parameters are
17601N/A</
para></
listitem></
varlistentry>
15995N/A<
term><
option>-mode=<
replaceable>pretty|glib-client|glib-server</
replaceable></
option></
term>
15995N/AIf the value is "glib-client", then client bindings are generated.
15995N/AIf the value is "glib-server", then server bindings are generated.
15995N/AIf the value is "pretty", then the output is in a more human readable
17601N/A</
para></
listitem></
varlistentry>
15995N/A<
term><
option>-output=<
replaceable>file</
replaceable></
option></
term>
15995N/ASpecify the output <
replaceable>file</
replaceable>.
17601N/A</
para></
listitem></
varlistentry>
15995N/A<
term><
option>-prefix=<
replaceable>symbol-prefix</
replaceable></
option></
term>
15995N/AFunctions in the generated output are prefixed with the
15995N/A<
replaceable>symbol-prefix</
replaceable> value.
17601N/A</
para></
listitem></
varlistentry>
15995N/A<
term><
option>-version</
option></
term>
15995N/ADisplay the version number of the <
command>&cmd;</
command> command.
17601N/A</
para></
listitem></
varlistentry>
15995N/A<
refsect1 id="gnome-audio-preview-1-oper"><
title>&oper-tt;</
title>
17601N/AThe following operands are supported:
15995N/A<
variablelist termlength="narrow">
15995N/A<
term><
option role="nodash"><
replaceable>file</
replaceable></
option></
term>
15995N/AA list of one or more input D\-Bus Introspection XML files to include in the
17601N/A</
para></
listitem></
varlistentry>
15995N/A<
refsect1 id="dbus-binding-tool-1-file"><
title>&file-tt;</
title>
17601N/AThe following files are used by this application:
15995N/A<
variablelist termlength="wide">
15995N/A<
varlistentry><
term><
filename>/
usr/
bin/&cmd;</
filename> </
term><
listitem>
15995N/A<
para>Executable for the D\-Bus Binding Tool application.</
para>
15995N/A<
refsect1 id="dbus-binding-tool-1-attr"><
title>&attr-tt;</
title>
17601N/A<
olink targetdocent="REFMAN5" localinfo="attributes-5">
17601N/A<
citerefentry><
refentrytitle>attributes</
refentrytitle>
17601N/A<
manvolnum>5</
manvolnum></
citerefentry></
olink>
17601N/Afor descriptions of the following attributes:
17601N/A<
tgroup cols="2" colsep="1" rowsep="1">
17601N/A<
colspec colname="COLSPEC0" colwidth="1*">
15995N/A<
colspec colname="COLSPEC1" colwidth="1*">
17601N/A<
entry align="center" valign="middle">ATTRIBUTE TYPE</
entry>
17601N/A<
entry align="center" valign="middle">ATTRIBUTE VALUE</
entry></
row>
17601N/A<
entry><
para>Availability</
para></
entry>
17601N/A<
entry><
para>SUNWdbus-glib</
para></
entry>
17601N/A<
entry colname="COLSPEC0"><
para>Interface stability</
para></
entry>
17601N/A<
entry colname="COLSPEC1"><
para>Volatile</
para></
entry>
15995N/A<
refsect1 id="dbus-binding-tool-1-also"><
title>&also-tt;</
title>
15995N/A<!--Reference to another man page--> 15995N/A<!--Reference to a Help manual--> 15995N/A<
citerefentry><
refentrytitle>dbus-cleanup-sockets</
refentrytitle><
manvolnum>1</
manvolnum></
citerefentry>,
15995N/A<
citerefentry><
refentrytitle>dbus-daemon</
refentrytitle><
manvolnum>1</
manvolnum></
citerefentry>,
15995N/A<
citerefentry><
refentrytitle>dbus-monitor</
refentrytitle><
manvolnum>1</
manvolnum></
citerefentry>,
15995N/A<
citerefentry><
refentrytitle>dbus-send</
refentrytitle><
manvolnum>1</
manvolnum></
citerefentry>,
15995N/A<
citerefentry><
refentrytitle>dbus-uuidgen</
refentrytitle><
manvolnum>1</
manvolnum></
citerefentry>,
15995N/A<
citerefentry><
refentrytitle>libdbus-glib-1</
refentrytitle><
manvolnum>3</
manvolnum></
citerefentry>,
15995N/A<
citerefentry><
refentrytitle>attributes</
refentrytitle><
manvolnum>5</
manvolnum></
citerefentry>
15995N/A<
refsect1 id="rhythmbox-1-note"><
title>¬e-tt;</
title>
17601N/AWritten by Brian Cameron, Sun Microsystems Inc., 2009.