GitLab repository storage has been migrated to hashed layout. Please contact Infrastructure team if you notice any issues with repositories or hooks.

Commit f309334b authored by David Zeuthen's avatar David Zeuthen

GDBus: add a man page for gdbus(1)

parent f14e3081
......@@ -121,7 +121,9 @@ content_files = \
gio-querymodules.xml \
glib-compile-schemas.xml\
gsettings.xml \
gsettings-schema-convert.xml
gsettings-schema-convert.xml \
gdbus.xml \
$(NULL)
expand_content_files = \
overview.xml \
......@@ -143,7 +145,8 @@ man_MANS = \
gio-querymodules.1 \
glib-compile-schemas.1 \
gsettings.1 \
gsettings-schema-convert.1
gsettings-schema-convert.1 \
gdbus.1
if ENABLE_MAN
......
<refentry id="gdbus" lang="en">
<refmeta>
<refentrytitle>gdbus</refentrytitle>
<manvolnum>1</manvolnum>
<refmiscinfo class="manual">User Commands</refmiscinfo>
</refmeta>
<refnamediv>
<refname>gdbus</refname>
<refpurpose>Introspect and call remote objects</refpurpose>
</refnamediv>
<refsynopsisdiv>
<cmdsynopsis>
<command>gdbus</command>
<arg choice="plain">introspect</arg>
<group>
<arg choice="plain">--system</arg>
<arg choice="plain">--session</arg>
<arg choice="plain">--address <replaceable>address</replaceable></arg>
</group>
<arg choice="plain">--dest <replaceable>bus_name</replaceable></arg>
<arg choice="plain">--object-path <replaceable>/path/to/object</replaceable></arg>
</cmdsynopsis>
<cmdsynopsis>
<command>gdbus</command>
<arg choice="plain">call</arg>
<group>
<arg choice="plain">--system</arg>
<arg choice="plain">--session</arg>
<arg choice="plain">--address <replaceable>address</replaceable></arg>
</group>
<arg choice="plain">--dest <replaceable>bus_name</replaceable></arg>
<arg choice="plain">--object-path <replaceable>/path/to/object</replaceable></arg>
<arg choice="plain">--method <replaceable>org.project.InterfaceName.MethodName</replaceable></arg>
<arg choice="plain">ARG1</arg>
<arg choice="plain" rep="repeat">ARG2</arg>
</cmdsynopsis>
<cmdsynopsis>
<command>gdbus</command>
<arg choice="plain">help</arg>
</cmdsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Description</title>
<para>
<command>gdbus</command> offers a simple commandline utility for
introspecting and calling methods on remote objects.
</para>
<refsect2>
<title>Commands</title>
<variablelist>
<varlistentry>
<term><option>introspect</option></term>
<listitem><para>
Prints out interfaces and property values for a remote object.
For this to work, the owner of the object needs to implement the
<literal>org.freedesktop.DBus.Introspectable</literal> interface.
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>call</option></term>
<listitem><para>
Invokes a method on a remote object. Each argument to pass to the
method must be specified as a serialized
<link linkend="GVariant"><type>GVariant</type></link> except that strings do
not need explicit quotes. The return values are printed out as
serialized <link linkend="GVariant"><type>GVariant</type></link>
values.
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>help</option></term>
<listitem><para>
Prints help and exit.
</para></listitem>
</varlistentry>
</variablelist>
</refsect2>
</refsect1>
<refsect1>
<title>Bash Completion</title>
<para>
<command>gdbus</command> ships with a bash completion script to
complete commands, destinations, bus names, object paths and
interface/method names.
</para>
</refsect1>
<refsect1>
<title>Examples</title>
This shows how to introspect an object - note that the value of each
property is displayed:
<programlisting>
$ gdbus introspect --system \
--dest org.freedesktop.NetworkManager \
--object-path /org/freedesktop/NetworkManager/Devices/0
node /org/freedesktop/NetworkManager/Devices/0 {
interface org.freedesktop.DBus.Introspectable {
methods:
Introspect(out s data);
};
interface org.freedesktop.DBus.Properties {
methods:
Get(in s interface,
in s propname,
out v value);
Set(in s interface,
in s propname,
in v value);
GetAll(in s interface,
out a{sv} props);
};
interface org.freedesktop.NetworkManager.Device.Wired {
signals:
PropertiesChanged(a{sv} arg_0);
properties:
readonly b Carrier = false;
readonly u Speed = 0;
readonly s HwAddress = '00:1D:72:88:BE:97';
};
interface org.freedesktop.NetworkManager.Device {
methods:
Disconnect();
signals:
StateChanged(u arg_0,
u arg_1,
u arg_2);
properties:
readonly u DeviceType = 1;
readonly b Managed = true;
readwrite o Ip6Config = '/';
readwrite o Dhcp4Config = '/';
readwrite o Ip4Config = '/';
readonly u State = 2;
readwrite u Ip4Address = 0;
readonly u Capabilities = 3;
readonly s Driver = 'e1000e';
readwrite s Interface = 'eth0';
readonly s Udi = '/sys/devices/pci0000:00/0000:00:19.0/net/eth0';
};
};
</programlisting>
<para>
In a similar fashion, the <option>introspect</option> command can be
used to learn details about the <literal>Notify</literal> method:
</para>
<programlisting>
[...]
interface org.freedesktop.Notifications {
methods:
GetServerInformation(out s return_name,
out s return_vendor,
out s return_version,
out s return_spec_version);
GetCapabilities(out as return_caps);
CloseNotification(in u id);
Notify(in s app_name,
in u id,
in s icon,
in s summary,
in s body,
in as actions,
in a{sv} hints,
in i timeout,
out u return_id);
};
[...]
</programlisting>
<para>
With this information, it's easy to use the <option>call</option>
command to display a notification
</para>
<programlisting>
$ gdbus call --session \
--dest org.freedesktop.Notifications \
--object-path /org/freedesktop/Notifications \
--method org.freedesktop.Notifications.Notify \
my_app_name \
42 \
gtk-dialog-info \
"The Summary" \
"Here's the body of the notification" \
[] \
{} \
5000
(uint32 12,)
</programlisting>
</refsect1>
<refsect1>
<title>AUTHOR</title>
<para>
Written by David Zeuthen <email>zeuthen@gmail.com</email> with
a lot of help from many others.
</para>
</refsect1>
<refsect1>
<title>BUGS</title>
<para>
Please send bug reports to either the distribution bug tracker
or the upstream bug tracker at
<ulink url="https://bugzilla.gnome.org/enter_bug.cgi?product=glib"/>.
</para>
</refsect1>
<refsect1>
<title>SEE ALSO</title>
<para>
<citerefentry>
<refentrytitle>dbus-send</refentrytitle><manvolnum>1</manvolnum>
</citerefentry>
</para>
</refsect1>
</refentry>
......@@ -166,6 +166,7 @@
<xi:include href="gsettings.xml"/>
<xi:include href="glib-compile-schemas.xml"/>
<xi:include href="gsettings-schema-convert.xml"/>
<xi:include href="gdbus.xml"/>
</chapter>
</part>
......
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment