From 7b2a2fd4b7ff0b7a42118f1bd22a30e43df63b6e Mon Sep 17 00:00:00 2001 From: Guillaume Desmottes Date: Wed, 15 Jan 2014 14:23:27 +0100 Subject: [PATCH] move RequestableChannelClasses to Connection --- doc/templates/interface.html | 4 +- spec/Channel_Interface_Addressing1.xml | 2 +- spec/Channel_Interface_Conference1.xml | 10 +- spec/Channel_Type_Call1.xml | 2 +- spec/Channel_Type_Contact_Search1.xml | 4 +- spec/Channel_Type_File_Transfer1.xml | 2 +- spec/Connection.xml | 141 ++++++++++++++++++++ .../Connection_Interface_Contact_Capabilities1.xml | 3 +- spec/Connection_Interface_Requests.xml | 145 +-------------------- spec/Protocol.xml | 4 +- spec/Protocol_Interface_Addressing1.xml | 2 +- 11 files changed, 159 insertions(+), 160 deletions(-) diff --git a/doc/templates/interface.html b/doc/templates/interface.html index 221b15f..1ff7889 100644 --- a/doc/templates/interface.html +++ b/doc/templates/interface.html @@ -380,7 +380,7 @@ and ChannelDispatcher. If supported on this protocol, the property should appear in either the Fixed_Properties or Allowed_Properties of - a RequestableChannelClass + a RequestableChannelClass advertised by the CM. #elif $property.requestable:
This property @@ -394,7 +394,7 @@ and ChannelDispatcher. The property should also appear in either the Fixed_Properties or Allowed_Properties of - a RequestableChannelClass + a RequestableChannelClass advertised by the CM.
#end if diff --git a/spec/Channel_Interface_Addressing1.xml b/spec/Channel_Interface_Addressing1.xml index 7b4ff43..70c7bd4 100644 --- a/spec/Channel_Interface_Addressing1.xml +++ b/spec/Channel_Interface_Addressing1.xml @@ -55,7 +55,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.

While this seems redundant, since the scheme is included in TargetURI, it exists for constructing - RequestableChannelClasses + RequestableChannelClasses that support a limited set of URI schemes.

diff --git a/spec/Channel_Interface_Conference1.xml b/spec/Channel_Interface_Conference1.xml index d4a42d5..91ea7b4 100644 --- a/spec/Channel_Interface_Conference1.xml +++ b/spec/Channel_Interface_Conference1.xml @@ -50,7 +50,7 @@ If InitialInviteeHandles and InitialInviteeIDs are Allowed_Properties in RequestableChannelClasses, + namespace="imt1.Connection">RequestableChannelClasses, ad-hoc conferences to a set of contacts may be created by requesting a channel, specifying InitialInviteeHandles and/or @@ -204,7 +204,7 @@ TargetHandle of C1 into Cn), then immediately inviting the TargetHandle of C2, the TargetHandle of C3, etc. into Cn as well.

-

Sample Sample RequestableChannelClasses

A GSM connection might advertise the following channel class for @@ -366,7 +366,7 @@ InitialInviteeHandles and InitialInviteeIDs are Allowed_Properties in RequestableChannelClasses, then requests with zero or one channel paths SHOULD also succeed; otherwise, clients SHOULD NOT make requests with zero or one paths for this property.

@@ -428,7 +428,7 @@ (as opposed to merging several channels into one new conference channel), this property SHOULD be requestable, and appear in the allowed properties in RequestableChannelClasses. Otherwise, this property SHOULD NOT be requestable, and its value SHOULD always be the empty list.

@@ -521,7 +521,7 @@

This property SHOULD be requestable, and appear in the allowed properties in RequestableChannelClasses, in protocols where invitations can have an accompanying text message.

diff --git a/spec/Channel_Type_Call1.xml b/spec/Channel_Type_Call1.xml index 4055238..7d645f8 100644 --- a/spec/Channel_Type_Call1.xml +++ b/spec/Channel_Type_Call1.xml @@ -267,7 +267,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.

Requestable channel classes

The RequestableChannelClasses + namespace="imt1.Connection">RequestableChannelClasses for Call1 channels can be:

diff --git a/spec/Channel_Type_Contact_Search1.xml b/spec/Channel_Type_Contact_Search1.xml index 535f884..3a214bd 100644 --- a/spec/Channel_Type_Contact_Search1.xml +++ b/spec/Channel_Type_Contact_Search1.xml @@ -37,7 +37,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.

Connections that support contact search channels SHOULD have an entry - in RequestableChannelClasses with the ChannelType fixed to this interface, @@ -56,7 +56,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.Requests for channels of this type need only optionally specify the Server property (if it is an allowed property in the connection's RequestableChannelClasses).

+ namespace='imt1.Connection'>RequestableChannelClasses).

