Commit 389f2345 authored by Guillaume Desmottes's avatar Guillaume Desmottes 🐐

move RequestableChannelClasses to Connection

parent 4f3bd603
......@@ -380,7 +380,7 @@
and <a href="Channel_Dispatcher.html">ChannelDispatcher</a>.
If supported on this protocol, the property should appear in either the
Fixed_Properties or Allowed_Properties of
a <a href="Connection_Interface_Requests.html#im.telepathy.v1.Connection.Interface.Requests.RequestableChannelClasses">RequestableChannelClass</a>
a <a href="Connection.html#im.telepathy.v1.Connection.RequestableChannelClasses">RequestableChannelClass</a>
advertised by the CM.</div>
#elif $property.requestable:
<div class="annotation requestable">This property
......@@ -394,7 +394,7 @@
and <a href="Channel_Dispatcher.html">ChannelDispatcher</a>.
The property should also appear in either the Fixed_Properties
or Allowed_Properties of
a <a href="Connection_Interface_Requests.html#im.telepathy.v1.Connection.Interface.Requests.RequestableChannelClasses">RequestableChannelClass</a>
a <a href="Connection.html#im.telepathy.v1.Connection.RequestableChannelClasses">RequestableChannelClass</a>
advertised by the CM.</div>
#end if
......
......@@ -55,7 +55,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
<tp:rationale>
<p>While this seems redundant, since the scheme is included in
<tp:member-ref>TargetURI</tp:member-ref>, it exists for constructing
<tp:dbus-ref namespace="im.telepathy.v1.Connection.Interface.Requests">RequestableChannelClasses</tp:dbus-ref>
<tp:dbus-ref namespace="imt1.Connection">RequestableChannelClasses</tp:dbus-ref>
that support a limited set of URI schemes.</p>
</tp:rationale>
......
......@@ -50,7 +50,7 @@
If <tp:member-ref>InitialInviteeHandles</tp:member-ref> and
<tp:member-ref>InitialInviteeIDs</tp:member-ref> are
<var>Allowed_Properties</var> in <tp:dbus-ref
namespace="im.telepathy.v1.Connection.Interface.Requests">RequestableChannelClasses</tp:dbus-ref>,
namespace="imt1.Connection">RequestableChannelClasses</tp:dbus-ref>,
ad-hoc conferences to a set of contacts may be created by requesting a
channel, specifying
<tp:member-ref>InitialInviteeHandles</tp:member-ref> 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.</p>
<h4>Sample <tp:dbus-ref namespace='imt1.Connection.Interface.Requests'
<h4>Sample <tp:dbus-ref namespace='imt1.Connection'
>RequestableChannelClasses</tp:dbus-ref></h4>
<p>A GSM connection might advertise the following channel class for
......@@ -366,7 +366,7 @@
<tp:member-ref>InitialInviteeHandles</tp:member-ref> and
<tp:member-ref>InitialInviteeIDs</tp:member-ref> are
<var>Allowed_Properties</var> in <tp:dbus-ref
namespace='imt1.Connection.Interface.Requests'
namespace='imt1.Connection'
>RequestableChannelClasses</tp:dbus-ref>, 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.</p>
......@@ -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 <tp:dbus-ref
namespace="im.telepathy.v1.Connection.Interface.Requests"
namespace="imt1.Connection"
>RequestableChannelClasses</tp:dbus-ref>. Otherwise, this property
SHOULD NOT be requestable, and its value SHOULD always be the empty
list.</p>
......@@ -521,7 +521,7 @@
<p>This property SHOULD be requestable, and appear in the allowed
properties in <tp:dbus-ref
namespace="im.telepathy.v1.Connection.Interface.Requests"
namespace="imt1.Connection"
>RequestableChannelClasses</tp:dbus-ref>, in protocols where
invitations can have an accompanying text message.</p>
......
......@@ -267,7 +267,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
<h4>Requestable channel classes</h4>
<p>The <tp:dbus-ref
namespace="imt1.Connection.Interface.Requests">RequestableChannelClasses</tp:dbus-ref>
namespace="imt1.Connection">RequestableChannelClasses</tp:dbus-ref>
for <tp:dbus-ref
namespace="imt1.Channel.Type">Call1</tp:dbus-ref> channels
can be:</p>
......
......@@ -37,7 +37,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
found.</p>
<p>Connections that support contact search channels SHOULD have an entry
in <tp:dbus-ref namespace='imt1.Connection.Interface.Requests'
in <tp:dbus-ref namespace='imt1.Connection'
>RequestableChannelClasses</tp:dbus-ref> with the <tp:dbus-ref
namespace='imt1.Channel'>ChannelType</tp:dbus-ref> fixed to this
interface,
......@@ -56,7 +56,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
<p>Requests for channels of this type need only
optionally specify the <tp:member-ref>Server</tp:member-ref> property
(if it is an allowed property in the connection's <tp:dbus-ref
namespace='imt1.Connection.Interface.Requests'>RequestableChannelClasses</tp:dbus-ref>).</p>
namespace='imt1.Connection'>RequestableChannelClasses</tp:dbus-ref>).</p>
<p>Before searching, the
<tp:member-ref>AvailableSearchKeys</tp:member-ref> property should be
......
......@@ -159,7 +159,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
<p>For each supported hash type, implementations SHOULD include an entry
in <tp:dbus-ref
namespace="im.telepathy.v1.Connection.Interface.Requests">RequestableChannelClasses</tp:dbus-ref>
namespace="imt1.Connection">RequestableChannelClasses</tp:dbus-ref>
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
......
......@@ -846,6 +846,147 @@ USA.</p>
</tp:possible-errors>
</method>
<tp:mapping name="Channel_Class" array-name="Channel_Class_List">
<tp:added version="0.17.11">(as stable API)</tp:added>
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
<p>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.</p>
<p>Classes of channel are identified by the fixed values of
a subset of their properties.</p>
<p>Channel classes SHOULD always include the keys
<tp:dbus-ref>im.telepathy.v1.Channel.ChannelType</tp:dbus-ref>
and
<tp:dbus-ref>im.telepathy.v1.Channel.TargetHandleType</tp:dbus-ref>.</p>
</tp:docstring>
<tp:member type="s" name="Key" tp:type="DBus_Qualified_Member">
<tp:docstring>
A D-Bus interface name, followed by a dot and a D-Bus property name.
</tp:docstring>
</tp:member>
<tp:member type="v" name="Value">
<tp:docstring>
The value of the property.
</tp:docstring>
</tp:member>
</tp:mapping>
<tp:struct name="Requestable_Channel_Class"
array-name="Requestable_Channel_Class_List">
<tp:added version="0.17.11">(as stable API)</tp:added>
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
<p>Structure representing a class of channels that can be requested,
identified by a set of properties that identify that class of
channel.</p>
<tp:rationale>
<p>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.</p>
</tp:rationale>
<p>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.</p>
<tp:rationale>
<p>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:</p>
<ul>
<li>class 1: ChannelType = Text, TargetHandleType = CONTACT</li>
<li>class 2: Channel.ChannelType = Text,
Channel.TargetHandleType = CONTACT,
Encryption.Encrypted = TRUE</li>
</ul>
</tp:rationale>
</tp:docstring>
<tp:member name="Fixed_Properties" type="a{sv}"
tp:type="Channel_Class">
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
<p>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.</p>
<p>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.</p>
<p>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.</p>
<p>Interface designers SHOULD avoid introducing fixed properties
whose types are not serializable in a <code>.manager</code>
file.</p>
<tp:rationale>
<p>Connection managers with a fixed property that is not
serializable cannot have a complete <code>.manager</code>
file.</p>
</tp:rationale>
</tp:docstring>
</tp:member>
<tp:member name="Allowed_Properties" type="as"
tp:type="DBus_Qualified_Member[]">
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
<p>Properties that MAY be set when requesting a channel of this
channel type and handle type.</p>
<p>This array MUST NOT include properties that are in the
Fixed_Properties mapping.</p>
<p>Properties in this array may either be required or optional,
according to their documented semantics.</p>
<tp:rationale>
<p>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.</p>
</tp:rationale>
</tp:docstring>
</tp:member>
</tp:struct>
<property name="RequestableChannelClasses" access="read"
type="a(a{sv}as)" tp:type="Requestable_Channel_Class[]"
tp:name-for-bindings="Requestable_Channel_Classes">
<tp:added version="0.17.11">(as stable API)</tp:added>
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
<p>The classes of channel that are expected to be available on this
connection, i.e. those for which
<tp:dbus-ref namespace="im.telepathy.v1.Connection.Interface.Requests">CreateChannel</tp:dbus-ref> can reasonably
be expected to succeed. User interfaces can use this information
to show or hide UI components.</p>
<p>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.</p>
<tp:rationale>
<p>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).</p>
</tp:rationale>
</tp:docstring>
</property>
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
<p>This models a connection to a single user account on a communication
service. Its basic capability is to provide the facility to request and
......
......@@ -194,8 +194,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
<p>The contact's capabilities. These should be represented
in the same way as in <tp:dbus-ref
namespace="im.telepathy.v1.Connection.Interface.Requests"
>RequestableChannelClasses</tp:dbus-ref>,
namespace="imt1.Connection">RequestableChannelClasses</tp:dbus-ref>,
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.</p>
......
......@@ -201,7 +201,7 @@
<tp:docstring>
The request matched the fixed properties of a
<tp:type>Requestable_Channel_Class</tp:type> in
<tp:member-ref>RequestableChannelClasses</tp:member-ref>, but the
<tp:dbus-ref namespace="imt1.Connection">RequestableChannelClasses</tp:dbus-ref>, but the
allowed arguments did not make sense; for example, a <tp:dbus-ref
namespace="im.telepathy.v1.Channel.Type">RoomList1</tp:dbus-ref>
was requested, but the <tp:dbus-ref
......@@ -345,7 +345,7 @@
<tp:docstring>
The request matched the fixed properties of a
<tp:type>Requestable_Channel_Class</tp:type> in
<tp:member-ref>RequestableChannelClasses</tp:member-ref>, but the
<tp:dbus-ref namespace="imt1.Connection">RequestableChannelClasses</tp:dbus-ref>, but the
allowed arguments did not make sense; for example, a <tp:dbus-ref
namespace="im.telepathy.v1.Channel.Type">RoomList1</tp:dbus-ref>
was requested, but the <tp:dbus-ref
......@@ -449,147 +449,6 @@
</arg>
</signal>
<tp:mapping name="Channel_Class" array-name="Channel_Class_List">
<tp:added version="0.17.11">(as stable API)</tp:added>
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
<p>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.</p>
<p>Classes of channel are identified by the fixed values of
a subset of their properties.</p>
<p>Channel classes SHOULD always include the keys
<tp:dbus-ref>im.telepathy.v1.Channel.ChannelType</tp:dbus-ref>
and
<tp:dbus-ref>im.telepathy.v1.Channel.TargetHandleType</tp:dbus-ref>.</p>
</tp:docstring>
<tp:member type="s" name="Key" tp:type="DBus_Qualified_Member">
<tp:docstring>
A D-Bus interface name, followed by a dot and a D-Bus property name.
</tp:docstring>
</tp:member>
<tp:member type="v" name="Value">
<tp:docstring>
The value of the property.
</tp:docstring>
</tp:member>
</tp:mapping>
<tp:struct name="Requestable_Channel_Class"
array-name="Requestable_Channel_Class_List">
<tp:added version="0.17.11">(as stable API)</tp:added>
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
<p>Structure representing a class of channels that can be requested,
identified by a set of properties that identify that class of
channel.</p>
<tp:rationale>
<p>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.</p>
</tp:rationale>
<p>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.</p>
<tp:rationale>
<p>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:</p>
<ul>
<li>class 1: ChannelType = Text, TargetHandleType = CONTACT</li>
<li>class 2: Channel.ChannelType = Text,
Channel.TargetHandleType = CONTACT,
Encryption.Encrypted = TRUE</li>
</ul>
</tp:rationale>
</tp:docstring>
<tp:member name="Fixed_Properties" type="a{sv}"
tp:type="Channel_Class">
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
<p>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.</p>
<p>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.</p>
<p>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.</p>
<p>Interface designers SHOULD avoid introducing fixed properties
whose types are not serializable in a <code>.manager</code>
file.</p>
<tp:rationale>
<p>Connection managers with a fixed property that is not
serializable cannot have a complete <code>.manager</code>
file.</p>
</tp:rationale>
</tp:docstring>
</tp:member>
<tp:member name="Allowed_Properties" type="as"
tp:type="DBus_Qualified_Member[]">
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
<p>Properties that MAY be set when requesting a channel of this
channel type and handle type.</p>
<p>This array MUST NOT include properties that are in the
Fixed_Properties mapping.</p>
<p>Properties in this array may either be required or optional,
according to their documented semantics.</p>
<tp:rationale>
<p>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.</p>
</tp:rationale>
</tp:docstring>
</tp:member>
</tp:struct>
<property name="RequestableChannelClasses" access="read"
type="a(a{sv}as)" tp:type="Requestable_Channel_Class[]"
tp:name-for-bindings="Requestable_Channel_Classes">
<tp:added version="0.17.11">(as stable API)</tp:added>
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
<p>The classes of channel that are expected to be available on this
connection, i.e. those for which
<tp:member-ref>CreateChannel</tp:member-ref> can reasonably
be expected to succeed. User interfaces can use this information
to show or hide UI components.</p>
<p>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.</p>
<tp:rationale>
<p>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).</p>
</tp:rationale>
</tp:docstring>
</property>
</interface>
</node>
<!-- vim:set sw=2 sts=2 et ft=xml: -->
......@@ -153,8 +153,8 @@ allowed=im.telepathy.v1.Channel.TargetHandle;im.telepathy.v1.Channel.TargetID;
<tp:dbus-ref namespace="im.telepathy.v1"
>Connection</tp:dbus-ref> to this protocol (i.e. they will,
or might, appear in the Connection's <tp:dbus-ref
namespace="im.telepathy.v1.Connection.Interface.Requests"
>RequestableChannelClasses</tp:dbus-ref> property).</p>
namespace="imt1.Connection">RequestableChannelClasses</tp:dbus-ref>
property).</p>
<p>Whether a Connection will have all, some or none of these
requestable channel classes depends on server capabilities;
......
......@@ -116,7 +116,7 @@ AddressableURISchemes=tel;sip;
offline. When it is connected the addressable URI schemes should be
retrieved from the
<tp:dbus-ref
namespace="im.telepathy.v1.Connection.Interface">Requests.RequestableChannelClasses</tp:dbus-ref>'s
namespace="imt1.Connection">RequestableChannelClasses</tp:dbus-ref>'s
TargetURIScheme fixed-property instead.</p>
<p>Connection managers with a <code>.manager</code> file
......
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