docs/reference/gio/gdbus.xml

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