NewChannel: be singular

We no longer recommend emitting plural NewChannels signals, so we
might as well simplify the signal.

Bug: https://bugs.freedesktop.org/show_bug.cgi?id=69430

12 files changed, 52 insertions, 73 deletions

diff --git a/doc/templates/interface.html b/doc/templates/interface.html
index 981f67ef..0ede0364 100644
--- a/doc/templates/interface.html
+++ b/doc/templates/interface.html
@@ -348,7 +348,7 @@
        #if $interface.is_channel_related:
        change once the channel has been created. Immutable properties SHOULD
        appear in the channel detail list
-       of <a href="Connection.html#im.telepathy.v1.Connection.NewChannels">NewChannels</a>
+       of <a href="Connection.html#im.telepathy.v1.Connection.NewChannel">NewChannel</a>
        signals.
        #else
        change.
@@ -360,7 +360,7 @@
        #if $interface.is_channel_related:
        change once the channel has been created. Immutable properties SHOULD
        appear in the channel detail list
-       of <a href="Connection.html#im.telepathy.v1.Connection.NewChannels">NewChannels</a>
+       of <a href="Connection.html#im.telepathy.v1.Connection.NewChannel">NewChannel</a>
        signals.
        #else
        change.
diff --git a/spec/Channel.xml b/spec/Channel.xml
index 8c2d9f1b..fc8791fe 100644
--- a/spec/Channel.xml
+++ b/spec/Channel.xml
@@ -323,7 +323,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
 
     <p>Each channel has a number of immutable properties (which cannot vary
       after the channel has been announced with <tp:dbus-ref
-        namespace='imt1.Connection'>NewChannels</tp:dbus-ref>),
+        namespace='imt1.Connection'>NewChannel</tp:dbus-ref>),
       provided to clients in the
       <tp:dbus-ref namespace='imt1.Client.Observer'>ObserveChannels</tp:dbus-ref>,
       <tp:dbus-ref namespace='imt1.Client.Approver'>AddDispatchOperation</tp:dbus-ref> and
diff --git a/spec/Channel_Dispatch_Operation.xml b/spec/Channel_Dispatch_Operation.xml
index 022eab0d..6c770f25 100644
--- a/spec/Channel_Dispatch_Operation.xml
+++ b/spec/Channel_Dispatch_Operation.xml
@@ -36,50 +36,29 @@
         from outgoing requests for channels.</p>
 
       <p>More specifically, whenever the <tp:dbus-ref
-        namespace="im.telepathy.v1">Connection.NewChannels</tp:dbus-ref>
-        signal contains channels whose <tp:dbus-ref
+        namespace="im.telepathy.v1">Connection.NewChannel</tp:dbus-ref>
+        signal contains a channel whose <tp:dbus-ref
         namespace="im.telepathy.v1.Channel">Requested</tp:dbus-ref>
-        property is false, one or more ChannelDispatchOperation
-        objects are created for those channels.</p>
-
-      <p>(If some channels in a NewChannels signal are in different bundles,
-        this is an error. The channel dispatcher SHOULD recover by treating
-        the NewChannels signal as if it had been several NewChannels signals
-        each containing one channel.)</p>
-
-      <p>First, the channel dispatcher SHOULD construct a list of all the
-        <tp:dbus-ref
-          namespace="im.telepathy.v1.Client">Handler</tp:dbus-ref>s
-        that could handle all the channels (based on their <tp:dbus-ref
-          namespace="im.telepathy.v1.Client.Handler">HandlerChannelFilter</tp:dbus-ref>
-        property), ordered by
-        priority in some implementation-dependent way. If there are handlers
-        which could handle all the channels, one channel dispatch operation
-        SHOULD be created for all the channels. If there are not, one channel
-        dispatch operation SHOULD be created for each channel, each with
-        a list of channel handlers that could handle that channel.</p>
+        property is false, a ChannelDispatchOperation
+        object is created for that channel.</p>
 
       <p>If no handler at all can handle a channel, the channel dispatcher
         SHOULD terminate that channel instead of creating a channel dispatcher
         for it. It is RECOMMENDED that the channel dispatcher closes
-        the channels using <tp:dbus-ref
+        the channel using <tp:dbus-ref
           namespace="im.telepathy.v1">Channel.Interface.Destroyable1.Destroy</tp:dbus-ref>
         if supported, or <tp:dbus-ref
           namespace="im.telepathy.v1">Channel.Close</tp:dbus-ref>
         otherwise.</p>
 
