mirror of
https://gitlab.gnome.org/GNOME/glib.git
synced 2024-11-10 19:36:18 +01:00
7890573f6e
This is effectively the mc-wait-for-name tool from telepathy-mission-control; moving it in to gdbus-tool will make it more widely useful without making people depend on telepathy-mission-control for no other reason. The code here is reimplemented from scratch to use GDBus. It blocks until the specified well-known name is owned by some process on the bus (which can be the session, system, or any other bus). By passing --activate, the same (or a different) name can be auto-started on the bus first. A timeout can be specified to ensure the process doesn’t block forever. https://bugzilla.gnome.org/show_bug.cgi?id=745971
417 lines
14 KiB
XML
417 lines
14 KiB
XML
<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://bugzilla.gnome.org/enter_bug.cgi?product=glib"/>.
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>See Also</title>
|
|
<para>
|
|
<citerefentry>
|
|
<refentrytitle>dbus-send</refentrytitle><manvolnum>1</manvolnum>
|
|
</citerefentry>
|
|
</para>
|
|
</refsect1>
|
|
|
|
</refentry>
|
|
|