From 433695f0f362214cc54fbffce85c18d5c8de46a2 Mon Sep 17 00:00:00 2001 From: Simon McVittie Date: Mon, 4 Nov 2013 15:21:19 +0000 Subject: [PATCH 03/12] 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 --- doc/templates/interface.html | 4 ++-- spec/Channel.xml | 2 +- spec/Channel_Dispatch_Operation.xml | 41 +++++++++------------------------- spec/Channel_Interface_Conference1.xml | 4 ++-- spec/Channel_Interface_SMS1.xml | 2 +- spec/Channel_Interface_Tube1.xml | 2 +- spec/Channel_Request.xml | 2 +- spec/Channel_Type_Call1.xml | 6 ++--- spec/Channel_Type_Contact_Search1.xml | 2 +- spec/Channel_Type_Text.xml | 4 ++-- spec/Client_Observer.xml | 21 +++++------------ spec/Connection.xml | 35 ++++++++++++++++++----------- 12 files changed, 52 insertions(+), 73 deletions(-) diff --git a/doc/templates/interface.html b/doc/templates/interface.html index 981f67e..0ede036 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 NewChannels + of NewChannel 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 NewChannels + of NewChannel signals. #else change. diff --git a/spec/Channel.xml b/spec/Channel.xml index 69f52d6..f93043d 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.Each channel has a number of immutable properties (which cannot vary after the channel has been announced with NewChannels), + namespace='imt1.Connection'>NewChannel), provided to clients in the ObserveChannels, AddDispatchOperation and diff --git a/spec/Channel_Dispatch_Operation.xml b/spec/Channel_Dispatch_Operation.xml index 9da09fd..26deb7d 100644 --- a/spec/Channel_Dispatch_Operation.xml +++ b/spec/Channel_Dispatch_Operation.xml @@ -36,50 +36,29 @@ from outgoing requests for channels.

More specifically, whenever the Connection.NewChannels - signal contains channels whose Connection.NewChannel + signal contains a channel whose Requested - property is false, one or more ChannelDispatchOperation - objects are created for those channels.

- -

(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.)

- -

First, the channel dispatcher SHOULD construct a list of all the - Handlers - that could handle all the channels (based on their HandlerChannelFilter - 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.

+ property is false, a ChannelDispatchOperation + object is created for that channel.

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 Channel.Interface.Destroyable1.Destroy if supported, or Channel.Close otherwise.

-

When listing channel handlers, priority SHOULD be given to - channel handlers that are already handling channels from the same - bundle.

-

If a handler with BypassApproval - = True could handle all of the channels in the dispatch + = True could handle the channel in the dispatch operation, then the channel dispatcher SHOULD call HandleChannels on that handler, and (assuming the call succeeds) emit - Finished and stop processing those - channels without involving any approvers.

+ Finished and stop processing that + channel without involving any approvers.

Some channel types can be picked up "quietly" by an existing @@ -95,14 +74,14 @@

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 AddDispatchOperation for more details on this.

Finally, if the approver requested it, the channel dispatcher SHOULD - send the channels to a handler.

+ send the channel to a handler.

+ channel is announced via the NewChannel signal.

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"].

diff --git a/spec/Channel_Interface_SMS1.xml b/spec/Channel_Interface_SMS1.xml index a4f1d74..ab23b3d 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.

This property is immutable (cannot change), and therefore SHOULD appear wherever immutable properties are reported, e.g. NewChannels signals.

+ >NewChannel signals.

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 d4eeb6a..3d43a2d 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.

When receiving an incoming tube, this property is immutable and so advertised in the NewChannels + namespace="im.telepathy.v1.Connection">NewChannel signal.

 diff --git a/spec/Channel_Request.xml b/spec/Channel_Request.xml index 4e52d5b..b36b0a6 100644 --- a/spec/Channel_Request.xml +++ b/spec/Channel_Request.xml @@ -323,7 +323,7 @@

The same immutable properties of the Channel that would appear in a NewChannels signal.

+ >NewChannel signal.

 diff --git a/spec/Channel_Type_Call1.xml b/spec/Channel_Type_Call1.xml index 5260e8e..dcf4c6f 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.

When an incoming call occurs, something like the following NewChannels + namespace="imt1.Connection">NewChannel signal will occur:

-NewChannels([
+NewChannel(
   /im/telepathy/v1/Connection/foo/bar/foo_40bar_2ecom/CallChannel,
   {
     ...ChannelType: ...InitialAudioName: "audio",
     ...InitialVideoName: "video",
     ...MutableContents: True,
-  }])
+ })

