Skip to content

GitLab

T
telepathy-spec
Commit b9dfcdad authored by Simon McVittie's avatar Simon McVittie Committed by Guillaume Desmottes
Browse files
Options

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
parent 28c6e0d0
Hide whitespace changes
Inline Side-by-side
Showing with 52 additions and 73 deletions
doc/templates/interface.html
View file @ b9dfcdad
......@@ -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.
......
spec/Channel.xml
View file @ b9dfcdad
......@@ -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
......
spec/Channel_Dispatch_Operation.xml
View file @ b9dfcdad
......@@ -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"
......
spec/Channel_Interface_Conference1.xml
View file @ b9dfcdad
......@@ -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>
......
spec/Channel_Interface_SMS1.xml
View file @ b9dfcdad
......@@ -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
......
spec/Channel_Interface_Tube1.xml
View file @ b9dfcdad
......@@ -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>
......
spec/Channel_Request.xml
View file @ b9dfcdad
......@@ -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>
......
spec/Channel_Type_Call1.xml
View file @ b9dfcdad
......@@ -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
......
spec/Channel_Type_Contact_Search1.xml
View file @ b9dfcdad
......@@ -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>
......
spec/Channel_Type_Text.xml
View file @ b9dfcdad
......@@ -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>
......
spec/Client_Observer.xml
View file @ b9dfcdad
......@@ -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>
......
spec/Connection.xml
View file @ b9dfcdad
......@@ -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>
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment