| <refentry id="gdbus" lang="en"> |
| |
| <refentryinfo> |
| <title>gdbus</title> |
| <productname>GIO</productname> |
| <authorgroup> |
| <author> |
| <contrib>Developer</contrib> |
| <firstname>David</firstname> |
| <surname>Zeuthen</surname> |
| <email>zeuthen@gmail.com</email> |
| </author> |
| </authorgroup> |
| </refentryinfo> |
| |
| <refmeta> |
| <refentrytitle>gdbus</refentrytitle> |
| <manvolnum>1</manvolnum> |
| <refmiscinfo class="manual">User Commands</refmiscinfo> |
| </refmeta> |
| |
| <refnamediv> |
| <refname>gdbus</refname> |
| <refpurpose>Tool for working with D-Bus objects</refpurpose> |
| </refnamediv> |
| |
| <refsynopsisdiv> |
| <cmdsynopsis> |
| <command>gdbus</command> |
| <arg choice="plain">introspect</arg> |
| <group> |
| <arg choice="plain">--system</arg> |
| <arg choice="plain">--session</arg> |
| <arg choice="plain">--address <replaceable>address</replaceable></arg> |
| </group> |
| <arg choice="plain">--dest <replaceable>bus_name</replaceable></arg> |
| <arg choice="plain">--object-path <replaceable>/path/to/object</replaceable></arg> |
| <group> |
| <arg choice="plain">--xml</arg> |
| </group> |
| <group> |
| <arg choice="plain">--recurse</arg> |
| </group> |
| <group> |
| <arg choice="plain">--only-properties</arg> |
| </group> |
| </cmdsynopsis> |
| <cmdsynopsis> |
| <command>gdbus</command> |
| <arg choice="plain">monitor</arg> |
| <group> |
| <arg choice="plain">--system</arg> |
| <arg choice="plain">--session</arg> |
| <arg choice="plain">--address <replaceable>address</replaceable></arg> |
| </group> |
| <arg choice="plain">--dest <replaceable>bus_name</replaceable></arg> |
| <group> |
| <arg choice="plain">--object-path <replaceable>/path/to/object</replaceable></arg> |
| </group> |
| </cmdsynopsis> |
| <cmdsynopsis> |
| <command>gdbus</command> |
| <arg choice="plain">call</arg> |
| <group> |
| <arg choice="plain">--system</arg> |
| <arg choice="plain">--session</arg> |
| <arg choice="plain">--address <replaceable>address</replaceable></arg> |
| </group> |
| <arg choice="plain">--dest <replaceable>bus_name</replaceable></arg> |
| <arg choice="plain">--object-path <replaceable>/path/to/object</replaceable></arg> |
| <arg choice="plain">--method <replaceable>org.project.InterfaceName.MethodName</replaceable></arg> |
| <group> |
| <arg choice="plain">--timeout <replaceable>seconds</replaceable></arg> |
| </group> |
| <arg choice="plain">ARG1</arg> |
| <arg choice="plain" rep="repeat">ARG2</arg> |
| </cmdsynopsis> |
| <cmdsynopsis> |
| <command>gdbus</command> |
| <arg choice="plain">emit</arg> |
| <group> |
| <arg choice="plain">--system</arg> |
| <arg choice="plain">--session</arg> |
| <arg choice="plain">--address <replaceable>address</replaceable></arg> |
| </group> |
| <arg choice="plain">--object-path <replaceable>/path/to/object</replaceable></arg> |
| <arg choice="plain">--signal <replaceable>org.project.InterfaceName.SignalName</replaceable></arg> |
| <group> |
| <arg choice="plain">--dest <replaceable>unique_bus_name</replaceable></arg> |
| </group> |
| <arg choice="plain">ARG1</arg> |
| <arg choice="plain" rep="repeat">ARG2</arg> |
| </cmdsynopsis> |
| <cmdsynopsis> |
| <command>gdbus</command> |
| <arg choice="plain">wait</arg> |
| <group> |
| <arg choice="plain">--system</arg> |
| <arg choice="plain">--session</arg> |
| <arg choice="plain">--address <replaceable>address</replaceable></arg> |
| </group> |
| <arg choice="plain">--activate <replaceable>bus_name</replaceable></arg> |
| <group> |
| <arg choice="plain">--timeout <replaceable>seconds</replaceable></arg> |
| </group> |
| <arg choice="plain"><replaceable>bus_name</replaceable></arg> |
| </cmdsynopsis> |
| <cmdsynopsis> |
| <command>gdbus</command> |
| <arg choice="plain">help</arg> |
| </cmdsynopsis> |
| </refsynopsisdiv> |
| |
| <refsect1> |
| <title>Description</title> |
| <para> |
| <command>gdbus</command> is a simple tool for working with D-Bus objects. |
| </para> |
| </refsect1> |
| <refsect1> |
| <title>Commands</title> |
| <variablelist> |
| <varlistentry> |
| <term><option>introspect</option></term> |
| <listitem><para> |
| Prints out interfaces and property values for a remote object. |
| For this to work, the owner of the object needs to implement the |
| <literal>org.freedesktop.DBus.Introspectable</literal> interface. |
| If the <option>--xml</option> option is used, the returned |
| introspection XML is printed, otherwise a parsed pretty |
| representation is printed. |
| The <option>--recurse</option> option can be used to |
| introspect children (and their children and so on) and the |
| <option>--only-properties</option> option can be used to |
| only print the interfaces with properties. |
| </para></listitem> |
| </varlistentry> |
| <varlistentry> |
| <term><option>monitor</option></term> |
| <listitem><para> |
| Monitors one or all objects owned by the owner of |
| <replaceable>bus_name</replaceable>. |
| </para></listitem> |
| </varlistentry> |
| <varlistentry> |
| <term><option>call</option></term> |
| <listitem><para> |
| Invokes a method on a remote object. Each argument to pass to the |
| method must be specified as a serialized |
| <link linkend="GVariant"><type>GVariant</type></link> except that strings do |
| not need explicit quotes. The return values are printed out as |
| serialized <link linkend="GVariant"><type>GVariant</type></link> |
| values. |
| </para></listitem> |
| </varlistentry> |
| <varlistentry> |
| <term><option>emit</option></term> |
| <listitem><para> |
| Emits a signal. Each argument to include in the signal must be specified as a serialized |
| <link linkend="GVariant"><type>GVariant</type></link> except that strings do |
| not need explicit quotes. |
| </para></listitem> |
| </varlistentry> |
| <varlistentry> |
| <term><option>wait</option></term> |
| <listitem><para> |
| Waits until <replaceable>bus_name</replaceable> is owned by some |
| process on the bus. If the <option>--activate</option> is specified, |
| that bus name will be auto-started first. It may be the same as the |
| bus name being waited for, or different. |
| </para></listitem> |
| </varlistentry> |
| <varlistentry> |
| <term><option>help</option></term> |
| <listitem><para> |
| Prints help and exit. |
| </para></listitem> |
| </varlistentry> |
| </variablelist> |
| </refsect1> |
| |
| <refsect1> |
| <title>Bash Completion</title> |
| <para> |
| <command>gdbus</command> ships with a bash completion script to |
| complete commands, destinations, bus names, object paths and |
| interface/method names. |
| </para> |
| </refsect1> |
| |
| <refsect1> |
| <title>Examples</title> |
| This shows how to introspect an object - note that the value of each |
| property is displayed: |
| <programlisting> |
| $ gdbus introspect --system \ |
| --dest org.freedesktop.NetworkManager \ |
| --object-path /org/freedesktop/NetworkManager/Devices/0 |
| node /org/freedesktop/NetworkManager/Devices/0 { |
| interface org.freedesktop.DBus.Introspectable { |
| methods: |
| Introspect(out s data); |
| }; |
| interface org.freedesktop.DBus.Properties { |
| methods: |
| Get(in s interface, |
| in s propname, |
| out v value); |
| Set(in s interface, |
| in s propname, |
| in v value); |
| GetAll(in s interface, |
| out a{sv} props); |
| }; |
| interface org.freedesktop.NetworkManager.Device.Wired { |
| signals: |
| PropertiesChanged(a{sv} arg_0); |
| properties: |
| readonly b Carrier = false; |
| readonly u Speed = 0; |
| readonly s HwAddress = '00:1D:72:88:BE:97'; |
| }; |
| interface org.freedesktop.NetworkManager.Device { |
| methods: |
| Disconnect(); |
| signals: |
| StateChanged(u arg_0, |
| u arg_1, |
| u arg_2); |
| properties: |
| readonly u DeviceType = 1; |
| readonly b Managed = true; |
| readwrite o Ip6Config = '/'; |
| readwrite o Dhcp4Config = '/'; |
| readwrite o Ip4Config = '/'; |
| readonly u State = 2; |
| readwrite u Ip4Address = 0; |
| readonly u Capabilities = 3; |
| readonly s Driver = 'e1000e'; |
| readwrite s Interface = 'eth0'; |
| readonly s Udi = '/sys/devices/pci0000:00/0000:00:19.0/net/eth0'; |
| }; |
| }; |
| </programlisting> |
| <para> |
| The <option>--recurse</option> and <option>--only-properties</option> options can be useful when wanting to inspect all objects owned by a particular process: |
| </para> |
| <programlisting> |
| $ gdbus introspect --system --dest org.freedesktop.UPower --object-path / --recurse --only-properties |
| node / { |
| node /org { |
| node /org/freedesktop { |
| node /org/freedesktop/UPower { |
| interface org.freedesktop.UPower { |
| properties: |
| readonly b IsDocked = true; |
| readonly b LidForceSleep = false; |
| readonly b LidIsPresent = false; |
| readonly b LidIsClosed = false; |
| readonly b OnLowBattery = false; |
| readonly b OnBattery = false; |
| readonly b CanHibernate = true; |
| readonly b CanSuspend = true; |
| readonly s DaemonVersion = '0.9.10'; |
| }; |
| node /org/freedesktop/UPower/Policy { |
| }; |
| node /org/freedesktop/UPower/Wakeups { |
| interface org.freedesktop.UPower.Wakeups { |
| properties: |
| readonly b HasCapability = true; |
| }; |
| }; |
| }; |
| }; |
| }; |
| }; |
| </programlisting> |
| <para> |
| In a similar fashion, the <option>introspect</option> command can be |
| used to learn details about the <literal>Notify</literal> method: |
| </para> |
| <programlisting> |
| [...] |
| interface org.freedesktop.Notifications { |
| methods: |
| GetServerInformation(out s return_name, |
| out s return_vendor, |
| out s return_version, |
| out s return_spec_version); |
| GetCapabilities(out as return_caps); |
| CloseNotification(in u id); |
| Notify(in s app_name, |
| in u id, |
| in s icon, |
| in s summary, |
| in s body, |
| in as actions, |
| in a{sv} hints, |
| in i timeout, |
| out u return_id); |
| }; |
| [...] |
| </programlisting> |
| <para> |
| With this information, it's easy to use the <option>call</option> |
| command to display a notification |
| </para> |
| <programlisting> |
| $ gdbus call --session \ |
| --dest org.freedesktop.Notifications \ |
| --object-path /org/freedesktop/Notifications \ |
| --method org.freedesktop.Notifications.Notify \ |
| my_app_name \ |
| 42 \ |
| gtk-dialog-info \ |
| "The Summary" \ |
| "Here's the body of the notification" \ |
| [] \ |
| {} \ |
| 5000 |
| (uint32 12,) |
| </programlisting> |
| <para> |
| Monitoring all objects on a service: |
| </para> |
| <programlisting> |
| $ gdbus monitor --system --dest org.freedesktop.ConsoleKit |
| Monitoring signals from all objects owned by org.freedesktop.ConsoleKit |
| The name org.freedesktop.ConsoleKit is owned by :1.15 |
| /org/freedesktop/ConsoleKit/Session2: org.freedesktop.ConsoleKit.Session.ActiveChanged (false,) |
| /org/freedesktop/ConsoleKit/Seat1: org.freedesktop.ConsoleKit.Seat.ActiveSessionChanged ('',) |
| /org/freedesktop/ConsoleKit/Session2: org.freedesktop.ConsoleKit.Session.ActiveChanged (true,) |
| /org/freedesktop/ConsoleKit/Seat1: org.freedesktop.ConsoleKit.Seat.ActiveSessionChanged ('/org/freedesktop/ConsoleKit/Session2',) |
| </programlisting> |
| <para> |
| Monitoring a single object on a service: |
| </para> |
| <programlisting> |
| $ gdbus monitor --system --dest org.freedesktop.NetworkManager --object-path /org/freedesktop/NetworkManager/AccessPoint/4141 |
| Monitoring signals on object /org/freedesktop/NetworkManager/AccessPoint/4141 owned by org.freedesktop.NetworkManager |
| The name org.freedesktop.NetworkManager is owned by :1.5 |
| /org/freedesktop/NetworkManager/AccessPoint/4141: org.freedesktop.NetworkManager.AccessPoint.PropertiesChanged ({'Strength': <byte 0x5c>},) |
| /org/freedesktop/NetworkManager/AccessPoint/4141: org.freedesktop.NetworkManager.AccessPoint.PropertiesChanged ({'Strength': <byte 0x64>},) |
| /org/freedesktop/NetworkManager/AccessPoint/4141: org.freedesktop.NetworkManager.AccessPoint.PropertiesChanged ({'Strength': <byte 0x5e>},) |
| /org/freedesktop/NetworkManager/AccessPoint/4141: org.freedesktop.NetworkManager.AccessPoint.PropertiesChanged ({'Strength': <byte 0x64>},) |
| </programlisting> |
| |
| <para> |
| Emitting a signal: |
| </para> |
| <programlisting> |
| $ gdbus emit --session --object-path /foo --signal org.bar.Foo "['foo', 'bar', 'baz']" |
| </programlisting> |
| |
| <para> |
| Emitting a signal to a specific process: |
| </para> |
| <programlisting> |
| $ gdbus emit --session --object-path /bar --signal org.bar.Bar someString --dest :1.42 |
| </programlisting> |
| |
| <para> |
| Waiting for a well-known name to be owned on the bus; this will |
| <emphasis>not</emphasis> auto-start the service: |
| </para> |
| <programlisting> |
| $ gdbus wait --session org.bar.SomeName |
| </programlisting> |
| |
| <para> |
| Auto-starting then waiting for a well-known name to be owned on the bus: |
| </para> |
| <programlisting> |
| $ gdbus wait --session --activate org.bar.SomeName |
| </programlisting> |
| |
| <para> |
| Auto-starting a different service, then waiting for a well-known name to be |
| owned on the bus. This is useful in situations where |
| <replaceable>SomeName</replaceable> is not directly activatable: |
| </para> |
| <programlisting> |
| $ gdbus wait --session --activate org.bar.PrerequisiteName org.bar.SomeName |
| </programlisting> |
| |
| <para> |
| Waiting for a well-known name and giving up after 30 seconds. By default, |
| the timeout is disabled; or set <option>--timeout</option> to 0 to disable it: |
| </para> |
| <programlisting> |
| $ gdbus wait --session --timeout 30 org.bar.SomeName |
| </programlisting> |
| |
| </refsect1> |
| |
| <refsect1> |
| <title>Bugs</title> |
| <para> |
| Please send bug reports to either the distribution bug tracker |
| or the upstream bug tracker at |
| <ulink url="https://gitlab.gnome.org/GNOME/glib/issues/new"/>. |
| </para> |
| </refsect1> |
| |
| <refsect1> |
| <title>See Also</title> |
| <para> |
| <citerefentry> |
| <refentrytitle>dbus-send</refentrytitle><manvolnum>1</manvolnum> |
| </citerefentry> |
| </para> |
| </refsect1> |
| |
| </refentry> |
| |
