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