Attachment 88633 Details for Bug 69430 – [05/12] HandleChannel: be singular

[patch] [05/12] HandleChannel: be singular

0005-HandleChannel-be-singular.patch (text/plain), 15.50 KB, created by Simon McVittie on 2013-11-04 18:24:40 UTC

(hide)

Description:

Filename:

MIME Type:

Creator: Simon McVittie

Created: 2013-11-04 18:24:40 UTC

Size: 15.50 KB

patch

obsolete

>From 371fc326449174d4ecd012bb27432cbcddad3517 Mon Sep 17 00:00:00 2001
>From: Simon McVittie <simon.mcvittie@collabora.co.uk>
>Date: Mon, 4 Nov 2013 15:35:49 +0000
>Subject: [PATCH 05/12] HandleChannel: be singular
>
>---
> spec/Channel.xml | 2 +-
> spec/Channel_Dispatch_Operation.xml | 16 ++++++-------
> spec/Channel_Dispatcher.xml | 8 +++----
> spec/Channel_Request.xml | 4 ++--
> spec/Client_Handler.xml | 48 +++++++++++++++++++++----------------
> spec/Client_Interface_Requests.xml | 2 +-
> spec/Client_Observer.xml | 4 ++--
> 7 files changed, 45 insertions(+), 39 deletions(-)
>
>diff --git a/spec/Channel.xml b/spec/Channel.xml
>index 0646f29..c5f219f 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'>ObserveChannel</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:
> 
>diff --git a/spec/Channel_Dispatch_Operation.xml b/spec/Channel_Dispatch_Operation.xml
>index 26deb7d..66b5ed4 100644
>--- a/spec/Channel_Dispatch_Operation.xml
>+++ b/spec/Channel_Dispatch_Operation.xml
>@@ -55,7 +55,7 @@
> namespace="im.telepathy.v1.Client.Handler">BypassApproval</tp:dbus-ref>
> <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">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 that
> channel without involving any approvers.
>@@ -223,7 +223,7 @@
> (FIXME: list some possible errors)
> 
> 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.
>@@ -256,7 +256,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>
>@@ -268,7 +268,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>
>@@ -281,7 +281,7 @@
> internally. If this method is called successfully, the process
> calling this method becomes the handler for the channel, but
> does not 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.
> 
> Clients that call Claim on channels but do not immediately
>@@ -348,7 +348,7 @@
> 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.
> </tp:docstring>
> 
>@@ -385,7 +385,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>
>@@ -397,7 +397,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 b8f5f87..3d7d52b 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>.
>+ namespace="im.telepathy.v1.Client.Handler">HandleChannel</tp:dbus-ref>.
> </tp:docstring>
> </arg>
> 
>@@ -200,7 +200,7 @@
> 
> 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.
> 
>@@ -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 @@
> 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.
>diff --git a/spec/Channel_Request.xml b/spec/Channel_Request.xml
>index b36b0a6..2b98284 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 7ea0b52..46b9aee 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">
>- 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).
>+ 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).
> 
> <tp:rationale>
> Clients are expected to know what channels they're already handling,
>@@ -178,20 +178,19 @@ im.telepathy.v1.Channel.Interface.MediaSignalling/video/h264=true
> 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.
>+ attempt to dispatch the channel to another handler, or close the
>+ channel.
> 
>- If closing the channels, it is RECOMMENDED that the channel
>- dispatcher attempts to close the channels using
>- <tp:dbus-ref
>+ 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.
>+ repeatedly fails to handle a channel.
> 
>- After HandleChannels returns successfully, the client process is
>+ After HandleChannel returns successfully, the client process is
> considered to be responsible for the channel until it its unique
> name disappears from the bus.
> 
>@@ -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">
>+ The Channel object. Its well-known bus name is the same
>+ as that of the Connection.
>+ </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">
>+ Properties of the channel, equivalent to
>+ the properties in <tp:type>Channel_Details</tp:type>.
> </tp:docstring>
> </arg>
> 
> <arg name="Requests_Satisfied" type="ao" direction="in">
> <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
>- The requests satisfied by these channels.
>+ The requests satisfied by this channel.
> 
> <tp:rationale>
> 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.
> 
>@@ -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">
>- Additional information about these channels. Currently defined
>+ Additional information about this channel. Currently defined
> keys are:
> 
> <dl>
>diff --git a/spec/Client_Interface_Requests.xml b/spec/Client_Interface_Requests.xml
>index f515aba..c96a29b 100644
>--- a/spec/Client_Interface_Requests.xml
>+++ b/spec/Client_Interface_Requests.xml
>@@ -54,7 +54,7 @@
> 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.
> 
> <tp:rationale>
>diff --git a/spec/Client_Observer.xml b/spec/Client_Observer.xml
>index b899742..4511bfd 100644
>--- a/spec/Client_Observer.xml
>+++ b/spec/Client_Observer.xml
>@@ -267,7 +267,7 @@ Recover=true
> to avoid the following race: text channel logger (observer) gets
> ObserveChannel, 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.
> </tp:rationale>
>@@ -356,7 +356,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>
>-- 
>1.8.4.2
>

Actions: View | Splinter Review

Attachments on bug 69430: 88629 | 88630 | 88631 | 88632 | 88633 | 88634 | 88635 | 88636 | 88637 | 88638 | 88639 | 88640 | 92141

Use of freedesktop.org services, including Bugzilla, is subject to our Code of Conduct. How we collect and use information is described in our Privacy Policy.