Before searching, the AvailableSearchKeys property should be diff --git a/spec/Channel_Type_File_Transfer1.xml b/spec/Channel_Type_File_Transfer1.xml index 67ccf11..1fc54fb 100644 --- a/spec/Channel_Type_File_Transfer1.xml +++ b/spec/Channel_Type_File_Transfer1.xml @@ -159,7 +159,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.For each supported hash type, implementations SHOULD include an entry in RequestableChannelClasses + namespace="imt1.Connection">RequestableChannelClasses with this property fixed to that hash type. If the protocol supports offering a file without a content hash, implementations SHOULD list this property in Allowed in a requestable channel class, mapping hash diff --git a/spec/Connection.xml b/spec/Connection.xml index 86b9a05..a7f6ac5 100644 --- a/spec/Connection.xml +++ b/spec/Connection.xml @@ -846,6 +846,147 @@ USA.

+ + (as stable API) + +

Mapping representing a class of channels that can be requested + from a connection manager, can be handled by a user interface, + are supported by a contact, etc.

+ +

Classes of channel are identified by the fixed values of + a subset of their properties.

+ +

Channel classes SHOULD always include the keys + im.telepathy.v1.Channel.ChannelType + and + im.telepathy.v1.Channel.TargetHandleType.

+ + + + + A D-Bus interface name, followed by a dot and a D-Bus property name. + + + + + + The value of the property. + + + + + + (as stable API) + +

Structure representing a class of channels that can be requested, + identified by a set of properties that identify that class of + channel.

+ + +

This will often just be the channel type and the handle type, + but can include other properties of the channel - for instance, + encrypted channels might require properties that + unencrypted channels do not, like an encryption key.

+ + +

In some cases, these classes of channel may overlap, in the sense + that one class fixes all the properties that another class does, + plus some more properties.

+ + +

For older clients to still be able to understand how to request + channels in the presence of a hypothetical "encryption" interface, + we'd need to represent it like this:

+ +
    +
  • class 1: ChannelType = Text, TargetHandleType = CONTACT
    • +
  • class 2: Channel.ChannelType = Text, + Channel.TargetHandleType = CONTACT, + Encryption.Encrypted = TRUE
    • +
+ + + + + +

The property values that identify this requestable channel class. + These properties MUST be included in requests for a channel of this + class, and MUST take these values.

+ +

Clients that do not understand the semantics of all the + Fixed_Properties MUST NOT request channels of this class, since + they would be unable to avoid making an incorrect request.

+ +

This implies that connection managers wishing to make channels + available to old or minimal clients SHOULD have a channel class + with the minimum number of Fixed_Properties, and MAY additionally + have channel classes with extra Fixed_Properties.

+ +

Interface designers SHOULD avoid introducing fixed properties + whose types are not serializable in a .manager + file.

+ + +

Connection managers with a fixed property that is not + serializable cannot have a complete .manager + file.

+ + + + + + +

Properties that MAY be set when requesting a channel of this + channel type and handle type.

+ +

This array MUST NOT include properties that are in the + Fixed_Properties mapping.

+ +

Properties in this array may either be required or optional, + according to their documented semantics.

+ + +

For instance, if + TargetHandleType takes a value that is not Handle_Type_None, + one or the other of TargetHandle and TargetID is required. + Clients are expected to understand the documented relationship + between the properties, so we do not have separate arrays + of required and optional properties.

+ + + + + + + (as stable API) + +

The classes of channel that are expected to be available on this + connection, i.e. those for which + CreateChannel can reasonably + be expected to succeed. User interfaces can use this information + to show or hide UI components.

+ +

This property cannot change after the connection has gone to + state Connection_Status_Connected, so there is no change + notification (if the connection has context-dependent capabilities, + it SHOULD advertise support for all classes of channel that it might + support during its lifetime). Before this state has been reached, + the value of this property is undefined.

+ + +

This is not on an optional interface, because connection + managers can always offer some sort of clue about the channel + classes they expect to support (at worst, they can announce + support for everything for which they have code).

+ + + +

This models a connection to a single user account on a communication service. Its basic capability is to provide the facility to request and diff --git a/spec/Connection_Interface_Contact_Capabilities1.xml b/spec/Connection_Interface_Contact_Capabilities1.xml index 51400cb..d390a67 100644 --- a/spec/Connection_Interface_Contact_Capabilities1.xml +++ b/spec/Connection_Interface_Contact_Capabilities1.xml @@ -194,8 +194,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.

The contact's capabilities. These should be represented in the same way as in RequestableChannelClasses, + namespace="imt1.Connection">RequestableChannelClasses, except that they may have more fixed properties or fewer allowed properties, to represent contacts who do not have all the capabilities of the connection.

