Default page

View File Name : gdbus.html

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>gdbus: GIO Reference Manual</title>
<meta name="generator" content="DocBook XSL Stylesheets V1.79.1">
<link rel="home" href="index.html" title="GIO Reference Manual">
<link rel="up" href="tools.html" title="GIO Tools">
<link rel="prev" href="glib-compile-resources.html" title="glib-compile-resources">
<link rel="next" href="gdbus-codegen.html" title="gdbus-codegen">
<meta name="generator" content="GTK-Doc V1.32 (XML mode)">
<link rel="stylesheet" href="style.css" type="text/css">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="5"><tr valign="middle">
<td width="100%" align="left" class="shortcuts"></td>
<td><a accesskey="h" href="index.html"><img src="home.png" width="16" height="16" border="0" alt="Home"></a></td>
<td><a accesskey="u" href="tools.html"><img src="up.png" width="16" height="16" border="0" alt="Up"></a></td>
<td><a accesskey="p" href="glib-compile-resources.html"><img src="left.png" width="16" height="16" border="0" alt="Prev"></a></td>
<td><a accesskey="n" href="gdbus-codegen.html"><img src="right.png" width="16" height="16" border="0" alt="Next"></a></td>
</tr></table>
<div lang="en" class="refentry">
<a name="gdbus"></a><div class="titlepage"></div>
<div class="refnamediv"><table width="100%"><tr>
<td valign="top">
<h2><span class="refentrytitle">gdbus</span></h2>
<p>gdbus — Tool for working with D-Bus objects</p>
</td>
<td class="gallery_image" valign="top" align="right"></td>
</tr></table></div>
<div class="refsynopsisdiv">
<h2>Synopsis</h2>
<div class="cmdsynopsis"><p><code class="command">gdbus</code>   introspect  [ --system  |   --session  |   --address <em class="replaceable"><code>address</code></em> ]  --dest <em class="replaceable"><code>bus_name</code></em>   --object-path <em class="replaceable"><code>/path/to/object</code></em>  [ --xml ] [ --recurse ] [ --only-properties ]</p></div>
<div class="cmdsynopsis"><p><code class="command">gdbus</code>   monitor  [ --system  |   --session  |   --address <em class="replaceable"><code>address</code></em> ]  --dest <em class="replaceable"><code>bus_name</code></em>  [ --object-path <em class="replaceable"><code>/path/to/object</code></em> ]</p></div>
<div class="cmdsynopsis"><p><code class="command">gdbus</code>   call  [ --system  |   --session  |   --address <em class="replaceable"><code>address</code></em> ]  --dest <em class="replaceable"><code>bus_name</code></em>   --object-path <em class="replaceable"><code>/path/to/object</code></em>   --method <em class="replaceable"><code>org.project.InterfaceName.MethodName</code></em>  [ --timeout <em class="replaceable"><code>seconds</code></em> ]  ARG1   ARG2... </p></div>
<div class="cmdsynopsis"><p><code class="command">gdbus</code>   emit  [ --system  |   --session  |   --address <em class="replaceable"><code>address</code></em> ]  --object-path <em class="replaceable"><code>/path/to/object</code></em>   --signal <em class="replaceable"><code>org.project.InterfaceName.SignalName</code></em>  [ --dest <em class="replaceable"><code>unique_bus_name</code></em> ]  ARG1   ARG2... </p></div>
<div class="cmdsynopsis"><p><code class="command">gdbus</code>   wait  [ --system  |   --session  |   --address <em class="replaceable"><code>address</code></em> ]  --activate <em class="replaceable"><code>bus_name</code></em>  [ --timeout <em class="replaceable"><code>seconds</code></em> ]  <em class="replaceable"><code>bus_name</code></em> </p></div>
<div class="cmdsynopsis"><p><code class="command">gdbus</code>   help </p></div>
</div>
<div class="refsect1">
<a name="id-1.4.25.6.5"></a><h2>Description</h2>
<p>
    <span class="command"><strong>gdbus</strong></span> is a simple tool for working with D-Bus objects.
  </p>
</div>
<div class="refsect1">
<a name="id-1.4.25.6.6"></a><h2>Commands</h2>
<div class="variablelist"><table border="0" class="variablelist">
<colgroup>
<col align="left" valign="top">
<col>
</colgroup>
<tbody>
<tr>
<td><p><span class="term"><code class="option">introspect</code></span></p></td>
<td><p>
          Prints out interfaces and property values for a remote object.
          For this to work, the owner of the object needs to implement the
          <code class="literal">org.freedesktop.DBus.Introspectable</code> interface.
          If the <code class="option">--xml</code> option is used, the returned
          introspection XML is printed, otherwise a parsed pretty
          representation is printed.
          The <code class="option">--recurse</code> option can be used to
          introspect children (and their children and so on) and the
          <code class="option">--only-properties</code> option can be used to
          only print the interfaces with properties.
          </p></td>
