gdbus-tool: Add a command to wait for a well-known name on the bus

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

docs/reference/gio/gdbus.xml

@@ -91,6 +91,20 @@
     <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>
@@ -147,6 +161,15 @@
           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>
@@ -337,6 +360,38 @@ $ gdbus emit --session --object-path /foo --signal org.bar.Foo "['foo', 'bar', '
 $ 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>