diff --git a/spec/Connection_Interface_Requests.xml b/spec/Connection_Interface_Requests.xml index d18e5e3..b7e82b0 100644 --- a/spec/Connection_Interface_Requests.xml +++ b/spec/Connection_Interface_Requests.xml @@ -201,7 +201,7 @@ The request matched the fixed properties of a Requestable_Channel_Class in - RequestableChannelClasses, but the + RequestableChannelClasses, but the allowed arguments did not make sense; for example, a RoomList1 was requested, but the The request matched the fixed properties of a Requestable_Channel_Class in - RequestableChannelClasses, but the + RequestableChannelClasses, but the allowed arguments did not make sense; for example, a RoomList1 was requested, but the - - (as stable API) - -

Mapping representing a class of channels that can be requested - from a connection manager, can be handled by a user interface, - are supported by a contact, etc.

- -

Classes of channel are identified by the fixed values of - a subset of their properties.

- -

Channel classes SHOULD always include the keys - im.telepathy.v1.Channel.ChannelType - and - im.telepathy.v1.Channel.TargetHandleType.

- - - - - A D-Bus interface name, followed by a dot and a D-Bus property name. - - - - - - The value of the property. - - - - - - (as stable API) - -

Structure representing a class of channels that can be requested, - identified by a set of properties that identify that class of - channel.

- - -

This will often just be the channel type and the handle type, - but can include other properties of the channel - for instance, - encrypted channels might require properties that - unencrypted channels do not, like an encryption key.

- - -

In some cases, these classes of channel may overlap, in the sense - that one class fixes all the properties that another class does, - plus some more properties.

- - -

For older clients to still be able to understand how to request - channels in the presence of a hypothetical "encryption" interface, - we'd need to represent it like this:

- -
    -
  • class 1: ChannelType = Text, TargetHandleType = CONTACT
    • -
  • class 2: Channel.ChannelType = Text, - Channel.TargetHandleType = CONTACT, - Encryption.Encrypted = TRUE
    • -
- - - - - -

The property values that identify this requestable channel class. - These properties MUST be included in requests for a channel of this - class, and MUST take these values.

- -

Clients that do not understand the semantics of all the - Fixed_Properties MUST NOT request channels of this class, since - they would be unable to avoid making an incorrect request.

- -

This implies that connection managers wishing to make channels - available to old or minimal clients SHOULD have a channel class - with the minimum number of Fixed_Properties, and MAY additionally - have channel classes with extra Fixed_Properties.

- -

Interface designers SHOULD avoid introducing fixed properties - whose types are not serializable in a .manager - file.

- - -

Connection managers with a fixed property that is not - serializable cannot have a complete .manager - file.

- - - - - - -

Properties that MAY be set when requesting a channel of this - channel type and handle type.

- -

This array MUST NOT include properties that are in the - Fixed_Properties mapping.

- -

Properties in this array may either be required or optional, - according to their documented semantics.

- - -

For instance, if - TargetHandleType takes a value that is not Handle_Type_None, - one or the other of TargetHandle and TargetID is required. - Clients are expected to understand the documented relationship - between the properties, so we do not have separate arrays - of required and optional properties.

- - - - - - - (as stable API) - -

The classes of channel that are expected to be available on this - connection, i.e. those for which - CreateChannel can reasonably - be expected to succeed. User interfaces can use this information - to show or hide UI components.

- -

This property cannot change after the connection has gone to - state Connection_Status_Connected, so there is no change - notification (if the connection has context-dependent capabilities, - it SHOULD advertise support for all classes of channel that it might - support during its lifetime). Before this state has been reached, - the value of this property is undefined.

- - -

This is not on an optional interface, because connection - managers can always offer some sort of clue about the channel - classes they expect to support (at worst, they can announce - support for everything for which they have code).

- - - - diff --git a/spec/Protocol.xml b/spec/Protocol.xml index a729393..8b525bd 100644 --- a/spec/Protocol.xml +++ b/spec/Protocol.xml @@ -153,8 +153,8 @@ allowed=im.telepathy.v1.Channel.TargetHandle;im.telepathy.v1.Channel.TargetID; Connection to this protocol (i.e. they will, or might, appear in the Connection's RequestableChannelClasses property).

+ namespace="imt1.Connection">RequestableChannelClasses + property).

Whether a Connection will have all, some or none of these requestable channel classes depends on server capabilities; diff --git a/spec/Protocol_Interface_Addressing1.xml b/spec/Protocol_Interface_Addressing1.xml index f42770f..939c13d 100644 --- a/spec/Protocol_Interface_Addressing1.xml +++ b/spec/Protocol_Interface_Addressing1.xml @@ -116,7 +116,7 @@ AddressableURISchemes=tel;sip; offline. When it is connected the addressable URI schemes should be retrieved from the Requests.RequestableChannelClasses's + namespace="imt1.Connection">RequestableChannelClasses's TargetURIScheme fixed-property instead.

Connection managers with a .manager file -- 1.8.4.2