-      <p>When listing channel handlers, priority SHOULD be given to
-        channel handlers that are already handling channels from the same
-        bundle.</p>
-
       <p>If a handler with <tp:dbus-ref
           namespace="im.telepathy.v1.Client.Handler">BypassApproval</tp:dbus-ref>
-        <code>= True</code> could handle all of the channels in the dispatch
+        <code>= True</code> could handle the channel in the dispatch
         operation, then the channel dispatcher SHOULD call <tp:dbus-ref
           namespace="im.telepathy.v1.Client.Handler">HandleChannel</tp:dbus-ref>
         on that handler, and (assuming the call succeeds) emit
-        <tp:member-ref>Finished</tp:member-ref> and stop processing those
-        channels without involving any approvers.</p>
+        <tp:member-ref>Finished</tp:member-ref> and stop processing that
+        channel without involving any approvers.</p>
 
       <tp:rationale>
         <p>Some channel types can be picked up "quietly" by an existing
@@ -95,14 +74,14 @@
 
       <p>Otherwise, the channel dispatcher SHOULD send the channel dispatch
         operation to all relevant approvers (in parallel) and wait for an
-        approver to claim the channels or request that they are handled.
+        approver to claim the channel or request that it is handled.
         See
         <tp:dbus-ref
           namespace="im.telepathy.v1.Client.Approver">AddDispatchOperation</tp:dbus-ref>
         for more details on this.</p>
 
       <p>Finally, if the approver requested it, the channel dispatcher SHOULD
-        send the channels to a handler.</p>
+        send the channel to a handler.</p>
     </tp:docstring>
 
     <property name="Interfaces" tp:name-for-bindings="Interfaces"
diff --git a/spec/Channel_Interface_Conference1.xml b/spec/Channel_Interface_Conference1.xml
index baf36779..5bb53603 100644
--- a/spec/Channel_Interface_Conference1.xml
+++ b/spec/Channel_Interface_Conference1.xml
@@ -478,12 +478,12 @@
           to the InitialInviteeIDs, and the target handles of the
           InitialChannels, with any duplicate handles removed. Because this
           property is immutable, its value SHOULD be computed before the
-          channel is announced via the NewChannels signal.</p>
+          channel is announced via the NewChannel signal.</p>
 
         <tp:rationale>
           <p>This simplifies identification of new channels in clients - they
             only have to look at one of the properties, not both. For example,
-            after either of the requests mentioned above, the NewChannels
+            after either of the requests mentioned above, the NewChannel
             signal would announce the channel with InitialChannels=[C1],
             InitialInviteeHandles=[rob, sjoerd], and
             InitialInviteeIDs=["rob@example.net", "sjoerd.example.com"].</p>
diff --git a/spec/Channel_Interface_SMS1.xml b/spec/Channel_Interface_SMS1.xml
index a4f1d74a..ab23b3d5 100644
--- a/spec/Channel_Interface_SMS1.xml
+++ b/spec/Channel_Interface_SMS1.xml
@@ -103,7 +103,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
         <p>This property is immutable (cannot change), and therefore SHOULD
           appear wherever immutable properties are reported, e.g. <tp:dbus-ref
             namespace="imt1.Connection"
-          >NewChannels</tp:dbus-ref> signals.</p>
+          >NewChannel</tp:dbus-ref> signals.</p>
 
         <tp:rationale>
           <p>Class 0 SMSes should be displayed immediately to the user, and
diff --git a/spec/Channel_Interface_Tube1.xml b/spec/Channel_Interface_Tube1.xml
index d4eeb6ab..3d43a2db 100644
--- a/spec/Channel_Interface_Tube1.xml
+++ b/spec/Channel_Interface_Tube1.xml
@@ -81,7 +81,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
 
         <p>When receiving an incoming tube, this property is immutable and so advertised in the
           <tp:dbus-ref
-            namespace="im.telepathy.v1.Connection">NewChannels</tp:dbus-ref>
+            namespace="im.telepathy.v1.Connection">NewChannel</tp:dbus-ref>
           signal.</p>
       </tp:docstring>
     </property>
diff --git a/spec/Channel_Request.xml b/spec/Channel_Request.xml
index 2b68f882..2b98284e 100644
--- a/spec/Channel_Request.xml
+++ b/spec/Channel_Request.xml
@@ -323,7 +323,7 @@
         <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
           <p>The same immutable properties of the Channel that would appear
             in a <tp:dbus-ref namespace="imt1.Connection"
-              >NewChannels</tp:dbus-ref> signal.</p>
+              >NewChannel</tp:dbus-ref> signal.</p>
         </tp:docstring>
       </arg>
 
