docs/reference/gio/gdbus.xml

   1 <refentry id="gdbus" lang="en">
   2
   3 <refmeta>
   4   <refentrytitle>gdbus</refentrytitle>
   5   <manvolnum>1</manvolnum>
   6   <refmiscinfo class="manual">User Commands</refmiscinfo>
   7 </refmeta>
   8
   9 <refnamediv>
  10   <refname>gdbus</refname>
  11   <refpurpose>Tool for working with D-Bus objects</refpurpose>
  12 </refnamediv>
  13
  14 <refsynopsisdiv>
  15   <cmdsynopsis>
  16     <command>gdbus</command>
  17     <arg choice="plain">introspect</arg>
  18     <group>
  19       <arg choice="plain">--system</arg>
  20       <arg choice="plain">--session</arg>
  21       <arg choice="plain">--address <replaceable>address</replaceable></arg>
  22     </group>
  23     <arg choice="plain">--dest <replaceable>bus_name</replaceable></arg>
  24     <arg choice="plain">--object-path <replaceable>/path/to/object</replaceable></arg>
  25     <group>
  26       <arg choice="plain">--xml</arg>
  27     </group>
  28     <group>
  29       <arg choice="plain">--recurse</arg>
  30     </group>
  31     <group>
  32       <arg choice="plain">--only-properties</arg>
  33     </group>
  34   </cmdsynopsis>
  35   <cmdsynopsis>
  36     <command>gdbus</command>
  37     <arg choice="plain">monitor</arg>
  38     <group>
  39       <arg choice="plain">--system</arg>
  40       <arg choice="plain">--session</arg>
  41       <arg choice="plain">--address <replaceable>address</replaceable></arg>
  42     </group>
  43     <arg choice="plain">--dest <replaceable>bus_name</replaceable></arg>
  44     <group>
  45       <arg choice="plain">--object-path <replaceable>/path/to/object</replaceable></arg>
  46     </group>
  47   </cmdsynopsis>
  48   <cmdsynopsis>
  49     <command>gdbus</command>
  50     <arg choice="plain">call</arg>
  51     <group>
  52       <arg choice="plain">--system</arg>
  53       <arg choice="plain">--session</arg>
  54       <arg choice="plain">--address <replaceable>address</replaceable></arg>
  55     </group>
  56     <arg choice="plain">--dest <replaceable>bus_name</replaceable></arg>
  57     <arg choice="plain">--object-path <replaceable>/path/to/object</replaceable></arg>
  58     <arg choice="plain">--method <replaceable>org.project.InterfaceName.MethodName</replaceable></arg>
  59     <group>
  60       <arg choice="plain">--timeout <replaceable>seconds</replaceable></arg>
  61     </group>
  62     <arg choice="plain">ARG1</arg>
  63     <arg choice="plain" rep="repeat">ARG2</arg>
  64   </cmdsynopsis>
  65   <cmdsynopsis>
  66     <command>gdbus</command>
  67     <arg choice="plain">emit</arg>
  68     <group>
  69       <arg choice="plain">--system</arg>
  70       <arg choice="plain">--session</arg>
  71       <arg choice="plain">--address <replaceable>address</replaceable></arg>
  72     </group>
  73     <arg choice="plain">--object-path <replaceable>/path/to/object</replaceable></arg>
  74     <arg choice="plain">--signal <replaceable>org.project.InterfaceName.SignalName</replaceable></arg>
  75     <group>
  76       <arg choice="plain">--dest <replaceable>unique_bus_name</replaceable></arg>
  77     </group>
  78     <arg choice="plain">ARG1</arg>
  79     <arg choice="plain" rep="repeat">ARG2</arg>
  80   </cmdsynopsis>
  81   <cmdsynopsis>
  82     <command>gdbus</command>
  83     <arg choice="plain">help</arg>
  84   </cmdsynopsis>
  85 </refsynopsisdiv>
  86
  87 <refsect1>
  88   <title>Description</title>
  89   <para>
  90     <command>gdbus</command> is a simple tool for working with D-Bus objects.
  91   </para>
  92   <refsect2>
  93     <title>Commands</title>
  94     <variablelist>
  95       <varlistentry>
  96         <term><option>introspect</option></term>
  97         <listitem><para>
  98           Prints out interfaces and property values for a remote object.
  99           For this to work, the owner of the object needs to implement the
 100           <literal>org.freedesktop.DBus.Introspectable</literal> interface.
 101           If the <option>--xml</option> option is used, the returned
 102           introspection XML is printed, otherwise a parsed pretty
 103           representation is printed.
 104           The <option>--recurse</option> option can be used to
 105           introspect children (and their children and so on) and the
 106           <option>--only-properties</option> option can be used to
 107           only print the interfaces with properties.
 108           </para></listitem>
 109       </varlistentry>
 110       <varlistentry>
 111         <term><option>monitor</option></term>
 112         <listitem><para>
 113           Monitors one or all objects owned by the owner of
 114           <replaceable>bus_name</replaceable>.
 115         </para></listitem>
 116       </varlistentry>
 117       <varlistentry>
 118         <term><option>call</option></term>
 119         <listitem><para>
 120           Invokes a method on a remote object.  Each argument to pass to the
 121           method must be specified as a serialized
 122           <link linkend="GVariant"><type>GVariant</type></link> except that strings do
 123           not need explicit quotes. The return values are printed out as
 124           serialized <link linkend="GVariant"><type>GVariant</type></link>
 125           values.
 126         </para></listitem>
 127       </varlistentry>
 128       <varlistentry>
 129         <term><option>emit</option></term>
 130         <listitem><para>
 131           Emits a signal. Each argument to include in the signal must be specified as a serialized
 132           <link linkend="GVariant"><type>GVariant</type></link> except that strings do
 133           not need explicit quotes.
 134         </para></listitem>
 135       </varlistentry>
 136       <varlistentry>
 137         <term><option>help</option></term>
 138         <listitem><para>
 139           Prints help and exit.
 140         </para></listitem>
 141       </varlistentry>
 142     </variablelist>
 143   </refsect2>
 144 </refsect1>
 145
 146 <refsect1>
 147   <title>Bash Completion</title>
 148   <para>
 149     <command>gdbus</command> ships with a bash completion script to
 150     complete commands, destinations, bus names, object paths and
 151     interface/method names.
 152   </para>
 153 </refsect1>
 154
 155 <refsect1>
 156   <title>Examples</title>
 157   This shows how to introspect an object - note that the value of each
 158   property is displayed:
 159 <programlisting>
 160 $ gdbus introspect --system \
 161         --dest org.freedesktop.NetworkManager \
 162         --object-path /org/freedesktop/NetworkManager/Devices/0
 163 node /org/freedesktop/NetworkManager/Devices/0 {
 164   interface org.freedesktop.DBus.Introspectable {
 165     methods:
 166       Introspect(out s data);
 167   };
 168   interface org.freedesktop.DBus.Properties {
 169     methods:
 170       Get(in  s interface,
 171           in  s propname,
 172           out v value);
 173       Set(in  s interface,
 174           in  s propname,
 175           in  v value);
 176       GetAll(in  s interface,
 177              out a{sv} props);
 178   };
 179   interface org.freedesktop.NetworkManager.Device.Wired {
 180     signals:
 181       PropertiesChanged(a{sv} arg_0);
 182     properties:
 183       readonly b Carrier = false;
 184       readonly u Speed = 0;
 185       readonly s HwAddress = '00:1D:72:88:BE:97';
 186   };
 187   interface org.freedesktop.NetworkManager.Device {
 188     methods:
 189       Disconnect();
 190     signals:
 191       StateChanged(u arg_0,
 192                    u arg_1,
 193                    u arg_2);
 194     properties:
 195       readonly u DeviceType = 1;
 196       readonly b Managed = true;
 197       readwrite o Ip6Config = '/';
 198       readwrite o Dhcp4Config = '/';
 199       readwrite o Ip4Config = '/';
 200       readonly u State = 2;
 201       readwrite u Ip4Address = 0;
 202       readonly u Capabilities = 3;
 203       readonly s Driver = 'e1000e';
 204       readwrite s Interface = 'eth0';
 205       readonly s Udi = '/sys/devices/pci0000:00/0000:00:19.0/net/eth0';
 206   };
 207 };
 208 </programlisting>
 209 <para>
 210   The <option>--recurse</option> and <option>--only-properties</option> options can be useful when wanting to inspect all objects owned by a particular process:
 211 </para>
 212 <programlisting>
 213 $ gdbus introspect --system --dest org.freedesktop.UPower --object-path / --recurse  --only-properties
 214 node / {
 215   node /org {
 216     node /org/freedesktop {
 217       node /org/freedesktop/UPower {
 218         interface org.freedesktop.UPower {
 219           properties:
 220             readonly b IsDocked = true;
 221             readonly b LidForceSleep = false;
 222             readonly b LidIsPresent = false;
 223             readonly b LidIsClosed = false;
 224             readonly b OnLowBattery = false;
 225             readonly b OnBattery = false;
 226             readonly b CanHibernate = true;
 227             readonly b CanSuspend = true;
 228             readonly s DaemonVersion = '0.9.10';
 229         };
 230         node /org/freedesktop/UPower/Policy {
 231         };
 232         node /org/freedesktop/UPower/Wakeups {
 233           interface org.freedesktop.UPower.Wakeups {
 234             properties:
 235               readonly b HasCapability = true;
 236           };
 237         };
 238       };
 239     };
 240   };
 241 };
 242 </programlisting>
 243 <para>
 244   In a similar fashion, the <option>introspect</option> command can be
 245   used to learn details about the <literal>Notify</literal> method:
 246 </para>
 247 <programlisting>
 248 [...]
 249   interface org.freedesktop.Notifications {
 250     methods:
 251       GetServerInformation(out s return_name,
 252                            out s return_vendor,
 253                            out s return_version,
 254                            out s return_spec_version);
 255       GetCapabilities(out as return_caps);
 256       CloseNotification(in  u id);
 257       Notify(in  s app_name,
 258              in  u id,
 259              in  s icon,
 260              in  s summary,
 261              in  s body,
 262              in  as actions,
 263              in  a{sv} hints,
 264              in  i timeout,
 265              out u return_id);
 266   };
 267 [...]
 268 </programlisting>
 269 <para>
 270   With this information, it's easy to use the <option>call</option>
 271   command to display a notification
 272 </para>
 273 <programlisting>
 274 $ gdbus call --session \
 275              --dest org.freedesktop.Notifications \
 276              --object-path /org/freedesktop/Notifications \
 277              --method org.freedesktop.Notifications.Notify \
 278              my_app_name \
 279              42 \
 280              gtk-dialog-info \
 281              "The Summary" \
 282              "Here's the body of the notification" \
 283              [] \
 284              {} \
 285              5000
 286 (uint32 12,)
 287 </programlisting>
 288 <para>
 289   Monitoring all objects on a service:
 290 </para>
 291 <programlisting>
 292 $ gdbus monitor --system --dest org.freedesktop.ConsoleKit
 293 Monitoring signals from all objects owned by org.freedesktop.ConsoleKit
 294 The name org.freedesktop.ConsoleKit is owned by :1.15
 295 /org/freedesktop/ConsoleKit/Session2: org.freedesktop.ConsoleKit.Session.ActiveChanged (false,)
 296 /org/freedesktop/ConsoleKit/Seat1: org.freedesktop.ConsoleKit.Seat.ActiveSessionChanged ('',)
 297 /org/freedesktop/ConsoleKit/Session2: org.freedesktop.ConsoleKit.Session.ActiveChanged (true,)
 298 /org/freedesktop/ConsoleKit/Seat1: org.freedesktop.ConsoleKit.Seat.ActiveSessionChanged ('/org/freedesktop/ConsoleKit/Session2',)
 299 </programlisting>
 300 <para>
 301   Monitoring a single object on a service:
 302 </para>
 303 <programlisting>
 304 $ gdbus monitor --system --dest org.freedesktop.NetworkManager --object-path /org/freedesktop/NetworkManager/AccessPoint/4141
 305 Monitoring signals on object /org/freedesktop/NetworkManager/AccessPoint/4141 owned by org.freedesktop.NetworkManager
 306 The name org.freedesktop.NetworkManager is owned by :1.5
 307 /org/freedesktop/NetworkManager/AccessPoint/4141: org.freedesktop.NetworkManager.AccessPoint.PropertiesChanged ({'Strength': &lt;byte 0x5c&gt;},)
 308 /org/freedesktop/NetworkManager/AccessPoint/4141: org.freedesktop.NetworkManager.AccessPoint.PropertiesChanged ({'Strength': &lt;byte 0x64&gt;},)
 309 /org/freedesktop/NetworkManager/AccessPoint/4141: org.freedesktop.NetworkManager.AccessPoint.PropertiesChanged ({'Strength': &lt;byte 0x5e&gt;},)
 310 /org/freedesktop/NetworkManager/AccessPoint/4141: org.freedesktop.NetworkManager.AccessPoint.PropertiesChanged ({'Strength': &lt;byte 0x64&gt;},)
 311 </programlisting>
 312
 313 <para>
 314   Emitting a signal:
 315 </para>
 316 <programlisting>
 317 $ gdbus emit --session --object-path /foo --signal org.bar.Foo "['foo', 'bar', 'baz']"
 318 </programlisting>
 319
 320 <para>
 321   Emitting a signal to a specific process:
 322 </para>
 323 <programlisting>
 324 $ gdbus emit --session --object-path /bar --signal org.bar.Bar someString --dest :1.42
 325 </programlisting>
 326
 327 </refsect1>
 328
 329 <refsect1>
 330   <title>AUTHOR</title>
 331   <para>
 332     Written by David Zeuthen <email>zeuthen@gmail.com</email> with
 333     a lot of help from many others.
 334   </para>
 335 </refsect1>
 336
 337 <refsect1>
 338   <title>BUGS</title>
 339   <para>
 340     Please send bug reports to either the distribution bug tracker
 341     or the upstream bug tracker at
 342     <ulink url="https://bugzilla.gnome.org/enter_bug.cgi?product=glib"/>.
 343   </para>
 344 </refsect1>
 345
 346 <refsect1>
 347   <title>SEE ALSO</title>
 348   <para>
 349     <citerefentry>
 350       <refentrytitle>dbus-send</refentrytitle><manvolnum>1</manvolnum>
 351     </citerefentry>
 352   </para>
 353 </refsect1>
 354
 355 </refentry>
 356