[glib/gdbus-merge] GDBus: add a man page for gdbus(1)

[David Zeuthen <davidz src gnome org>]

commit f309334bc629b9b148d9ce2887489930d4eedd3f
Author: David Zeuthen <davidz redhat com>
Date:   Thu May 6 19:39:16 2010 -0400

    GDBus: add a man page for gdbus(1)

 docs/reference/gio/Makefile.am  |    7 +-
 docs/reference/gio/gdbus.xml    |  221 +++++++++++++++++++++++++++++++++++++++
 docs/reference/gio/gio-docs.xml |    1 +
 3 files changed, 227 insertions(+), 2 deletions(-)
---
diff --git a/docs/reference/gio/Makefile.am b/docs/reference/gio/Makefile.am
index 4e77a25..23bcd90 100644
--- a/docs/reference/gio/Makefile.am
+++ b/docs/reference/gio/Makefile.am
@@ -121,7 +121,9 @@ content_files =			\
 	gio-querymodules.xml	\
 	glib-compile-schemas.xml\
 	gsettings.xml		\
-	gsettings-schema-convert.xml
+	gsettings-schema-convert.xml \
+	gdbus.xml		\
+	$(NULL)
 
 expand_content_files =		\
 	overview.xml		\
@@ -143,7 +145,8 @@ man_MANS =			\
 	gio-querymodules.1	\
 	glib-compile-schemas.1	\
 	gsettings.1	\
-	gsettings-schema-convert.1
+	gsettings-schema-convert.1 \
+	gdbus.1
 
 if ENABLE_MAN
 
diff --git a/docs/reference/gio/gdbus.xml b/docs/reference/gio/gdbus.xml
new file mode 100644
index 0000000..4bd0eb7
--- /dev/null
+++ b/docs/reference/gio/gdbus.xml
@@ -0,0 +1,221 @@
+<refentry id="gdbus" lang="en">
+
+<refmeta>
+  <refentrytitle>gdbus</refentrytitle>
+  <manvolnum>1</manvolnum>
+  <refmiscinfo class="manual">User Commands</refmiscinfo>
+</refmeta>
+
+<refnamediv>
+  <refname>gdbus</refname>
+  <refpurpose>Introspect and call remote 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>
+  </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>
+    <arg choice="plain">ARG1</arg>
+    <arg choice="plain" rep="repeat">ARG2</arg>
+  </cmdsynopsis>
+  <cmdsynopsis>
+    <command>gdbus</command>
+    <arg choice="plain">help</arg>
+  </cmdsynopsis>
+</refsynopsisdiv>
+
+<refsect1>
+  <title>Description</title>
+  <para>
+    <command>gdbus</command> offers a simple commandline utility for
+    introspecting and calling methods on remote objects.
+  </para>
+  <refsect2>
+    <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.
+        </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>help</option></term>
+        <listitem><para>
+          Prints help and exit.
+        </para></listitem>
+      </varlistentry>
+    </variablelist>
+  </refsect2>
+</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>
+  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>
+</refsect1>
+
+<refsect1>
+  <title>AUTHOR</title>
+  <para>
+    Written by David Zeuthen <email>zeuthen gmail com</email> with
+    a lot of help from many others.
+  </para>
+</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>
+
diff --git a/docs/reference/gio/gio-docs.xml b/docs/reference/gio/gio-docs.xml
index 7a0e4ae..2b9a7f2 100644
--- a/docs/reference/gio/gio-docs.xml
+++ b/docs/reference/gio/gio-docs.xml
@@ -166,6 +166,7 @@
         <xi:include href="gsettings.xml"/>
         <xi:include href="glib-compile-schemas.xml"/>
         <xi:include href="gsettings-schema-convert.xml"/>
+        <xi:include href="gdbus.xml"/>
     </chapter>
   </part>