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