path: root/docs/reference/gio/gdbus.xml

<refentry id="gdbus" lang="en">

<refmeta>
  <refentrytitle>gdbus</refentrytitle>
  <manvolnum>1</manvolnum>
  <refmiscinfo class="manual">User Commands</refmiscinfo>
</refmeta>

<refnamediv>
  <refname>gdbus</refname>
  <refpurpose>Tool for working with D-Bus 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>
    <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">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>
    <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>
  <cmdsynopsis>
    <command>gdbus</command>
    <arg choice="plain">help</arg>
  </cmdsynopsis>
</refsynopsisdiv>

<refsect1>
  <title>Description</title>
  <para>
    <command>gdbus</command> is a simple tool for working with D-Bus 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.
          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>
        <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>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>
  <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>
  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>
<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>
<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': &lt;byte 0x5c&gt;},)
/org/freedesktop/NetworkManager/AccessPoint/4141: org.freedesktop.NetworkManager.AccessPoint.PropertiesChanged ({'Strength': &lt;byte 0x64&gt;},)
/org/freedesktop/NetworkManager/AccessPoint/4141: org.freedesktop.NetworkManager.AccessPoint.PropertiesChanged ({'Strength': &lt;byte 0x5e&gt;},)
/org/freedesktop/NetworkManager/AccessPoint/4141: org.freedesktop.NetworkManager.AccessPoint.PropertiesChanged ({'Strength': &lt;byte 0x64&gt;},)
</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>

<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>