HandleChannel: be singular

7 files changed, 45 insertions, 39 deletions

diff --git a/spec/Channel.xml b/spec/Channel.xml
index fa208d26..88a2aebb 100644
--- a/spec/Channel.xml
+++ b/spec/Channel.xml
@@ -327,7 +327,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
       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
-      <tp:dbus-ref namespace='imt1.Client.Handler'>HandleChannels</tp:dbus-ref>
+      <tp:dbus-ref namespace='imt1.Client.Handler'>HandleChannel</tp:dbus-ref>
       methods to permit immediate identification of the channel. This interface
       contains immutable properties common to all channels. In brief:</p>
 
diff --git a/spec/Channel_Dispatch_Operation.xml b/spec/Channel_Dispatch_Operation.xml
index 4225dc30..efe1f67b 100644
--- a/spec/Channel_Dispatch_Operation.xml
+++ b/spec/Channel_Dispatch_Operation.xml
@@ -76,7 +76,7 @@
           namespace="im.telepathy.v1.Client.Handler">BypassApproval</tp:dbus-ref>
         <code>= True</code> could handle all of the channels in the dispatch
         operation, then the channel dispatcher SHOULD call <tp:dbus-ref
-          namespace="im.telepathy.v1.Client.Handler">HandleChannels</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>
@@ -244,7 +244,7 @@
         <p>(FIXME: list some possible errors)</p>
 
         <p>If the channel handler raises an error from <tp:dbus-ref
-            namespace="im.telepathy.v1.Client.Handler">HandleChannels</tp:dbus-ref>,
+            namespace="im.telepathy.v1.Client.Handler">HandleChannel</tp:dbus-ref>,
           this method
           MAY respond by raising that same error, even if it is not
           specifically documented here.</p>
@@ -277,7 +277,7 @@
           <tp:docstring>
             The selected handler is syntactically correct, but will never
             be able to handle these channels (for instance because the channels
-            do not match its HandlerChannelFilter, or because HandleChannels
+            do not match its HandlerChannelFilter, or because HandleChannel
             raised NotImplemented).
           </tp:docstring>
         </tp:error>
@@ -289,7 +289,7 @@
             now responsible for the channels. In this situation, the second
             call to HandleWith MUST NOT return until the first one has
             returned successfully or unsuccessfully, and if the first call
-            to HandleChannels fails, the channel dispatcher SHOULD try to obey
+            to HandleChannel fails, the channel dispatcher SHOULD try to obey
             the choice of Handler made by the second call to HandleWith.
           </tp:docstring>
         </tp:error>
@@ -302,7 +302,7 @@
           internally. If this method is called successfully, the process
           calling this method becomes the handler for the channel, but
           <em>does not</em> have the <tp:dbus-ref
-            namespace="im.telepathy.v1.Client.Handler">HandleChannels</tp:dbus-ref>
+            namespace="im.telepathy.v1.Client.Handler">HandleChannel</tp:dbus-ref>
           method called on it.</p>
 
         <p>Clients that call Claim on channels but do not immediately
@@ -369,7 +369,7 @@
         <p>A variant of <tp:member-ref>HandleWith</tp:member-ref> allowing the
           approver to pass an user action time. This timestamp will be passed
           to the Handler when <tp:dbus-ref
-          namespace="im.telepathy.v1.Client.Handler">HandleChannels</tp:dbus-ref>
+          namespace="im.telepathy.v1.Client.Handler">HandleChannel</tp:dbus-ref>
           is called.</p>
       </tp:docstring>
 
@@ -406,7 +406,7 @@
           <tp:docstring>
             The selected handler is syntactically correct, but will never
             be able to handle these channels (for instance because the channels
-            do not match its HandlerChannelFilter, or because HandleChannels
+            do not match its HandlerChannelFilter, or because HandleChannel
             raised NotImplemented).
           </tp:docstring>
         </tp:error>
@@ -418,7 +418,7 @@
             now responsible for the channels. In this situation, the second
             call to HandleWith MUST NOT return until the first one has
             returned successfully or unsuccessfully, and if the first call
-            to HandleChannels fails, the channel dispatcher SHOULD try to obey
+            to HandleChannel fails, the channel dispatcher SHOULD try to obey
             the choice of Handler made by the second call to HandleWith.
           </tp:docstring>
         </tp:error>
diff --git a/spec/Channel_Dispatcher.xml b/spec/Channel_Dispatcher.xml
index 434dd119..1bf50e09 100644
--- a/spec/Channel_Dispatcher.xml
+++ b/spec/Channel_Dispatcher.xml
@@ -174,7 +174,7 @@
               namespace="im.telepathy.v1.ChannelRequest">UserActionTime</tp:dbus-ref>
             property will be set to this value, and it will eventually be
             passed as the <code>User_Action_Time</code> parameter of <tp:dbus-ref
