mirror of
https://gitlab.gnome.org/GNOME/glib.git
synced 2024-11-06 09:26:17 +01:00
278 lines
10 KiB
ReStructuredText
278 lines
10 KiB
ReStructuredText
|
.. _gdbus(1):
|
|||
|
|
.. meta::
|
|||
|
|
:copyright: Copyright 2010, 2011, 2012, 2020 Red Hat, Inc.
|
|||
|
|
:copyright: Copyright 2015 Collabora, Ltd.
|
|||
|
|
:copyright: Copyright 2021 Endless OS Foundation, LLC
|
|||
|
|
:license: LGPL-2.1-or-later
|
|||
|
|
..
|
|||
|
|
This has to be duplicated from above to make it machine-readable by `reuse`:
|
|||
|
|
SPDX-FileCopyrightText: 2010, 2011, 2012, 2020 Red Hat, Inc.
|
|||
|
|
SPDX-FileCopyrightText: 2015 Collabora, Ltd.
|
|||
|
|
SPDX-FileCopyrightText: 2021 Endless OS Foundation, LLC
|
|||
|
|
SPDX-License-Identifier: LGPL-2.1-or-later
|
|||
|
|
|
|||
|
|
=====
|
|||
|
|
gdbus
|
|||
|
|
=====
|
|||
|
|
|
|||
|
|
-----------------------------------
|
|||
|
|
Tool for working with D-Bus objects
|
|||
|
|
-----------------------------------
|
|||
|
|
|
|||
|
|
SYNOPSIS
|
|||
|
|
--------
|
|||
|
|
|
|||
|
|
| **gdbus** introspect [--system | --session | --address *address*] --dest *bus_name* --object-path */path/to/object* [--xml] [--recurse] [--only-properties]
|
|||
|
|
| **gdbus** monitor [--system | --session | --address *address*] --dest *bus_name* [--object-path */path/to/object*]
|
|||
|
|
| **gdbus** call [--system | --session | --address *address*] --dest *bus_name* --object-path */path/to/object* --method *org.project.InterfaceName.MethodName* [--timeout *seconds* | --interactive] [*ARG*…]
|
|||
|
|
| **gdbus** emit [--system | --session | --address *address*] --object-path */path/to/object* --signal *org.project.InterfaceName.SignalName* [--dest *unique_bus_name*] [*ARG*…]
|
|||
|
|
| **gdbus** wait [--system | --session | --address *address*] --activate *bus_name* [--timeout *seconds*] *bus_name*
|
|||
|
|
| **gdbus** help
|
|||
|
|
|
|||
|
|
DESCRIPTION
|
|||
|
|
-----------
|
|||
|
|
|
|||
|
|
``gdbus`` is a simple tool for working with D-Bus objects.
|
|||
|
|
|
|||
|
|
COMMANDS
|
|||
|
|
--------
|
|||
|
|
|
|||
|
|
``introspect``
|
|||
|
|
|
|||
|
|
Prints out interfaces and property values for a remote object. For this to
|
|||
|
|
work, the owner of the object needs to implement the
|
|||
|
|
``org.freedesktop.DBus.Introspectable`` interface. If the ``--xml`` option is
|
|||
|
|
used, the returned introspection XML is printed, otherwise a parsed pretty
|
|||
|
|
representation is printed. The ``--recurse`` option can be used to introspect
|
|||
|
|
children (and their children and so on) and the ``--only-properties`` option
|
|||
|
|
can be used to only print the interfaces with properties.
|
|||
|
|
|
|||
|
|
``monitor``
|
|||
|
|
|
|||
|
|
Monitors one or all objects owned by the owner of ``bus_name``.
|
|||
|
|
|
|||
|
|
``call``
|
|||
|
|
|
|||
|
|
Invokes a method on a remote object. Each argument to pass to the method must
|
|||
|
|
be specified as a serialized ``GVariant`` except that strings do not need
|
|||
|
|
explicit quotes. The return values are printed out as serialized ``GVariant``
|
|||
|
|
values.
|
|||
|
|
|
|||
|
|
``emit``
|
|||
|
|
|
|||
|
|
Emits a signal. Each argument to include in the signal must be specified as a
|
|||
|
|
serialized ``GVariant`` except that strings do not need explicit quotes.
|
|||
|
|
|
|||
|
|
``wait``
|
|||
|
|
|
|||
|
|
Waits until ``bus_name`` is owned by some process on the bus. If the
|
|||
|
|
``--activate`` is specified, that bus name will be auto-started first. It may
|
|||
|
|
be the same as the bus name being waited for, or different.
|
|||
|
|
|
|||
|
|
``help``
|
|||
|
|
|
|||
|
|
Prints help and exits.
|
|||
|
|
|
|||
|
|
BASH COMPLETION
|
|||
|
|
---------------
|
|||
|
|
|
|||
|
|
``gdbus`` ships with a bash completion script to complete commands,
|
|||
|
|
destinations, bus names, object paths and interface/method names.
|
|||
|
|
|
|||
|
|
EXAMPLES
|
|||
|
|
--------
|
|||
|
|
|
|||
|
|
This shows how to introspect an object — note that the value of each property is
|
|||
|
|
displayed::
|
|||
|
|
|
|||
|
|
$ 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';
|
|||
|
|
};
|
|||
|
|
};
|
|||
|
|
|
|||
|
|
The ``--recurse`` and ``--only-properties`` options can be useful when wanting
|
|||
|
|
to inspect all objects owned by a particular process::
|
|||
|
|
|
|||
|
|
$ 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;
|
|||
|
|
};
|
|||
|
|
};
|
|||
|
|
};
|
|||
|
|
};
|
|||
|
|
};
|
|||
|
|
};
|
|||
|
|
|
|||
|
|
In a similar fashion, the ``introspect`` command can be used to learn details
|
|||
|
|
about the ``Notify`` method::
|
|||
|
|
|
|||
|
|
[…]
|
|||
|
|
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);
|
|||
|
|
};
|
|||
|
|
[…]
|
|||
|
|
|
|||
|
|
With this information, it’s easy to use the ``call`` command to display a
|
|||
|
|
notification::
|
|||
|
|
|
|||
|
|
$ 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,)
|
|||
|
|
|
|||
|
|
Call a method with file handle argument::
|
|||
|
|
|
|||
|
|
$ gdbus call --session \
|
|||
|
|
--dest org.example.foo \
|
|||
|
|
--object-path /org/example/foo \
|
|||
|
|
--method SendFDs \
|
|||
|
|
1 \
|
|||
|
|
10 \
|
|||
|
|
10<file.foo
|
|||
|
|
|
|||
|
|
Monitoring all objects on a service::
|
|||
|
|
|
|||
|
|
$ 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',)
|
|||
|
|
|
|||
|
|
Monitoring a single object on a service::
|
|||
|
|
|
|||
|
|
$ 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>},)
|
|||
|
|
|
|||
|
|
Emitting a signal::
|
|||
|
|
|
|||
|
|
$ gdbus emit --session --object-path /foo --signal org.bar.Foo "['foo', 'bar', 'baz']"
|
|||
|
|
|
|||
|
|
Emitting a signal to a specific process::
|
|||
|
|
|
|||
|
|
$ gdbus emit --session --object-path /bar --signal org.bar.Bar someString --dest :1.42
|
|||
|
|
|
|||
|
|
Waiting for a well-known name to be owned on the bus; this will *not* auto-start
|
|||
|
|
the service::
|
|||
|
|
|
|||
|
|
$ gdbus wait --session org.bar.SomeName
|
|||
|
|
|
|||
|
|
Auto-starting then waiting for a well-known name to be owned on the bus::
|
|||
|
|
|
|||
|
|
$ gdbus wait --session --activate org.bar.SomeName
|
|||
|
|
|
|||
|
|
Auto-starting a different service, then waiting for a well-known name to be
|
|||
|
|
owned on the bus. This is useful in situations where ``SomeName`` is not
|
|||
|
|
directly activatable::
|
|||
|
|
|
|||
|
|
$ gdbus wait --session --activate org.bar.PrerequisiteName org.bar.SomeName
|
|||
|
|
|
|||
|
|
Waiting for a well-known name and giving up after 30 seconds. By default, the
|
|||
|
|
timeout is disabled; or set ``--timeout`` to ``0`` to disable it::
|
|||
|
|
|
|||
|
|
$ gdbus wait --session --timeout 30 org.bar.SomeName
|
|||
|
|
|
|||
|
|
BUGS
|
|||
|
|
----
|
|||
|
|
|
|||
|
|
Please send bug reports to either the distribution bug tracker or the
|
|||
|
|
`upstream bug tracker <https://gitlab.gnome.org/GNOME/glib/issues/new>`_.
|
|||
|
|
|
|||
|
|
SEE ALSO
|
|||
|
|
--------
|
|||
|
|
|
|||
|
|
`dbus-send(1) <man:dbus-send(1)>`_
|