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