-              namespace="im.telepathy.v1.Client.Handler">HandleChannels</tp:dbus-ref>.</p>
+              namespace="im.telepathy.v1.Client.Handler">HandleChannel</tp:dbus-ref>.</p>
         </tp:docstring>
       </arg>
 
@@ -200,7 +200,7 @@
 
             <p>This is partly so the channel dispatcher can call
               <tp:dbus-ref
-                namespace="im.telepathy.v1.Client.Handler">HandleChannels</tp:dbus-ref>
+                namespace="im.telepathy.v1.Client.Handler">HandleChannel</tp:dbus-ref>
               on it, and partly so the channel dispatcher
               can recover state if it crashes and is restarted.</p>
 
@@ -429,7 +429,7 @@
       </tp:added>
       <tp:changed version="0.23.2">This method now returns
         <var>Delegated</var> and <var>Not_Delegated</var> instead of nothing.
-        <tp:dbus-ref namespace="imt1.Client.Handler">HandleChannels</tp:dbus-ref>
+        <tp:dbus-ref namespace="imt1.Client.Handler">HandleChannel</tp:dbus-ref>
         is now called once per <var>Channel</var> in <var>Channels</var>.
       </tp:changed>
       <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
@@ -440,7 +440,7 @@
         <p>For each <var>Channel</var> in <var>Channels</var>, if another
           <tp:dbus-ref namespace="imt1.Client">Handler</tp:dbus-ref>
           can be found,
-          <tp:dbus-ref namespace="imt1.Client.Handler">HandleChannels</tp:dbus-ref>
+          <tp:dbus-ref namespace="imt1.Client.Handler">HandleChannel</tp:dbus-ref>
           will be called on it until a
           <tp:dbus-ref namespace="imt1.Client">Handler</tp:dbus-ref>
           accepts it.</p>
diff --git a/spec/Channel_Request.xml b/spec/Channel_Request.xml
index 75290988..188a34ba 100644
--- a/spec/Channel_Request.xml
+++ b/spec/Channel_Request.xml
@@ -272,13 +272,13 @@
             The Handler should check each
             <tp:dbus-ref namespace="imt1">ChannelRequest</tp:dbus-ref>
             of the Requests_Satisfied parameter of
-            <tp:dbus-ref namespace="imt1.Client.Handler">HandleChannels</tp:dbus-ref>
+            <tp:dbus-ref namespace="imt1.Client.Handler">HandleChannel</tp:dbus-ref>
             for the hint. The first request containing the hint SHOULD be used
             and all further hints SHOULD be ignored.
 
             <tp:rationale>
               This covers the very unlikely case where
-              <tp:dbus-ref namespace="imt1.Client.Handler">HandleChannels</tp:dbus-ref>
+              <tp:dbus-ref namespace="imt1.Client.Handler">HandleChannel</tp:dbus-ref>
               satisfies two separate requests which have different
               <tp:member-ref>PreferredHandler</tp:member-ref>s.
             </tp:rationale>
diff --git a/spec/Client_Handler.xml b/spec/Client_Handler.xml
index 7ea0b52a..46b9aee3 100644
--- a/spec/Client_Handler.xml
+++ b/spec/Client_Handler.xml
@@ -162,11 +162,11 @@ im.telepathy.v1.Channel.Interface.MediaSignalling/video/h264=true
       </tp:docstring>
     </property>
 
-    <method name="HandleChannels" tp:name-for-bindings="Handle_Channels">
+    <method name="HandleChannel" tp:name-for-bindings="Handle_Channel">
       <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
-        <p>Called by the channel dispatcher when this client should handle these
-          channels, or when this client should present channels that it is already
-          handling to the user (e.g. bring them into the foreground).</p>
+        <p>Called by the channel dispatcher when this client should handle this
+          channel, or when this client should present a channel that it is already
+          handling to the user (e.g. bring it into the foreground).</p>
 
         <tp:rationale>
           <p>Clients are expected to know what channels they're already handling,
@@ -178,20 +178,19 @@ im.telepathy.v1.Channel.Interface.MediaSignalling/video/h264=true
         <p>This method can raise any D-Bus error. If it does, the
           handler is assumed to have failed or crashed, and the channel
           dispatcher MUST recover in an implementation-specific way; it MAY
-          attempt to dispatch the channels to another handler, or close the
-          channels.</p>
+          attempt to dispatch the channel to another handler, or close the
+          channel.</p>
 
-        <p>If closing the channels, it is RECOMMENDED that the channel
-          dispatcher attempts to close the channels using
-          <tp:dbus-ref
+        <p>If closing the channel, it is RECOMMENDED that the channel
+          dispatcher attempts to use <tp:dbus-ref
             namespace="im.telepathy.v1">Channel.Close</tp:dbus-ref>,
           but resorts to calling
           <tp:dbus-ref
             namespace="im.telepathy.v1">Channel.Interface.Destroyable1.Destroy</tp:dbus-ref>
           (if available) or ignoring the channel (if not) if the same handler
