glib/docs/reference/gio/gdbus.xml

<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>
  <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">wait</arg>
    <group>
      <arg choice="plain">--system</arg>
      <arg choice="plain">--session</arg>
      <arg choice="plain">--address <replaceable>address</replaceable></arg>
    </group>
    <arg choice="plain">--activate <replaceable>bus_name</replaceable></arg>
    <group>
      <arg choice="plain">--timeout <replaceable>seconds</replaceable></arg>
    </group>
    <arg choice="plain"><replaceable>bus_name</replaceable></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>
</refsect1>
<refsect1>
    <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>wait</option></term>
        <listitem><para>
          Waits until <replaceable>bus_name</replaceable> is owned by some
          process on the bus. If the <option>--activate</option> is specified,
          that bus name will be auto-started first. It may be the same as the
          bus name being waited for, or different.
        </para></listitem>
      </varlistentry>
      <varlistentry>
        <term><option>help</option></term>
        <listitem><para>
          Prints help and exit.
        </para></listitem>
      </varlistentry>
    </variablelist>
</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>

<para>
  Waiting for a well-known name to be owned on the bus; this will
  <emphasis>not</emphasis> auto-start the service:
</para>
<programlisting>
$ gdbus wait --session org.bar.SomeName
</programlisting>

<para>
  Auto-starting then waiting for a well-known name to be owned on the bus:
</para>
<programlisting>
$ gdbus wait --session --activate org.bar.SomeName
</programlisting>

<para>
  Auto-starting a different service, then waiting for a well-known name to be
  owned on the bus. This is useful in situations where
  <replaceable>SomeName</replaceable> is not directly activatable:
</para>
<programlisting>
$ gdbus wait --session --activate org.bar.PrerequisiteName org.bar.SomeName
</programlisting>

<para>
  Waiting for a well-known name and giving up after 30 seconds. By default,
  the timeout is disabled; or set <option>--timeout</option> to 0 to disable it:
</para>
<programlisting>
$ gdbus wait --session --timeout 30 org.bar.SomeName
</programlisting>

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