diff options
Diffstat (limited to 'spec')
| -rw-r--r-- | spec/Channel.xml | 2 | ||||
| -rw-r--r-- | spec/Channel_Dispatch_Operation.xml | 16 | ||||
| -rw-r--r-- | spec/Channel_Dispatcher.xml | 8 | ||||
| -rw-r--r-- | spec/Channel_Request.xml | 4 | ||||
| -rw-r--r-- | spec/Client_Handler.xml | 48 | ||||
| -rw-r--r-- | spec/Client_Interface_Requests.xml | 2 | ||||
| -rw-r--r-- | spec/Client_Observer.xml | 4 |
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> |