<refentry id="gdbus" lang="en">
+<refentryinfo>
+ <title>gdbus</title>
+ <productname>GIO</productname>
+ <authorgroup>
+ <author>
+ <contrib>Developer</contrib>
+ <firstname>David</firstname>
+ <surname>Zeuthen</surname>
+ <email>zeuthen@gmail.com</email>
+ </author>
+ </authorgroup>
+</refentryinfo>
+
<refmeta>
<refentrytitle>gdbus</refentrytitle>
<manvolnum>1</manvolnum>
<refnamediv>
<refname>gdbus</refname>
- <refpurpose>Introspect and call remote objects</refpurpose>
+ <refpurpose>Tool for working with D-Bus objects</refpurpose>
</refnamediv>
<refsynopsisdiv>
</group>
<arg choice="plain">--dest <replaceable>bus_name</replaceable></arg>
<arg choice="plain">--object-path <replaceable>/path/to/object</replaceable></arg>
+ <group>
+ <arg choice="plain">--xml</arg>
+ </group>
+ <group>
+ <arg choice="plain">--recurse</arg>
+ </group>
+ <group>
+ <arg choice="plain">--only-properties</arg>
+ </group>
+ </cmdsynopsis>
+ <cmdsynopsis>
+ <command>gdbus</command>
+ <arg choice="plain">monitor</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>
+ <group>
+ <arg choice="plain">--object-path <replaceable>/path/to/object</replaceable></arg>
+ </group>
</cmdsynopsis>
<cmdsynopsis>
<command>gdbus</command>
<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>
+ <group>
+ <arg choice="plain">--timeout <replaceable>seconds</replaceable></arg>
+ </group>
+ <arg choice="plain">ARG1</arg>
+ <arg choice="plain" rep="repeat">ARG2</arg>
+ </cmdsynopsis>
+ <cmdsynopsis>
+ <command>gdbus</command>
+ <arg choice="plain">emit</arg>
+ <group>
+ <arg choice="plain">--system</arg>
+ <arg choice="plain">--session</arg>
+ <arg choice="plain">--address <replaceable>address</replaceable></arg>
+ </group>
+ <arg choice="plain">--object-path <replaceable>/path/to/object</replaceable></arg>
+ <arg choice="plain">--signal <replaceable>org.project.InterfaceName.SignalName</replaceable></arg>
+ <group>
+ <arg choice="plain">--dest <replaceable>unique_bus_name</replaceable></arg>
+ </group>
<arg choice="plain">ARG1</arg>
<arg choice="plain" rep="repeat">ARG2</arg>
</cmdsynopsis>
<refsect1>
<title>Description</title>
<para>
- <command>gdbus</command> offers a simple commandline utility for
- introspecting and calling methods on remote objects.
+ <command>gdbus</command> is a simple tool for working with D-Bus objects.
</para>
- <refsect2>
+</refsect1>
+<refsect1>
<title>Commands</title>
<variablelist>
<varlistentry>
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.
+ If the <option>--xml</option> option is used, the returned
+ introspection XML is printed, otherwise a parsed pretty
+ representation is printed.
+ The <option>--recurse</option> option can be used to
+ introspect children (and their children and so on) and the
+ <option>--only-properties</option> option can be used to
+ only print the interfaces with properties.
+ </para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>monitor</option></term>
+ <listitem><para>
+ Monitors one or all objects owned by the owner of
+ <replaceable>bus_name</replaceable>.
</para></listitem>
</varlistentry>
<varlistentry>
</para></listitem>
</varlistentry>
<varlistentry>
+ <term><option>emit</option></term>
+ <listitem><para>
+ Emits a signal. Each argument to include in the signal must be specified as a serialized
+ <link linkend="GVariant"><type>GVariant</type></link> except that strings do
+ not need explicit quotes.
+ </para></listitem>
+ </varlistentry>
+ <varlistentry>
<term><option>help</option></term>
<listitem><para>
Prints help and exit.
</para></listitem>
</varlistentry>
</variablelist>
- </refsect2>
</refsect1>
<refsect1>
};
</programlisting>
<para>
+ The <option>--recurse</option> and <option>--only-properties</option> options can be useful when wanting to inspect all objects owned by a particular process:
+</para>
+<programlisting>
+$ gdbus introspect --system --dest org.freedesktop.UPower --object-path / --recurse --only-properties
+node / {
+ node /org {
+ node /org/freedesktop {
+ node /org/freedesktop/UPower {
+ interface org.freedesktop.UPower {
+ properties:
+ readonly b IsDocked = true;
+ readonly b LidForceSleep = false;
+ readonly b LidIsPresent = false;
+ readonly b LidIsClosed = false;
+ readonly b OnLowBattery = false;
+ readonly b OnBattery = false;
+ readonly b CanHibernate = true;
+ readonly b CanSuspend = true;
+ readonly s DaemonVersion = '0.9.10';
+ };
+ node /org/freedesktop/UPower/Policy {
+ };
+ node /org/freedesktop/UPower/Wakeups {
+ interface org.freedesktop.UPower.Wakeups {
+ properties:
+ readonly b HasCapability = true;
+ };
+ };
+ };
+ };
+ };
+};
+</programlisting>
+<para>
In a similar fashion, the <option>introspect</option> command can be
used to learn details about the <literal>Notify</literal> method:
</para>
5000
(uint32 12,)
</programlisting>
-</refsect1>
+<para>
+ Monitoring all objects on a service:
+</para>
+<programlisting>
+$ gdbus monitor --system --dest org.freedesktop.ConsoleKit
+Monitoring signals from all objects owned by org.freedesktop.ConsoleKit
+The name org.freedesktop.ConsoleKit is owned by :1.15
+/org/freedesktop/ConsoleKit/Session2: org.freedesktop.ConsoleKit.Session.ActiveChanged (false,)
+/org/freedesktop/ConsoleKit/Seat1: org.freedesktop.ConsoleKit.Seat.ActiveSessionChanged ('',)
+/org/freedesktop/ConsoleKit/Session2: org.freedesktop.ConsoleKit.Session.ActiveChanged (true,)
+/org/freedesktop/ConsoleKit/Seat1: org.freedesktop.ConsoleKit.Seat.ActiveSessionChanged ('/org/freedesktop/ConsoleKit/Session2',)
+</programlisting>
+<para>
+ Monitoring a single object on a service:
+</para>
+<programlisting>
+$ gdbus monitor --system --dest org.freedesktop.NetworkManager --object-path /org/freedesktop/NetworkManager/AccessPoint/4141
+Monitoring signals on object /org/freedesktop/NetworkManager/AccessPoint/4141 owned by org.freedesktop.NetworkManager
+The name org.freedesktop.NetworkManager is owned by :1.5
+/org/freedesktop/NetworkManager/AccessPoint/4141: org.freedesktop.NetworkManager.AccessPoint.PropertiesChanged ({'Strength': <byte 0x5c>},)
+/org/freedesktop/NetworkManager/AccessPoint/4141: org.freedesktop.NetworkManager.AccessPoint.PropertiesChanged ({'Strength': <byte 0x64>},)
+/org/freedesktop/NetworkManager/AccessPoint/4141: org.freedesktop.NetworkManager.AccessPoint.PropertiesChanged ({'Strength': <byte 0x5e>},)
+/org/freedesktop/NetworkManager/AccessPoint/4141: org.freedesktop.NetworkManager.AccessPoint.PropertiesChanged ({'Strength': <byte 0x64>},)
+</programlisting>
+
+<para>
+ Emitting a signal:
+</para>
+<programlisting>
+$ gdbus emit --session --object-path /foo --signal org.bar.Foo "['foo', 'bar', 'baz']"
+</programlisting>
+
+<para>
+ Emitting a signal to a specific process:
+</para>
+<programlisting>
+$ gdbus emit --session --object-path /bar --signal org.bar.Bar someString --dest :1.42
+</programlisting>
-<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>
+ <title>Bugs</title>
<para>
Please send bug reports to either the distribution bug tracker
or the upstream bug tracker at
</refsect1>
<refsect1>
- <title>SEE ALSO</title>
+ <title>See Also</title>
<para>
<citerefentry>
<refentrytitle>dbus-send</refentrytitle><manvolnum>1</manvolnum>