diff --git a/spec/Channel_Type_Call1.xml b/spec/Channel_Type_Call1.xml
index f6226b7c..341b7534 100644
--- a/spec/Channel_Type_Call1.xml
+++ b/spec/Channel_Type_Call1.xml
@@ -155,12 +155,12 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
 
       <p>When an incoming call occurs, something like the following
         <tp:dbus-ref
-        namespace="imt1.Connection">NewChannels</tp:dbus-ref>
+        namespace="imt1.Connection">NewChannel</tp:dbus-ref>
         signal will occur:</p>
 
       <blockquote>
         <pre>
-<tp:dbus-ref namespace="imt1.Connection">NewChannels</tp:dbus-ref>([
+<tp:dbus-ref namespace="imt1.Connection">NewChannel</tp:dbus-ref>(
   /im/telepathy/v1/Connection/foo/bar/foo_40bar_2ecom/CallChannel,
   {
     ...<tp:dbus-ref namespace="imt1.Channel">ChannelType</tp:dbus-ref>: ...<tp:dbus-ref
@@ -174,7 +174,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
     ...<tp:member-ref>InitialAudioName</tp:member-ref>: "audio",
     ...<tp:member-ref>InitialVideoName</tp:member-ref>: "video",
     ...<tp:member-ref>MutableContents</tp:member-ref>: True,
-  }])</pre></blockquote>
+  })</pre></blockquote>
 
       <p>The <tp:member-ref>InitialAudio</tp:member-ref> and
         <tp:member-ref>InitialVideo</tp:member-ref> properties show that
diff --git a/spec/Channel_Type_Contact_Search1.xml b/spec/Channel_Type_Contact_Search1.xml
index 9fdab7fb..2841ae0d 100644
--- a/spec/Channel_Type_Contact_Search1.xml
+++ b/spec/Channel_Type_Contact_Search1.xml
@@ -296,7 +296,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
 
         <tp:rationale>
           It can be in the <tp:dbus-ref
-            namespace="im.telepathy.v1.Connection">NewChannels</tp:dbus-ref>
+            namespace="im.telepathy.v1.Connection">NewChannel</tp:dbus-ref>
           signal for round-trip reduction.
         </tp:rationale>
       </tp:docstring>
diff --git a/spec/Channel_Type_Text.xml b/spec/Channel_Type_Text.xml
index 5c1707a3..780ff5f1 100644
--- a/spec/Channel_Type_Text.xml
+++ b/spec/Channel_Type_Text.xml
@@ -1494,7 +1494,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
         the connection manager MUST allow this, but SHOULD open a new channel
         to deliver those messages, signalling it as a new channel with the
         <tp:dbus-ref
-          namespace="imt1.Connection">NewChannels</tp:dbus-ref>
+          namespace="imt1.Connection">NewChannel</tp:dbus-ref>
         signal. The new channel should resemble the old channel, but have
         <tp:dbus-ref namespace='imt1.Channel'>Requested</tp:dbus-ref> = FALSE
         regardless of its previous value; the <tp:dbus-ref
@@ -1524,7 +1524,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
           <li>UI calls Close on text channel</li>
           <li>text channel emits Closed and closes</li>
           <li>message arrives</li>
-          <li>new text channel is created, connection emits NewChannels</li>
+          <li>new text channel is created, connection emits NewChannel</li>
           <li>(the same or a different) UI handles it</li>
         </ul>
 
diff --git a/spec/Client_Observer.xml b/spec/Client_Observer.xml
index 1a80d4fb..7baabfc3 100644
--- a/spec/Client_Observer.xml
+++ b/spec/Client_Observer.xml
@@ -120,10 +120,10 @@
       <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
         <p>A specification of the channels in which this observer is
           interested. The <tp:member-ref>ObserveChannels</tp:member-ref> method
-          should be called by the channel dispatcher whenever any of the new
-          channels in a <tp:dbus-ref
-            namespace="im.telepathy.v1.Connection">NewChannels</tp:dbus-ref>
-          signal match this description.</p>
+          should be called by the channel dispatcher whenever the new
+          channel in a <tp:dbus-ref
+            namespace="im.telepathy.v1.Connection">NewChannel</tp:dbus-ref>
+          signal matches this description.</p>
 
         <p>Only certain D-Bus types have useful semantics for matching like this,
           so only certain types are allowed:</p>
@@ -253,20 +253,11 @@ Recover=true
 
     <method name="ObserveChannels" tp:name-for-bindings="Observe_Channels">
       <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
-        <p>Called by the channel dispatcher when channels in which the
+        <p>Called by the channel dispatcher when a channel in which the
           observer has registered an interest are announced in a <tp:dbus-ref
