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