</tr>
<tr>
<td><p><span class="term"><code class="option">monitor</code></span></p></td>
<td><p>
          Monitors one or all objects owned by the owner of
          <em class="replaceable"><code>bus_name</code></em>.
        </p></td>
</tr>
<tr>
<td><p><span class="term"><code class="option">call</code></span></p></td>
<td><p>
          Invokes a method on a remote object.  Each argument to pass to the
          method must be specified as a serialized
          <span class="type">GVariant</span> except that strings do
          not need explicit quotes. The return values are printed out as
          serialized <span class="type">GVariant</span>
          values.
        </p></td>
</tr>
<tr>
<td><p><span class="term"><code class="option">emit</code></span></p></td>
<td><p>
          Emits a signal. Each argument to include in the signal must be specified as a serialized
          <span class="type">GVariant</span> except that strings do
          not need explicit quotes.
        </p></td>
</tr>
<tr>
<td><p><span class="term"><code class="option">wait</code></span></p></td>
<td><p>
          Waits until <em class="replaceable"><code>bus_name</code></em> is owned by some
          process on the bus. If the <code class="option">--activate</code> is specified,
          that bus name will be auto-started first. It may be the same as the
          bus name being waited for, or different.
        </p></td>
</tr>
<tr>
<td><p><span class="term"><code class="option">help</code></span></p></td>
<td><p>
          Prints help and exit.
        </p></td>
</tr>
</tbody>
</table></div>
</div>
<div class="refsect1">
<a name="id-1.4.25.6.7"></a><h2>Bash Completion</h2>
<p>
    <span class="command"><strong>gdbus</strong></span> ships with a bash completion script to
    complete commands, destinations, bus names, object paths and
    interface/method names.
  </p>
</div>
<div class="refsect1">
<a name="id-1.4.25.6.8"></a><h2>Examples</h2>
  This shows how to introspect an object - note that the value of each
  property is displayed:
<pre class="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';
  };
};
</pre>
<p>
  The <code class="option">--recurse</code> and <code class="option">--only-properties</code> options can be useful when wanting to inspect all objects owned by a particular process:
</p>
<pre class="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;
          };
        };
      };
    };
  };
};
</pre>
<p>
  In a similar fashion, the <code class="option">introspect</code> command can be
  used to learn details about the <code class="literal">Notify</code> method:
</p>
<pre class="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);
  };
[...]
</pre>
<p>
  With this information, it's easy to use the <code class="option">call</code>
  command to display a notification
</p>
<pre class="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,)
</pre>
<p>
  Monitoring all objects on a service:
</p>
<pre class="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',)
</pre>
<p>
  Monitoring a single object on a service:
</p>
<pre class="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;},)
</pre>
<p>
  Emitting a signal:
</p>
<pre class="programlisting">
$ gdbus emit --session --object-path /foo --signal org.bar.Foo "['foo', 'bar', 'baz']"
</pre>
<p>
  Emitting a signal to a specific process:
</p>
<pre class="programlisting">
$ gdbus emit --session --object-path /bar --signal org.bar.Bar someString --dest :1.42
</pre>
<p>
  Waiting for a well-known name to be owned on the bus; this will
  <span class="emphasis"><em>not</em></span> auto-start the service:
</p>
<pre class="programlisting">
$ gdbus wait --session org.bar.SomeName
</pre>
<p>
  Auto-starting then waiting for a well-known name to be owned on the bus:
</p>
<pre class="programlisting">
$ gdbus wait --session --activate org.bar.SomeName
</pre>
<p>
  Auto-starting a different service, then waiting for a well-known name to be
  owned on the bus. This is useful in situations where
  <em class="replaceable"><code>SomeName</code></em> is not directly activatable:
</p>
<pre class="programlisting">
$ gdbus wait --session --activate org.bar.PrerequisiteName org.bar.SomeName
</pre>
<p>
  Waiting for a well-known name and giving up after 30 seconds. By default,
  the timeout is disabled; or set <code class="option">--timeout</code> to 0 to disable it:
</p>
<pre class="programlisting">
$ gdbus wait --session --timeout 30 org.bar.SomeName
</pre>
</div>
<div class="refsect1">
<a name="id-1.4.25.6.9"></a><h2>Bugs</h2>
<p>
    Please send bug reports to either the distribution bug tracker
    or the upstream bug tracker at
    <a class="ulink" href="https://gitlab.gnome.org/GNOME/glib/issues/new" target="_top">https://gitlab.gnome.org/GNOME/glib/issues/new</a>.
  </p>
</div>
<div class="refsect1">
<a name="id-1.4.25.6.10"></a><h2>See Also</h2>
<p>
    <span class="citerefentry"><span class="refentrytitle">dbus-send</span>(1)</span>
  </p>
</div>
</div>
<div class="footer">
<hr>Generated by GTK-Doc V1.32</div>
</body>
</html>