-          repeatedly fails to handle channels.</p>
+          repeatedly fails to handle a channel.</p>
 
-        <p>After HandleChannels returns successfully, the client process is
+        <p>After HandleChannel returns successfully, the client process is
           considered to be responsible for the channel until it its unique
           name disappears from the bus.</p>
 
@@ -207,7 +206,7 @@ im.telepathy.v1.Channel.Interface.MediaSignalling/video/h264=true
         <tp:docstring>
           The
           <tp:dbus-ref namespace="im.telepathy.v1">Account</tp:dbus-ref>
-          with which the channels are associated. The
+          with which the channel is associated. The
           well-known bus name to use is that of the
           <tp:dbus-ref namespace="im.telepathy.v1">AccountManager</tp:dbus-ref>.
         </tp:docstring>
@@ -215,28 +214,35 @@ im.telepathy.v1.Channel.Interface.MediaSignalling/video/h264=true
 
       <arg name="Connection" type="o" direction="in">
         <tp:docstring>
-          The Connection with which the channels are associated. The
+          The Connection with which the channel is associated. The
           well-known bus name to use can be derived from this object
           path by removing the leading '/' and replacing all subsequent
           '/' by '.'.
         </tp:docstring>
       </arg>
 
-      <arg name="Channels" type="a(oa{sv})" direction="in"
-        tp:type="Channel_Details[]">
-        <tp:docstring>
-          The channels and their immutable properties. Their well-known
-          bus name is the same as that of the Connection.
+      <arg name="Channel" direction="in" type="o">
+        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+          <p>The Channel object. Its well-known bus name is the same
+            as that of the Connection.</p>
+        </tp:docstring>
+      </arg>
+
+      <arg name="Channel_Properties" direction="in" type="a{sv}"
+        tp:type="Qualified_Property_Value_Map">
+        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+          <p>Properties of the channel, equivalent to
+            the properties in <tp:type>Channel_Details</tp:type>.</p>
         </tp:docstring>
       </arg>
 
       <arg name="Requests_Satisfied" type="ao" direction="in">
         <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
-          <p>The requests satisfied by these channels.</p>
+          <p>The requests satisfied by this channel.</p>
 
           <tp:rationale>
             <p>If the handler implements Requests, this tells it
-              that these channels match previous <tp:dbus-ref
+              that this channel matches previous <tp:dbus-ref
                 namespace="im.telepathy.v1.Client.Interface.Requests">AddRequest</tp:dbus-ref>
               calls that it may have received.</p>
 
@@ -259,7 +265,7 @@ im.telepathy.v1.Channel.Interface.MediaSignalling/video/h264=true
 
       <arg name="Handler_Info" type="a{sv}" direction="in">
         <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
-          <p>Additional information about these channels. Currently defined
+          <p>Additional information about this channel. Currently defined
             keys are:</p>
 
           <dl>
diff --git a/spec/Client_Interface_Requests.xml b/spec/Client_Interface_Requests.xml
index f515abac..c96a29b3 100644
--- a/spec/Client_Interface_Requests.xml
+++ b/spec/Client_Interface_Requests.xml
@@ -54,7 +54,7 @@
         <p>If the request succeeds and is given to the expected Handler,
           the Requests_Satisfied parameter to
           <tp:dbus-ref
-            namespace="im.telepathy.v1.Client.Handler">HandleChannels</tp:dbus-ref>
+            namespace="im.telepathy.v1.Client.Handler">HandleChannel</tp:dbus-ref>
           can be used to match the channel to a previous AddRequest call.</p>
 
         <tp:rationale>
diff --git a/spec/Client_Observer.xml b/spec/Client_Observer.xml
index 1cfd5969..85961ee9 100644
--- a/spec/Client_Observer.xml
+++ b/spec/Client_Observer.xml
@@ -276,7 +276,7 @@ Recover=true
             to avoid the following race: text channel logger (observer) gets
             ObserveChannels, text channel handler gets
             <tp:dbus-ref
-              namespace="im.telepathy.v1.Client.Handler">HandleChannels</tp:dbus-ref>
+              namespace="im.telepathy.v1.Client.Handler">HandleChannel</tp:dbus-ref>
             channel handler starts up faster and acknowledges messages,
             logger never sees those messages.</p>
         </tp:rationale>
@@ -360,7 +360,7 @@ Recover=true
             If the same process is an Observer and a Handler, it can be useful
             to be given this information as soon as possible (it will also
             be passed to <tp:dbus-ref
-              namespace="im.telepathy.v1.Client">Handler.HandleChannels</tp:dbus-ref>).
+              namespace="im.telepathy.v1.Client">Handler.HandleChannel</tp:dbus-ref>).
           </tp:rationale>
         </tp:docstring>
       </arg>