-            namespace="im.telepathy.v1.Connection">NewChannels</tp:dbus-ref>
+            namespace="im.telepathy.v1.Connection">NewChannel</tp:dbus-ref>
           signal.</p>
 
-        <p>If the same NewChannels signal announces some channels that match
-          the filter, and some that do not, then only a subset of the channels
-          (those that do match the filter) are passed to this method.</p>
-
-        <p>If the channel dispatcher will split up the channels from a single
-          NewChannels signal and dispatch them separately (for instance
-          because no installed Handler can handle all of them), it will call
-          ObserveChannels several times.</p>
-
         <p>The observer MUST NOT return from this method call until it is ready
           for a handler for the channel to run (which may change the channel's
           state).</p>
diff --git a/spec/Connection.xml b/spec/Connection.xml
index 154c8bb7..fdb43877 100644
--- a/spec/Connection.xml
+++ b/spec/Connection.xml
@@ -868,7 +868,7 @@ USA.</p>
               race condition would be likely to exist in some cases:</p>
 
             <ul>
-              <li>NewChannels or Get("Channels") includes a property P with
+              <li>NewChannel or Get("Channels") includes a property P with
                 value V1</li>
               <li>Client creates a proxy object for the channel</li>
               <li>The value of P changes to V2</li>
@@ -950,12 +950,12 @@ USA.</p>
       <arg name="Channel" direction="out" type="o">
         <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
           <p>The Channel object, which MUST NOT be signalled with
-            <tp:member-ref>NewChannels</tp:member-ref> until after this method
+            <tp:member-ref>NewChannel</tp:member-ref> until after this method
             returns.</p>
 
           <tp:rationale>
             <p>This allows the requester to alter its handling of
-              NewChannels by knowing whether one of the channels satisfied
+              NewChannel by knowing whether one of the channels satisfied
               a request it made.</p>
           </tp:rationale>
         </tp:docstring>
@@ -1090,12 +1090,12 @@ USA.</p>
         <tp:docstring>
           The Channel object. If it was created as a result of this method
           call, it MUST NOT be signalled by
-          <tp:member-ref>NewChannels</tp:member-ref> until after this method
+          <tp:member-ref>NewChannel</tp:member-ref> until after this method
           returns.
 
           <tp:rationale>
             <p>This allows the requester to alter its handling of
-              NewChannels by knowing whether one of the channels satisfied
+              NewChannel by knowing whether one of the channels satisfied
               a request it made.</p>
           </tp:rationale>
         </tp:docstring>
@@ -1171,14 +1171,15 @@ USA.</p>
       </tp:possible-errors>
     </method>
 
-    <signal name="NewChannels" tp:name-for-bindings="New_Channels">
-      <tp:added version="0.99.UNRELEASED">(as part of Connection)</tp:added>
+    <signal name="NewChannel" tp:name-for-bindings="New_Channel">
+      <tp:added version="0.99.UNRELEASED"/>
 
       <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
-        <p>A new channel has been created. The connection manager
-          SHOULD emit a single signal for each channel created.</p>
+        <p>A new channel has been created.</p>
 
-        <p>For example, joining a MUC Tube in XMPP requires joining the
+        <p>Unlike in some previous Telepathy versions, the connection manager
+          cannot emit a single signal for multiple channels.
+          For example, joining a MUC Tube in XMPP requires joining the
           corresponding MUC (chatroom). Either the connection manager
           should announce a new <tp:dbus-ref
           namespace="imt1.Channel.Type">Text</tp:dbus-ref> channel
@@ -1194,9 +1195,17 @@ USA.</p>
         </tp:rationale>
       </tp:docstring>
 
-      <arg name="Channels" type="a(oa{sv})" tp:type="Channel_Details[]">
+      <arg name="Channel" type="o">
         <tp:docstring>
-          The channels and their details.
+          The object path of the channel.
+        </tp:docstring>
+      </arg>
+
+      <arg name="Properties" type="a{sv}"
+        tp:type="Qualified_Property_Value_Map">
+        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+          <p>The same properties of the channel that would appear in the
+            <tp:type>Channel_Details</tp:type> struct.</p>
         </tp:docstring>
       </arg>
     </signal>
@@ -1207,7 +1216,7 @@ USA.</p>
       <tp:docstring>
         A list of all the channels which currently exist on this connection.
         Change notification is via the
-        <tp:member-ref>NewChannels</tp:member-ref> and
+        <tp:member-ref>NewChannel</tp:member-ref> and
         <tp:member-ref>ChannelClosed</tp:member-ref> signals.
       </tp:docstring>
     </property>