glib/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>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">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>
    <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>monitor</option></term>
        <listitem><para>
          Monitors one or all objects owned by the owned 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>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>
<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.ConsoleKit --object-path /org/freedesktop/ConsoleKit/Session2
Monitoring signals on object /org/freedesktop/ConsoleKit/Session2 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/Session2: org.freedesktop.ConsoleKit.Session.ActiveChanged (true,)
</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>