glib/docs/reference/gio/gdbus.1

'\" t
.\"     Title: gdbus
.\"    Author: David Zeuthen <zeuthen@gmail.com>
.\" Generator: DocBook XSL Stylesheets v1.79.1 <http://docbook.sf.net/>
.\"      Date: 07/20/2016
.\"    Manual: User Commands
.\"    Source: GIO
.\"  Language: English
.\"
.TH "GDBUS" "1" "" "GIO" "User Commands"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
gdbus \- Tool for working with D\-Bus objects
.SH "SYNOPSIS"
.HP \w'\fBgdbus\fR\ 'u
\fBgdbus\fR introspect [\-\-system | \-\-session | \-\-address\ \fIaddress\fR] \-\-dest\ \fIbus_name\fR \-\-object\-path\ \fI/path/to/object\fR [\-\-xml] [\-\-recurse] [\-\-only\-properties]
.HP \w'\fBgdbus\fR\ 'u
\fBgdbus\fR monitor [\-\-system | \-\-session | \-\-address\ \fIaddress\fR] \-\-dest\ \fIbus_name\fR [\-\-object\-path\ \fI/path/to/object\fR]
.HP \w'\fBgdbus\fR\ 'u
\fBgdbus\fR call [\-\-system | \-\-session | \-\-address\ \fIaddress\fR] \-\-dest\ \fIbus_name\fR \-\-object\-path\ \fI/path/to/object\fR \-\-method\ \fIorg\&.project\&.InterfaceName\&.MethodName\fR [\-\-timeout\ \fIseconds\fR] ARG1 ARG2...
.HP \w'\fBgdbus\fR\ 'u
\fBgdbus\fR emit [\-\-system | \-\-session | \-\-address\ \fIaddress\fR] \-\-object\-path\ \fI/path/to/object\fR \-\-signal\ \fIorg\&.project\&.InterfaceName\&.SignalName\fR [\-\-dest\ \fIunique_bus_name\fR] ARG1 ARG2...
.HP \w'\fBgdbus\fR\ 'u
\fBgdbus\fR help
.SH "DESCRIPTION"
.PP
\fBgdbus\fR
is a simple tool for working with D\-Bus objects\&.
.SH "COMMANDS"
.PP
\fBintrospect\fR
.RS 4
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
\fB\-\-xml\fR
option is used, the returned introspection XML is printed, otherwise a parsed pretty representation is printed\&. The
\fB\-\-recurse\fR
option can be used to introspect children (and their children and so on) and the
\fB\-\-only\-properties\fR
option can be used to only print the interfaces with properties\&.
.RE
.PP
\fBmonitor\fR
.RS 4
Monitors one or all objects owned by the owner of
\fIbus_name\fR\&.
.RE
.PP
\fBcall\fR
.RS 4
Invokes a method on a remote object\&. Each argument to pass to the method must be specified as a serialized
\fBGVariant\fR
except that strings do not need explicit quotes\&. The return values are printed out as serialized
\fBGVariant\fR
values\&.
.RE
.PP
\fBemit\fR
.RS 4
Emits a signal\&. Each argument to include in the signal must be specified as a serialized
\fBGVariant\fR
except that strings do not need explicit quotes\&.
.RE
.PP
\fBhelp\fR
.RS 4
Prints help and exit\&.
.RE
.SH "BASH COMPLETION"
.PP
\fBgdbus\fR
ships with a bash completion script to complete commands, destinations, bus names, object paths and interface/method names\&.
.SH "EXAMPLES"

  This shows how to introspect an object \- note that the value of each
  property is displayed:
.sp
.if n \{\
.RS 4
.\}
.nf
$ gdbus introspect \-\-system \e
        \-\-dest org\&.freedesktop\&.NetworkManager \e
        \-\-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 = \*(Aq00:1D:72:88:BE:97\*(Aq;
  };
  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 = \*(Aq/\*(Aq;
      readwrite o Dhcp4Config = \*(Aq/\*(Aq;
      readwrite o Ip4Config = \*(Aq/\*(Aq;
      readonly u State = 2;
      readwrite u Ip4Address = 0;
      readonly u Capabilities = 3;
      readonly s Driver = \*(Aqe1000e\*(Aq;
      readwrite s Interface = \*(Aqeth0\*(Aq;
      readonly s Udi = \*(Aq/sys/devices/pci0000:00/0000:00:19\&.0/net/eth0\*(Aq;
  };
};
.fi
.if n \{\
.RE
.\}
.PP
The
\fB\-\-recurse\fR
and
\fB\-\-only\-properties\fR
options can be useful when wanting to inspect all objects owned by a particular process:
.sp
.if n \{\
.RS 4
.\}
.nf
$ 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 = \*(Aq0\&.9\&.10\*(Aq;
        };
        node /org/freedesktop/UPower/Policy {
        };
        node /org/freedesktop/UPower/Wakeups {
          interface org\&.freedesktop\&.UPower\&.Wakeups {
            properties:
              readonly b HasCapability = true;
          };
        };
      };
    };
  };
};
.fi
.if n \{\
.RE
.\}
.PP
In a similar fashion, the
\fBintrospect\fR
command can be used to learn details about the
Notify
method:
.sp
.if n \{\
.RS 4
.\}
.nf
[\&.\&.\&.]
  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);
  };
[\&.\&.\&.]
.fi
.if n \{\
.RE
.\}
.PP
With this information, it\*(Aqs easy to use the
\fBcall\fR
command to display a notification
.sp
.if n \{\
.RS 4
.\}
.nf
$ gdbus call \-\-session \e
             \-\-dest org\&.freedesktop\&.Notifications \e
             \-\-object\-path /org/freedesktop/Notifications \e
             \-\-method org\&.freedesktop\&.Notifications\&.Notify \e
             my_app_name \e
             42 \e
             gtk\-dialog\-info \e
             "The Summary" \e
             "Here\*(Aqs the body of the notification" \e
             [] \e
             {} \e
             5000
(uint32 12,)
.fi
.if n \{\
.RE
.\}
.PP
Monitoring all objects on a service:
.sp
.if n \{\
.RS 4
.\}
.nf
$ 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 (\*(Aq\*(Aq,)
/org/freedesktop/ConsoleKit/Session2: org\&.freedesktop\&.ConsoleKit\&.Session\&.ActiveChanged (true,)
/org/freedesktop/ConsoleKit/Seat1: org\&.freedesktop\&.ConsoleKit\&.Seat\&.ActiveSessionChanged (\*(Aq/org/freedesktop/ConsoleKit/Session2\*(Aq,)
.fi
.if n \{\
.RE
.\}
.PP
Monitoring a single object on a service:
.sp
.if n \{\
.RS 4
.\}
.nf
$ 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 ({\*(AqStrength\*(Aq: <byte 0x5c>},)
/org/freedesktop/NetworkManager/AccessPoint/4141: org\&.freedesktop\&.NetworkManager\&.AccessPoint\&.PropertiesChanged ({\*(AqStrength\*(Aq: <byte 0x64>},)
/org/freedesktop/NetworkManager/AccessPoint/4141: org\&.freedesktop\&.NetworkManager\&.AccessPoint\&.PropertiesChanged ({\*(AqStrength\*(Aq: <byte 0x5e>},)
/org/freedesktop/NetworkManager/AccessPoint/4141: org\&.freedesktop\&.NetworkManager\&.AccessPoint\&.PropertiesChanged ({\*(AqStrength\*(Aq: <byte 0x64>},)
.fi
.if n \{\
.RE
.\}
.PP
Emitting a signal:
.sp
.if n \{\
.RS 4
.\}
.nf
$ gdbus emit \-\-session \-\-object\-path /foo \-\-signal org\&.bar\&.Foo "[\*(Aqfoo\*(Aq, \*(Aqbar\*(Aq, \*(Aqbaz\*(Aq]"
.fi
.if n \{\
.RE
.\}
.PP
Emitting a signal to a specific process:
.sp
.if n \{\
.RS 4
.\}
.nf
$ gdbus emit \-\-session \-\-object\-path /bar \-\-signal org\&.bar\&.Bar someString \-\-dest :1\&.42
.fi
.if n \{\
.RE
.\}
.SH "BUGS"
.PP
Please send bug reports to either the distribution bug tracker or the upstream bug tracker at
\m[blue]\fB\%https://bugzilla.gnome.org/enter_bug.cgi?product=glib\fR\m[]\&.
.SH "SEE ALSO"
.PP
\fBdbus-send\fR(1)