docs/reference/gio/gdbus.1

   1 '\" t
   2 .\"     Title: gdbus
   3 .\"    Author: [see the "AUTHOR" section]
   4 .\" Generator: DocBook XSL Stylesheets v1.76.1 <http://docbook.sf.net/>
   5 .\"      Date: 05/14/2012
   6 .\"    Manual: User Commands
   7 .\"    Source: User Commands
   8 .\"  Language: English
   9 .\"
  10 .TH "GDBUS" "1" "05/14/2012" "User Commands" "User Commands"
  11 .\" -----------------------------------------------------------------
  12 .\" * Define some portability stuff
  13 .\" -----------------------------------------------------------------
  14 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  15 .\" http://bugs.debian.org/507673
  16 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
  17 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  18 .ie \n(.g .ds Aq \(aq
  19 .el       .ds Aq '
  20 .\" -----------------------------------------------------------------
  21 .\" * set default formatting
  22 .\" -----------------------------------------------------------------
  23 .\" disable hyphenation
  24 .nh
  25 .\" disable justification (adjust text to left margin only)
  26 .ad l
  27 .\" -----------------------------------------------------------------
  28 .\" * MAIN CONTENT STARTS HERE *
  29 .\" -----------------------------------------------------------------
  30 .SH "NAME"
  31 gdbus \- Tool for working with D\-Bus objects
  32 .SH "SYNOPSIS"
  33 .HP \w'\fBgdbus\fR\ 'u
  34 \fBgdbus\fR introspect [\-\-system | \-\-session | \-\-address\ \fIaddress\fR] \-\-dest\ \fIbus_name\fR \-\-object\-path\ \fI/path/to/object\fR [\-\-xml] [\-\-recurse] [\-\-only\-properties]
  35 .HP \w'\fBgdbus\fR\ 'u
  36 \fBgdbus\fR monitor [\-\-system | \-\-session | \-\-address\ \fIaddress\fR] \-\-dest\ \fIbus_name\fR [\-\-object\-path\ \fI/path/to/object\fR]
  37 .HP \w'\fBgdbus\fR\ 'u
  38 \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...
  39 .HP \w'\fBgdbus\fR\ 'u
  40 \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...
  41 .HP \w'\fBgdbus\fR\ 'u
  42 \fBgdbus\fR help
  43 .SH "DESCRIPTION"
  44 .PP
  45
  46 \fBgdbus\fR
  47 is a simple tool for working with D\-Bus objects\&.
  48 .SS "Commands"
  49 .PP
  50 \fBintrospect\fR
  51 .RS 4
  52 Prints out interfaces and property values for a remote object\&. For this to work, the owner of the object needs to implement the
  53 org\&.freedesktop\&.DBus\&.Introspectable
  54 interface\&. If the
  55 \fB\-\-xml\fR
  56 option is used, the returned introspection XML is printed, otherwise a parsed pretty representation is printed\&. The
  57 \fB\-\-recurse\fR
  58 option can be used to introspect children (and their children and so on) and the
  59 \fB\-\-only\-properties\fR
  60 option can be used to only print the interfaces with properties\&.
  61 .RE
  62 .PP
  63 \fBmonitor\fR
  64 .RS 4
  65 Monitors one or all objects owned by the owner of
  66 \fIbus_name\fR\&.
  67 .RE
  68 .PP
  69 \fBcall\fR
  70 .RS 4
  71 Invokes a method on a remote object\&. Each argument to pass to the method must be specified as a serialized
  72 \fBGVariant\fR
  73 except that strings do not need explicit quotes\&. The return values are printed out as serialized
  74 \fBGVariant\fR
  75 values\&.
  76 .RE
  77 .PP
  78 \fBemit\fR
  79 .RS 4
  80 Emits a signal\&. Each argument to include in the signal must be specified as a serialized
  81 \fBGVariant\fR
  82 except that strings do not need explicit quotes\&.
  83 .RE
  84 .PP
  85 \fBhelp\fR
  86 .RS 4
  87 Prints help and exit\&.
  88 .RE
  89 .SH "BASH COMPLETION"
  90 .PP
  91
  92 \fBgdbus\fR
  93 ships with a bash completion script to complete commands, destinations, bus names, object paths and interface/method names\&.
  94 .SH "EXAMPLES"
  95
  96   This shows how to introspect an object \- note that the value of each
  97   property is displayed:
  98 .sp
  99 .if n \{\
 100 .RS 4
 101 .\}
 102 .nf
 103 $ gdbus introspect \-\-system \e
 104         \-\-dest org\&.freedesktop\&.NetworkManager \e
 105         \-\-object\-path /org/freedesktop/NetworkManager/Devices/0
 106 node /org/freedesktop/NetworkManager/Devices/0 {
 107   interface org\&.freedesktop\&.DBus\&.Introspectable {
 108     methods:
 109       Introspect(out s data);
 110   };
 111   interface org\&.freedesktop\&.DBus\&.Properties {
 112     methods:
 113       Get(in  s interface,
 114           in  s propname,
 115           out v value);
 116       Set(in  s interface,
 117           in  s propname,
 118           in  v value);
 119       GetAll(in  s interface,
 120              out a{sv} props);
 121   };
 122   interface org\&.freedesktop\&.NetworkManager\&.Device\&.Wired {
 123     signals:
 124       PropertiesChanged(a{sv} arg_0);
 125     properties:
 126       readonly b Carrier = false;
 127       readonly u Speed = 0;
 128       readonly s HwAddress = \*(Aq00:1D:72:88:BE:97\*(Aq;
 129   };
 130   interface org\&.freedesktop\&.NetworkManager\&.Device {
 131     methods:
 132       Disconnect();
 133     signals:
 134       StateChanged(u arg_0,
 135                    u arg_1,
 136                    u arg_2);
 137     properties:
 138       readonly u DeviceType = 1;
 139       readonly b Managed = true;
 140       readwrite o Ip6Config = \*(Aq/\*(Aq;
 141       readwrite o Dhcp4Config = \*(Aq/\*(Aq;
 142       readwrite o Ip4Config = \*(Aq/\*(Aq;
 143       readonly u State = 2;
 144       readwrite u Ip4Address = 0;
 145       readonly u Capabilities = 3;
 146       readonly s Driver = \*(Aqe1000e\*(Aq;
 147       readwrite s Interface = \*(Aqeth0\*(Aq;
 148       readonly s Udi = \*(Aq/sys/devices/pci0000:00/0000:00:19\&.0/net/eth0\*(Aq;
 149   };
 150 };
 151 .fi
 152 .if n \{\
 153 .RE
 154 .\}
 155 .PP
 156 The
 157 \fB\-\-recurse\fR
 158 and
 159 \fB\-\-only\-properties\fR
 160 options can be useful when wanting to inspect all objects owned by a particular process:
 161 .sp
 162 .if n \{\
 163 .RS 4
 164 .\}
 165 .nf
 166 $ gdbus introspect \-\-system \-\-dest org\&.freedesktop\&.UPower \-\-object\-path / \-\-recurse  \-\-only\-properties
 167 node / {
 168   node /org {
 169     node /org/freedesktop {
 170       node /org/freedesktop/UPower {
 171         interface org\&.freedesktop\&.UPower {
 172           properties:
 173             readonly b IsDocked = true;
 174             readonly b LidForceSleep = false;
 175             readonly b LidIsPresent = false;
 176             readonly b LidIsClosed = false;
 177             readonly b OnLowBattery = false;
 178             readonly b OnBattery = false;
 179             readonly b CanHibernate = true;
 180             readonly b CanSuspend = true;
 181             readonly s DaemonVersion = \*(Aq0\&.9\&.10\*(Aq;
 182         };
 183         node /org/freedesktop/UPower/Policy {
 184         };
 185         node /org/freedesktop/UPower/Wakeups {
 186           interface org\&.freedesktop\&.UPower\&.Wakeups {
 187             properties:
 188               readonly b HasCapability = true;
 189           };
 190         };
 191       };
 192     };
 193   };
 194 };
 195 .fi
 196 .if n \{\
 197 .RE
 198 .\}
 199 .PP
 200 In a similar fashion, the
 201 \fBintrospect\fR
 202 command can be used to learn details about the
 203 Notify
 204 method:
 205 .sp
 206 .if n \{\
 207 .RS 4
 208 .\}
 209 .nf
 210 [\&.\&.\&.]
 211   interface org\&.freedesktop\&.Notifications {
 212     methods:
 213       GetServerInformation(out s return_name,
 214                            out s return_vendor,
 215                            out s return_version,
 216                            out s return_spec_version);
 217       GetCapabilities(out as return_caps);
 218       CloseNotification(in  u id);
 219       Notify(in  s app_name,
 220              in  u id,
 221              in  s icon,
 222              in  s summary,
 223              in  s body,
 224              in  as actions,
 225              in  a{sv} hints,
 226              in  i timeout,
 227              out u return_id);
 228   };
 229 [\&.\&.\&.]
 230 .fi
 231 .if n \{\
 232 .RE
 233 .\}
 234 .PP
 235 With this information, it\*(Aqs easy to use the
 236 \fBcall\fR
 237 command to display a notification
 238 .sp
 239 .if n \{\
 240 .RS 4
 241 .\}
 242 .nf
 243 $ gdbus call \-\-session \e
 244              \-\-dest org\&.freedesktop\&.Notifications \e
 245              \-\-object\-path /org/freedesktop/Notifications \e
 246              \-\-method org\&.freedesktop\&.Notifications\&.Notify \e
 247              my_app_name \e
 248              42 \e
 249              gtk\-dialog\-info \e
 250              "The Summary" \e
 251              "Here\*(Aqs the body of the notification" \e
 252              [] \e
 253              {} \e
 254              5000
 255 (uint32 12,)
 256 .fi
 257 .if n \{\
 258 .RE
 259 .\}
 260 .PP
 261 Monitoring all objects on a service:
 262 .sp
 263 .if n \{\
 264 .RS 4
 265 .\}
 266 .nf
 267 $ gdbus monitor \-\-system \-\-dest org\&.freedesktop\&.ConsoleKit
 268 Monitoring signals from all objects owned by org\&.freedesktop\&.ConsoleKit
 269 The name org\&.freedesktop\&.ConsoleKit is owned by :1\&.15
 270 /org/freedesktop/ConsoleKit/Session2: org\&.freedesktop\&.ConsoleKit\&.Session\&.ActiveChanged (false,)
 271 /org/freedesktop/ConsoleKit/Seat1: org\&.freedesktop\&.ConsoleKit\&.Seat\&.ActiveSessionChanged (\*(Aq\*(Aq,)
 272 /org/freedesktop/ConsoleKit/Session2: org\&.freedesktop\&.ConsoleKit\&.Session\&.ActiveChanged (true,)
 273 /org/freedesktop/ConsoleKit/Seat1: org\&.freedesktop\&.ConsoleKit\&.Seat\&.ActiveSessionChanged (\*(Aq/org/freedesktop/ConsoleKit/Session2\*(Aq,)
 274 .fi
 275 .if n \{\
 276 .RE
 277 .\}
 278 .PP
 279 Monitoring a single object on a service:
 280 .sp
 281 .if n \{\
 282 .RS 4
 283 .\}
 284 .nf
 285 $ gdbus monitor \-\-system \-\-dest org\&.freedesktop\&.NetworkManager \-\-object\-path /org/freedesktop/NetworkManager/AccessPoint/4141
 286 Monitoring signals on object /org/freedesktop/NetworkManager/AccessPoint/4141 owned by org\&.freedesktop\&.NetworkManager
 287 The name org\&.freedesktop\&.NetworkManager is owned by :1\&.5
 288 /org/freedesktop/NetworkManager/AccessPoint/4141: org\&.freedesktop\&.NetworkManager\&.AccessPoint\&.PropertiesChanged ({\*(AqStrength\*(Aq: <byte 0x5c>},)
 289 /org/freedesktop/NetworkManager/AccessPoint/4141: org\&.freedesktop\&.NetworkManager\&.AccessPoint\&.PropertiesChanged ({\*(AqStrength\*(Aq: <byte 0x64>},)
 290 /org/freedesktop/NetworkManager/AccessPoint/4141: org\&.freedesktop\&.NetworkManager\&.AccessPoint\&.PropertiesChanged ({\*(AqStrength\*(Aq: <byte 0x5e>},)
 291 /org/freedesktop/NetworkManager/AccessPoint/4141: org\&.freedesktop\&.NetworkManager\&.AccessPoint\&.PropertiesChanged ({\*(AqStrength\*(Aq: <byte 0x64>},)
 292 .fi
 293 .if n \{\
 294 .RE
 295 .\}
 296 .PP
 297 Emitting a signal:
 298 .sp
 299 .if n \{\
 300 .RS 4
 301 .\}
 302 .nf
 303 $ gdbus emit \-\-session \-\-object\-path /foo \-\-signal org\&.bar\&.Foo "[\*(Aqfoo\*(Aq, \*(Aqbar\*(Aq, \*(Aqbaz\*(Aq]"
 304 .fi
 305 .if n \{\
 306 .RE
 307 .\}
 308 .PP
 309 Emitting a signal to a specific process:
 310 .sp
 311 .if n \{\
 312 .RS 4
 313 .\}
 314 .nf
 315 $ gdbus emit \-\-session \-\-object\-path /bar \-\-signal org\&.bar\&.Bar someString \-\-dest :1\&.42
 316 .fi
 317 .if n \{\
 318 .RE
 319 .\}
 320 .SH "AUTHOR"
 321 .PP
 322 Written by David Zeuthen
 323 zeuthen@gmail\&.com
 324 with a lot of help from many others\&.
 325 .SH "BUGS"
 326 .PP
 327 Please send bug reports to either the distribution bug tracker or the upstream bug tracker at
 328 \m[blue]\fB\%https://bugzilla.gnome.org/enter_bug.cgi?product=glib\fR\m[]\&.
 329 .SH "SEE ALSO"
 330 .PP
 331
 332 \fBdbus-send\fR(1)