The InitialAudio and InitialVideo properties show that diff --git a/spec/Channel_Type_Contact_Search1.xml b/spec/Channel_Type_Contact_Search1.xml index 9fdab7f..2841ae0 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. It can be in the NewChannels + namespace="im.telepathy.v1.Connection">NewChannel signal for round-trip reduction. diff --git a/spec/Channel_Type_Text.xml b/spec/Channel_Type_Text.xml index 5c1707a..780ff5f 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.NewChannels + namespace="imt1.Connection">NewChannel signal. The new channel should resemble the old channel, but have Requested = FALSE regardless of its previous value; the UI calls Close on text channel

  • text channel emits Closed and closes
  • message arrives
    • -
  • new text channel is created, connection emits NewChannels
    • +
  • new text channel is created, connection emits NewChannel
  • (the same or a different) UI handles it
    • diff --git a/spec/Client_Observer.xml b/spec/Client_Observer.xml index 5ad32eb..a21078f 100644 --- a/spec/Client_Observer.xml +++ b/spec/Client_Observer.xml @@ -120,10 +120,10 @@

    A specification of the channels in which this observer is interested. The ObserveChannels method - should be called by the channel dispatcher whenever any of the new - channels in a NewChannels - signal match this description.

    + should be called by the channel dispatcher whenever the new + channel in a NewChannel + signal matches this description.

    Only certain D-Bus types have useful semantics for matching like this, so only certain types are allowed:

    @@ -253,20 +253,11 @@ Recover=true -

    Called by the channel dispatcher when channels in which the +

    Called by the channel dispatcher when a channel in which the observer has registered an interest are announced in a NewChannels + namespace="im.telepathy.v1.Connection">NewChannel signal.

    -

    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.

    - -

    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.

    -

    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).

    diff --git a/spec/Connection.xml b/spec/Connection.xml index b4414ca..1a40ea1 100644 --- a/spec/Connection.xml +++ b/spec/Connection.xml @@ -695,7 +695,7 @@ USA.

    race condition would be likely to exist in some cases:

      -
    • NewChannels or Get("Channels") includes a property P with +
    • NewChannel or Get("Channels") includes a property P with value V1
    • Client creates a proxy object for the channel
    • The value of P changes to V2
      • @@ -777,12 +777,12 @@ USA.

      The Channel object, which MUST NOT be signalled with - NewChannels until after this method + NewChannel until after this method returns.

      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.

             @@ -917,12 +917,12 @@ USA.

      The Channel object. If it was created as a result of this method call, it MUST NOT be signalled by - NewChannels until after this method + NewChannel until after this method returns.

      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.

             @@ -998,14 +998,15 @@ USA.

      - - (as part of Connection) + + -

      A new channel has been created. The connection manager - SHOULD emit a single signal for each channel created.

      +

      A new channel has been created.

      -

      For example, joining a MUC Tube in XMPP requires joining the +

      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 Text channel @@ -1021,9 +1022,17 @@ USA.

       - + - The channels and their details. + The object path of the channel. + + + + + +

      The same properties of the channel that would appear in the + Channel_Details struct.

             @@ -1034,7 +1043,7 @@ USA.

      A list of all the channels which currently exist on this connection. Change notification is via the - NewChannels and + NewChannel and ChannelClosed signals. -- 1.8.4.2