summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorSimon McVittie <simon.mcvittie@collabora.co.uk>2013-11-04 14:13:48 +0000
committerGuillaume Desmottes <guillaume.desmottes@collabora.co.uk>2014-01-15 11:15:18 +0100
commit28c6e0d0454efc54f9a24da631eb75e6fcf925ba (patch)
tree4fb110d6ae6e1d6d3896bcbc927ec560550bff13
parentde3eb33479a0f7f2148740f1a05cbd1c65e08bc6 (diff)
Flatten Requests interface into Connection
We keep meaning to do this one day. That day has arrived.
-rw-r--r--doc/templates/interface.html20
-rw-r--r--spec/Channel.xml4
-rw-r--r--spec/Channel_Dispatch_Operation.xml2
-rw-r--r--spec/Channel_Dispatcher.xml6
-rw-r--r--spec/Channel_Dispatcher_Interface_Messages1.xml2
-rw-r--r--spec/Channel_Interface_Addressing1.xml2
-rw-r--r--spec/Channel_Interface_Conference1.xml14
-rw-r--r--spec/Channel_Interface_SMS1.xml2
-rw-r--r--spec/Channel_Interface_Tube1.xml6
-rw-r--r--spec/Channel_Request.xml6
-rw-r--r--spec/Channel_Type_Call1.xml8
-rw-r--r--spec/Channel_Type_Contact_Search1.xml12
-rw-r--r--spec/Channel_Type_DBus_Tube1.xml4
-rw-r--r--spec/Channel_Type_File_Transfer1.xml18
-rw-r--r--spec/Channel_Type_Room_List1.xml2
-rw-r--r--spec/Channel_Type_Server_Authentication1.xml2
-rw-r--r--spec/Channel_Type_Server_TLS_Connection1.xml2
-rw-r--r--spec/Channel_Type_Stream_Tube1.xml4
-rw-r--r--spec/Channel_Type_Text.xml2
-rw-r--r--spec/Client_Observer.xml4
-rw-r--r--spec/Connection.xml543
-rw-r--r--spec/Connection_Interface_Contact_Capabilities1.xml2
-rw-r--r--spec/Connection_Interface_Requests.xml590
-rw-r--r--spec/Protocol.xml6
-rw-r--r--spec/Protocol_Interface_Addressing1.xml2
-rw-r--r--spec/all.xml2
26 files changed, 601 insertions, 666 deletions
diff --git a/doc/templates/interface.html b/doc/templates/interface.html
index ed67a926..981f67ef 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 <a href="Connection_Interface_Requests.html#im.telepathy.v1.Connection.Interface.Requests.NewChannels">NewChannels</a>
+ of <a href="Connection.html#im.telepathy.v1.Connection.NewChannels">NewChannels</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_Interface_Requests.html#im.telepathy.v1.Connection.Interface.Requests.NewChannels">NewChannels</a>
+ of <a href="Connection.html#im.telepathy.v1.Connection.NewChannels">NewChannels</a>
signals.
#else
change.
@@ -372,29 +372,29 @@
<div class="annotation requestable">Depending on the protocol, this
property may be <strong>requestable</strong>, which means that it may be
allowed in the properties hash of a channel request such as in the
- <a href="Connection_Interface_Requests.html#im.telepathy.v1.Connection.Interface.Requests.CreateChannel">CreateChannel</a>
+ <a href="Connection.html#im.telepathy.v1.Connection.CreateChannel">CreateChannel</a>
and
- <a href="Connection_Interface_Requests.html#im.telepathy.v1.Connection.Interface.Requests.EnsureChannel">EnsureChannel</a>
+ <a href="Connection.html#im.telepathy.v1.Connection.EnsureChannel">EnsureChannel</a>
methods
- on <a href="Connection_Interface_Requests.html">Requests</a>
+ on <a href="Connection.html">Connection</a>
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
is <strong>requestable</strong>, which means that it is allowed
in the properties hash of a channel request such as in the
- <a href="Connection_Interface_Requests.html#im.telepathy.v1.Connection.Interface.Requests.CreateChannel">CreateChannel</a>
+ <a href="Connection.html#im.telepathy.v1.Connection.CreateChannel">CreateChannel</a>
and
- <a href="Connection_Interface_Requests.html#im.telepathy.v1.Connection.Interface.Requests.EnsureChannel">EnsureChannel</a>
+ <a href="Connection.html#im.telepathy.v1.Connection.EnsureChannel">EnsureChannel</a>
methods
- on <a href="Connection_Interface_Requests.html">Requests</a>
+ on <a href="Connection.html">Connection</a>
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
diff --git a/spec/Channel.xml b/spec/Channel.xml
index 88a2aebb..8c2d9f1b 100644
--- a/spec/Channel.xml
+++ b/spec/Channel.xml
@@ -189,7 +189,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
<p>True if this channel was created in response to a local request,
such as a call to
- <tp:dbus-ref namespace="im.telepathy.v1">Connection.Interface.Requests.CreateChannel</tp:dbus-ref>.</p>
+ <tp:dbus-ref namespace="im.telepathy.v1">Connection.CreateChannel</tp:dbus-ref>.</p>
<tp:rationale>
<p>The idea of this property is to distinguish between "incoming"
@@ -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.Interface.Requests'>NewChannels</tp:dbus-ref>),
+ namespace='imt1.Connection'>NewChannels</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
diff --git a/spec/Channel_Dispatch_Operation.xml b/spec/Channel_Dispatch_Operation.xml
index c1f0476e..022eab0d 100644
--- a/spec/Channel_Dispatch_Operation.xml
+++ b/spec/Channel_Dispatch_Operation.xml
@@ -36,7 +36,7 @@
from outgoing requests for channels.</p>
<p>More specifically, whenever the <tp:dbus-ref
- namespace="im.telepathy.v1">Connection.Interface.Requests.NewChannels</tp:dbus-ref>
+ namespace="im.telepathy.v1">Connection.NewChannels</tp:dbus-ref>
signal contains channels whose <tp:dbus-ref
namespace="im.telepathy.v1.Channel">Requested</tp:dbus-ref>
property is false, one or more ChannelDispatchOperation
diff --git a/spec/Channel_Dispatcher.xml b/spec/Channel_Dispatcher.xml
index 1bf50e09..3d7d52b1 100644
--- a/spec/Channel_Dispatcher.xml
+++ b/spec/Channel_Dispatcher.xml
@@ -153,7 +153,7 @@
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
<p>A dictionary containing desirable properties. This has the same
semantics as the corresponding parameter to
- <tp:dbus-ref namespace="im.telepathy.v1">Connection.Interface.Requests.CreateChannel</tp:dbus-ref>.
+ <tp:dbus-ref namespace="im.telepathy.v1">Connection.CreateChannel</tp:dbus-ref>.
</p>
<p>Certain properties will not necessarily make sense in this
@@ -318,7 +318,7 @@
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
<p>A dictionary containing desirable properties. This has the same
semantics as the corresponding parameter to
- <tp:dbus-ref namespace="im.telepathy.v1">Connection.Interface.Requests.EnsureChannel</tp:dbus-ref>.
+ <tp:dbus-ref namespace="im.telepathy.v1">Connection.EnsureChannel</tp:dbus-ref>.
</p>
<p>Certain properties will not necessarily make sense in this
@@ -361,7 +361,7 @@
so it can try to dispatch subsequent channels in the same bundle
to the same handler. If the requested channel already exists (that
is, <tp:dbus-ref
- namespace="im.telepathy.v1">Connection.Interface.Requests.EnsureChannel</tp:dbus-ref>
+ namespace="im.telepathy.v1">Connection.EnsureChannel</tp:dbus-ref>
returns <code>Yours=False</code>) then the channel dispatcher
SHOULD re-dispatch the channel to its existing handler, and MUST
NOT dispatch it to this client (unless it is the existing handler);
diff --git a/spec/Channel_Dispatcher_Interface_Messages1.xml b/spec/Channel_Dispatcher_Interface_Messages1.xml
index 9b92acba..95fd08ae 100644
--- a/spec/Channel_Dispatcher_Interface_Messages1.xml
+++ b/spec/Channel_Dispatcher_Interface_Messages1.xml
@@ -126,7 +126,7 @@
<p>This method may raise any error that would be raised by the
<tp:dbus-ref
- namespace="imt1.Connection.Interface">Requests.EnsureChannel</tp:dbus-ref>
+ namespace="imt1.Connection">EnsureChannel</tp:dbus-ref>
or <tp:dbus-ref
namespace="imt1.Channel.Type">Text.SendMessage</tp:dbus-ref>
methods, or signalled by the <tp:dbus-ref
diff --git a/spec/Channel_Interface_Addressing1.xml b/spec/Channel_Interface_Addressing1.xml
index 7b4ff432..a61c0ead 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.</
<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="im.telepathy.v1.Connection">RequestableChannelClasses</tp:dbus-ref>
that support a limited set of URI schemes.</p>
</tp:rationale>
diff --git a/spec/Channel_Interface_Conference1.xml b/spec/Channel_Interface_Conference1.xml
index ae2ee3b3..baf36779 100644
--- a/spec/Channel_Interface_Conference1.xml
+++ b/spec/Channel_Interface_Conference1.xml
@@ -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="im.telepathy.v1.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
@@ -114,7 +114,7 @@
into a single conference call by calling:</p>
<blockquote>
- <code><tp:dbus-ref namespace="im.telepathy.v1.Connection.Interface.Requests">CreateChannel</tp:dbus-ref>({
+ <code><tp:dbus-ref namespace="im.telepathy.v1.Connection">CreateChannel</tp:dbus-ref>({
...<tp:dbus-ref namespace="im.telepathy.v1.Channel">ChannelType</tp:dbus-ref>: ...Call,
...<tp:member-ref>InitialChannels</tp:member-ref>: [C1, C2]
})</code>
@@ -153,7 +153,7 @@
the room), call:</p>
<blockquote>
- <code><tp:dbus-ref namespace="im.telepathy.v1.Connection.Interface.Requests">EnsureChannel</tp:dbus-ref>({
+ <code><tp:dbus-ref namespace="im.telepathy.v1.Connection">EnsureChannel</tp:dbus-ref>({
...ChannelType: ...Text,
...<tp:dbus-ref namespace="im.telepathy.v1.Channel">TargetHandleType</tp:dbus-ref>: ...Room,
...<tp:dbus-ref namespace="im.telepathy.v1.Channel">TargetID</tp:dbus-ref>: 'telepathy@conf.example.com',
@@ -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="im.telepathy.v1.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="im.telepathy.v1.Connection"
>RequestableChannelClasses</tp:dbus-ref>, in protocols where
invitations can have an accompanying text message.</p>
diff --git a/spec/Channel_Interface_SMS1.xml b/spec/Channel_Interface_SMS1.xml
index 226505da..a4f1d74a 100644
--- a/spec/Channel_Interface_SMS1.xml
+++ b/spec/Channel_Interface_SMS1.xml
@@ -102,7 +102,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.Interface.Requests"
+ namespace="imt1.Connection"
>NewChannels</tp:dbus-ref> signals.</p>
<tp:rationale>
diff --git a/spec/Channel_Interface_Tube1.xml b/spec/Channel_Interface_Tube1.xml
index d97b0ae4..d4eeb6ab 100644
--- a/spec/Channel_Interface_Tube1.xml
+++ b/spec/Channel_Interface_Tube1.xml
@@ -70,7 +70,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
<p>When requesting a tube with
<tp:dbus-ref
- namespace="im.telepathy.v1.Connection.Interface.Requests">CreateChannel</tp:dbus-ref>,
+ namespace="im.telepathy.v1.Connection">CreateChannel</tp:dbus-ref>,
this property MUST NOT be included in the request; instead, it is set
when <tp:dbus-ref
namespace="im.telepathy.v1.Channel.Type">StreamTube1.Offer</tp:dbus-ref>
@@ -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.Interface.Requests">NewChannels</tp:dbus-ref>
+ namespace="im.telepathy.v1.Connection">NewChannels</tp:dbus-ref>
signal.</p>
</tp:docstring>
</property>
@@ -93,7 +93,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
<p>When requesting a tube with
<tp:dbus-ref
- namespace="im.telepathy.v1.Connection.Interface.Requests">CreateChannel</tp:dbus-ref>,
+ namespace="im.telepathy.v1.Connection">CreateChannel</tp:dbus-ref>,
this property MUST NOT be included in the request.</p>
</tp:docstring>
</property>
diff --git a/spec/Channel_Request.xml b/spec/Channel_Request.xml
index 188a34ba..2b68f882 100644
--- a/spec/Channel_Request.xml
+++ b/spec/Channel_Request.xml
@@ -154,7 +154,7 @@
<p>If the connection manager has already been asked to create a
channel but has not produced one yet (e.g. if <tp:dbus-ref
- namespace="im.telepathy.v1">Connection.Interface.Requests.CreateChannel</tp:dbus-ref>
+ namespace="im.telepathy.v1">Connection.CreateChannel</tp:dbus-ref>
has been called, but has not yet returned), then the
ChannelDispatcher will remember that the request has been cancelled.
When the channel appears, it will be closed (if it was newly
@@ -191,7 +191,7 @@
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
<p>The name of a D-Bus error. This can come from various sources,
including the error raised by <tp:dbus-ref
- namespace="im.telepathy.v1.Connection.Interface.Requests">CreateChannel</tp:dbus-ref>,
+ namespace="im.telepathy.v1.Connection">CreateChannel</tp:dbus-ref>,
or an error generated
to represent failure to establish the <tp:dbus-ref
namespace="im.telepathy.v1">Connection</tp:dbus-ref>.</p>
@@ -322,7 +322,7 @@
tp:type="Qualified_Property_Value_Map">
<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.Interface.Requests"
+ in a <tp:dbus-ref namespace="imt1.Connection"
>NewChannels</tp:dbus-ref> signal.</p>
</tp:docstring>
</arg>
diff --git a/spec/Channel_Type_Call1.xml b/spec/Channel_Type_Call1.xml
index 11cc2458..f6226b7c 100644
--- a/spec/Channel_Type_Call1.xml
+++ b/spec/Channel_Type_Call1.xml
@@ -75,7 +75,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
<blockquote>
<pre>
-<tp:dbus-ref namespace="imt1.Connection.Interface.Requests">CreateChannel</tp:dbus-ref>({
+<tp:dbus-ref namespace="imt1.Connection">CreateChannel</tp:dbus-ref>({
...<tp:dbus-ref namespace="imt1.Channel">ChannelType</tp:dbus-ref>: ...<tp:dbus-ref
namespace="imt1.Channel.Type">Call1</tp:dbus-ref>,
...<tp:dbus-ref namespace="imt1.Channel">TargetHandleType</tp:dbus-ref>: Contact,
@@ -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.Interface.Requests">NewChannels</tp:dbus-ref>
+ namespace="imt1.Connection">NewChannels</tp:dbus-ref>
signal will occur:</p>
<blockquote>
<pre>
-<tp:dbus-ref namespace="imt1.Connection.Interface.Requests">NewChannels</tp:dbus-ref>([
+<tp:dbus-ref namespace="imt1.Connection">NewChannels</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
@@ -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>
diff --git a/spec/Channel_Type_Contact_Search1.xml b/spec/Channel_Type_Contact_Search1.xml
index cfc3a62f..9fdab7fb 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.</
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
@@ -81,7 +81,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
<tp:member-ref>Limit</tp:member-ref> results. If allowed by the
connection manager, clients may specify the "page size" by specifying
<tp:member-ref>Limit</tp:member-ref> when calling
- <tp:dbus-ref namespace="im.telepathy.v1.Connection.Interface.Requests">CreateChannel</tp:dbus-ref>.
+ <tp:dbus-ref namespace="im.telepathy.v1.Connection">CreateChannel</tp:dbus-ref>.
</p>
<p>The client should call the channel's <tp:dbus-ref
@@ -94,10 +94,10 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
to the same server, if applicable).</p>
<p>It does not make sense to request this channel type using <tp:dbus-ref
- namespace="im.telepathy.v1.Connection.Interface.Requests">EnsureChannel</tp:dbus-ref>;
+ namespace="im.telepathy.v1.Connection">EnsureChannel</tp:dbus-ref>;
clients SHOULD request channels of this type using
<tp:dbus-ref
- namespace="im.telepathy.v1.Connection.Interface.Requests">CreateChannel</tp:dbus-ref>
+ namespace="im.telepathy.v1.Connection">CreateChannel</tp:dbus-ref>
instead.</p>
<tp:rationale>
@@ -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.Interface.Requests">NewChannels</tp:dbus-ref>
+ namespace="im.telepathy.v1.Connection">NewChannels</tp:dbus-ref>
signal for round-trip reduction.
</tp:rationale>
</tp:docstring>
diff --git a/spec/Channel_Type_DBus_Tube1.xml b/spec/Channel_Type_DBus_Tube1.xml
index 6f7f6f19..4917643e 100644
--- a/spec/Channel_Type_DBus_Tube1.xml
+++ b/spec/Channel_Type_DBus_Tube1.xml
@@ -138,7 +138,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
other end.</p>
<p>When requesting a channel with
<tp:dbus-ref
- namespace="im.telepathy.v1.Connection.Interface.Requests">CreateChannel</tp:dbus-ref>,
+ namespace="im.telepathy.v1.Connection">CreateChannel</tp:dbus-ref>,
this property MUST be included in the request.</p>
</tp:docstring>
</property>
@@ -190,7 +190,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
</tp:rationale>
<p>When requesting a channel with
- <tp:dbus-ref namespace="im.telepathy.v1">Connection.Interface.Requests.CreateChannel</tp:dbus-ref>,
+ <tp:dbus-ref namespace="im.telepathy.v1">Connection.CreateChannel</tp:dbus-ref>,
this property MUST NOT be included in the request.</p>
</tp:docstring>
diff --git a/spec/Channel_Type_File_Transfer1.xml b/spec/Channel_Type_File_Transfer1.xml
index 67ccf11e..04258f90 100644
--- a/spec/Channel_Type_File_Transfer1.xml
+++ b/spec/Channel_Type_File_Transfer1.xml
@@ -102,7 +102,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
been created.</p>
<p>This property is mandatory when requesting the channel with the
- <tp:dbus-ref namespace="im.telepathy.v1">Connection.Interface.Requests.CreateChannel</tp:dbus-ref>
+ <tp:dbus-ref namespace="im.telepathy.v1">Connection.CreateChannel</tp:dbus-ref>
method. Protocols which do not have a content-type property with file
transfers should set this value to application/octet-stream.</p>
</tp:docstring>
@@ -120,7 +120,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
be set to monkey.pdf.</p>
<p>This property is mandatory when requesting the channel with the
- <tp:dbus-ref namespace="im.telepathy.v1">Connection.Interface.Requests.CreateChannel</tp:dbus-ref>
+ <tp:dbus-ref namespace="im.telepathy.v1">Connection.CreateChannel</tp:dbus-ref>
method. This property cannot be empty and MUST be set to a sensible value.</p>
</tp:docstring>
</property>
@@ -138,7 +138,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
to the byte.</p>
<p>This property is mandatory when requesting the channel with the
- <tp:dbus-ref namespace="im.telepathy.v1">Connection.Interface.Requests.CreateChannel</tp:dbus-ref>
+ <tp:dbus-ref namespace="im.telepathy.v1">Connection.CreateChannel</tp:dbus-ref>
method. If this information isn't provided in the protocol, connection managers MUST set it
to UINT64_MAX.</p>
</tp:docstring>
@@ -151,15 +151,15 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
<p>The type of the <tp:member-ref>ContentHash</tp:member-ref> property.</p>
<p>This property is optional when requesting the channel with the
- <tp:dbus-ref namespace="im.telepathy.v1">Connection.Interface.Requests.CreateChannel</tp:dbus-ref>
+ <tp:dbus-ref namespace="im.telepathy.v1">Connection.CreateChannel</tp:dbus-ref>
method. However, if you wish to include the <tp:member-ref>ContentHash</tp:member-ref>
property you MUST also include this property. If you omit this property from a
- <tp:dbus-ref namespace="im.telepathy.v1">Connection.Interface.Requests.CreateChannel</tp:dbus-ref>
+ <tp:dbus-ref namespace="im.telepathy.v1">Connection.CreateChannel</tp:dbus-ref>
method call then its value will be assumed to be File_Hash_Type_None.</p>
<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="im.telepathy.v1.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
@@ -177,7 +177,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
property.</p>
<p>This property is optional when requesting the channel with the
- <tp:dbus-ref namespace="im.telepathy.v1">Connection.Interface.Requests.CreateChannel</tp:dbus-ref>
+ <tp:dbus-ref namespace="im.telepathy.v1">Connection.CreateChannel</tp:dbus-ref>
method. Its value MUST correspond to the appropriate type of the
<tp:member-ref>ContentHashType</tp:member-ref> property. If the
ContentHashType property is not set, or set to File_Hash_Type_None,
@@ -192,7 +192,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
channel has been created.</p>
<p>This property is optional when requesting the channel with the
- <tp:dbus-ref namespace="im.telepathy.v1">Connection.Interface.Requests.CreateChannel</tp:dbus-ref>
+ <tp:dbus-ref namespace="im.telepathy.v1">Connection.CreateChannel</tp:dbus-ref>
method. If this property was not provided by the remote party, connection managers MUST set it to
the empty string.</p>
</tp:docstring>
@@ -206,7 +206,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
cannot change once the channel has been created</p>
<p>This property is optional when requesting the channel with the
- <tp:dbus-ref namespace="im.telepathy.v1">Connection.Interface.Requests.CreateChannel</tp:dbus-ref>
+ <tp:dbus-ref namespace="im.telepathy.v1">Connection.CreateChannel</tp:dbus-ref>
method.</p>
</tp:docstring>
</property>
diff --git a/spec/Channel_Type_Room_List1.xml b/spec/Channel_Type_Room_List1.xml
index 91d86ac4..5ae45ab8 100644
--- a/spec/Channel_Type_Room_List1.xml
+++ b/spec/Channel_Type_Room_List1.xml
@@ -66,7 +66,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
<p>Emitted when information about rooms on the server becomes
available. The array contains the room handle (as can be
passed to the <tp:dbus-ref
- namespace="imt1.Connection.Interface.Requests">CreateChannel</tp:dbus-ref>
+ namespace="imt1.Connection">CreateChannel</tp:dbus-ref>
method with <tp:dbus-ref
namespace="imt1.Channel">TargetHandleType</tp:dbus-ref>=
HANDLE_TYPE_ROOM), the channel type, and a dictionary
diff --git a/spec/Channel_Type_Server_Authentication1.xml b/spec/Channel_Type_Server_Authentication1.xml
index dcd1e34b..d3ebfc68 100644
--- a/spec/Channel_Type_Server_Authentication1.xml
+++ b/spec/Channel_Type_Server_Authentication1.xml
@@ -46,7 +46,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
<p>Channels of this type cannot be requested with methods such as
<tp:dbus-ref
- namespace="imt1.Connection.Interface.Requests">CreateChannel</tp:dbus-ref>.
+ namespace="imt1.Connection">CreateChannel</tp:dbus-ref>.
They always have <tp:dbus-ref
namespace="imt1.Channel">Requested</tp:dbus-ref> = False,
<tp:dbus-ref
diff --git a/spec/Channel_Type_Server_TLS_Connection1.xml b/spec/Channel_Type_Server_TLS_Connection1.xml
index a0a5b412..c2bfcf65 100644
--- a/spec/Channel_Type_Server_TLS_Connection1.xml
+++ b/spec/Channel_Type_Server_TLS_Connection1.xml
@@ -31,7 +31,7 @@
<tp:dbus-ref namespace="im.telepathy.v1.Channel">TargetHandleType</tp:dbus-ref>
= None and <tp:dbus-ref namespace="im.telepathy.v1.Channel">TargetHandle</tp:dbus-ref>
= 0, and cannot be requested with methods such as <tp:dbus-ref
- namespace="im.telepathy.v1.Connection.Interface.Requests">CreateChannel</tp:dbus-ref>.
+ namespace="im.telepathy.v1.Connection">CreateChannel</tp:dbus-ref>.
Also, they SHOULD be dispatched while the
<tp:dbus-ref namespace="im.telepathy.v1">Connection</tp:dbus-ref>
owning them is in the CONNECTING state.</p>
diff --git a/spec/Channel_Type_Stream_Tube1.xml b/spec/Channel_Type_Stream_Tube1.xml
index 1081de2b..7b192cc6 100644
--- a/spec/Channel_Type_Stream_Tube1.xml
+++ b/spec/Channel_Type_Stream_Tube1.xml
@@ -246,7 +246,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
<p>When the tube is offered, the service name is transmitted to the
other end.</p>
<p>When requesting a channel with
- <tp:dbus-ref namespace="im.telepathy.v1">Connection.Interface.Requests.CreateChannel</tp:dbus-ref>,
+ <tp:dbus-ref namespace="im.telepathy.v1">Connection.CreateChannel</tp:dbus-ref>,
this property MUST be included in the request.</p>
</tp:docstring>
</property>
@@ -286,7 +286,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
access control.</p>
<p>When requesting a channel with
- <tp:dbus-ref namespace="im.telepathy.v1">Connection.Interface.Requests.CreateChannel</tp:dbus-ref>,
+ <tp:dbus-ref namespace="im.telepathy.v1">Connection.CreateChannel</tp:dbus-ref>,
this property MUST NOT be included in the request.</p>
</tp:docstring>
diff --git a/spec/Channel_Type_Text.xml b/spec/Channel_Type_Text.xml
index cebc2ecf..5c1707a3 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.</
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.Interface.Requests">NewChannels</tp:dbus-ref>
+ namespace="imt1.Connection">NewChannels</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
diff --git a/spec/Client_Observer.xml b/spec/Client_Observer.xml
index 85961ee9..1a80d4fb 100644
--- a/spec/Client_Observer.xml
+++ b/spec/Client_Observer.xml
@@ -122,7 +122,7 @@
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.Interface.Requests">NewChannels</tp:dbus-ref>
+ namespace="im.telepathy.v1.Connection">NewChannels</tp:dbus-ref>
signal match this description.</p>
<p>Only certain D-Bus types have useful semantics for matching like this,
@@ -255,7 +255,7 @@ Recover=true
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
<p>Called by the channel dispatcher when channels in which the
observer has registered an interest are announced in a <tp:dbus-ref
- namespace="im.telepathy.v1.Connection.Interface.Requests">NewChannels</tp:dbus-ref>
+ namespace="im.telepathy.v1.Connection">NewChannels</tp:dbus-ref>
signal.</p>
<p>If the same NewChannels signal announces some channels that match
diff --git a/spec/Connection.xml b/spec/Connection.xml
index 86b9a053..154c8bb7 100644
--- a/spec/Connection.xml
+++ b/spec/Connection.xml
@@ -22,8 +22,6 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301,
USA.</p>
</tp:license>
<interface name="im.telepathy.v1.Connection">
- <tp:requires interface="im.telepathy.v1.Connection.Interface.Requests"/>
-
<method name="Connect" tp:name-for-bindings="Connect">
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
<p>Request that the connection be established. This will be done
@@ -68,10 +66,6 @@ USA.</p>
interfaces for the remainder of the Connection's lifetime.</p>
</tp:rationale>
- <p>As a special case, the mandatory <tp:dbus-ref
- namespace="imt1.Connection.Interface">Requests</tp:dbus-ref>
- interface SHOULD NOT be listed in this property.</p>
-
<tp:rationale>
<p>It has been mandatory since Telepathy 0.18 in 2009,
and contains essential functionality for this interface,
@@ -846,6 +840,540 @@ USA.</p>
</tp:possible-errors>
</method>
+ <tp:struct name="Channel_Details" array-name="Channel_Details_List">
+ <tp:added version="0.17.11">(as stable API)</tp:added>
+
+ <tp:docstring>
+ Enough details of a channel that clients can work out how to dispatch
+ or handle it.
+ </tp:docstring>
+
+ <tp:member name="Channel" type="o">
+ <tp:docstring>
+ The object path of the channel.
+ </tp:docstring>
+ </tp:member>
+
+ <tp:member name="Properties" type="a{sv}"
+ tp:type="Qualified_Property_Value_Map">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Properties of the channel.</p>
+
+ <p>Connection managers MUST NOT include properties in this mapping
+ if their values can change. Clients MUST ignore properties
+ that appear in this mapping if their values can change.</p>
+
+ <tp:rationale>
+ <p>If properties that could change were included, the following
+ race condition would be likely to exist in some cases:</p>
+
+ <ul>
+ <li>NewChannels 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>
+ <li>Client connects to PChanged signal</li>
+ <li>Client should call Get("P") or GetAll here, to avoid the
+ race, but client's author has forgotten to do so</li>
+ <li>Proxy object thinks P == V1, but actually P == V2</li>
+ </ul>
+
+ <p>We've taken the opportunity to make the API encourage the
+ client author to get it right. Where possible, we intend that
+ properties whose value will be used in channel dispatching
+ or other "early" processing will be defined so that they are
+ immutable (can never change).</p>
+ </tp:rationale>
+
+ <p>Each dictionary MUST contain the keys
+ <tp:dbus-ref>im.telepathy.v1.Channel.ChannelType</tp:dbus-ref>,
+ <tp:dbus-ref>im.telepathy.v1.Channel.TargetHandleType</tp:dbus-ref>,
+ <tp:dbus-ref>im.telepathy.v1.Channel.TargetHandle</tp:dbus-ref>,
+ <tp:dbus-ref>im.telepathy.v1.Channel.TargetID</tp:dbus-ref>
+ and
+ <tp:dbus-ref>im.telepathy.v1.Channel.Requested</tp:dbus-ref>.
+ </p>
+
+ <tp:rationale>
+ <p>We expect these to be crucial to the channel-dispatching
+ process.</p>
+ </tp:rationale>
+ </tp:docstring>
+ </tp:member>
+ </tp:struct>
+
+ <method name="CreateChannel" tp:name-for-bindings="Create_Channel">
+ <tp:added version="0.99.UNRELEASED">(as part of Connection)</tp:added>
+
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Request that an entirely new channel is created.</p>
+ </tp:docstring>
+
+ <arg direction="in" name="Request" type="a{sv}"
+ tp:type="Qualified_Property_Value_Map">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>A dictionary containing desirable properties, which MUST include
+ <tp:dbus-ref
+ namespace="im.telepathy.v1.Channel">ChannelType</tp:dbus-ref>.
+ Some properties
+ are defined such that only an exact match makes sense, and
+ connection managers MUST NOT satisfy a request with a channel
+ where that property does not match; some properties are defined
+ such that the connection manager MAY treat the request as merely
+ a hint, and make a best-effort attempt to satisfy it. This is
+ documented separately for each property.</p>
+
+ <p>If this dictionary contains a property whose semantics
+ are not known to the connection manager, this method MUST fail
+ without side-effects (in particular it must not create a new
+ channel).</p>
+
+ <tp:rationale>
+ <p>This is necessary if we want to be able to invent properties
+ in future that, when used in a request, are hard requirements
+ rather than just hints. A connection manager that did not know
+ the semantics of those properties could incorrectly return a
+ new channel that did not satisfy the requirements.</p>
+ </tp:rationale>
+
+ <p>The connection manager MUST NOT respond successfully,
+ and SHOULD NOT create a new channel or cause any other
+ side-effects, unless it can create a new channel that satisfies
+ the client's requirements.</p>
+
+ <p>Properties that will be set by this argument need not have write
+ access after the channel has been created - indeed, it is
+ expected that most will be read-only.</p>
+ </tp:docstring>
+ </arg>
+
+ <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
+ returns.</p>
+
+ <tp:rationale>
+ <p>This allows the requester to alter its handling of
+ NewChannels by knowing whether one of the channels satisfied
+ a request it made.</p>
+ </tp:rationale>
+ </tp:docstring>
+ </arg>
+
+ <arg name="Properties" direction="out" type="a{sv}"
+ tp:type="Qualified_Property_Value_Map">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Properties of the channel that was produced, equivalent to
+ the properties in <tp:type>Channel_Details</tp:type>.
+ Connection managers MUST NOT include properties here whose
+ values can change, for the same reasons as in
+ <tp:type>Channel_Details</tp:type>.</p>
+ </tp:docstring>
+ </arg>
+
+ <tp:possible-errors>
+ <tp:error name="im.telepathy.v1.Error.Disconnected"/>
+ <tp:error name="im.telepathy.v1.Error.NetworkError"/>
+ <tp:error name="im.telepathy.v1.Error.NotImplemented">
+ <tp:docstring>
+ The channel request was one that can never succeed,
+ such as requesting an unsupported channel type, or requesting
+ a channel type which this connection manager does not support with
+ the given target handle type.
+ </tp:docstring>
+ </tp:error>
+ <tp:error name="im.telepathy.v1.Error.InvalidHandle">
+ <tp:docstring>
+ An invalid handle was requested as the value of a property whose
+ value is a handle (like
+ <tp:dbus-ref namespace="im.telepathy.v1">Channel.TargetHandle</tp:dbus-ref>),
+ or a syntactically invalid identifier was requested as the value
+ of a property whose value is the string corresponding to a handle
+ (like <tp:dbus-ref
+ namespace="im.telepathy.v1">Channel.TargetID</tp:dbus-ref>).
+ </tp:docstring>
+ </tp:error>
+ <tp:error name="im.telepathy.v1.Error.InvalidArgument">
+ <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
+ 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
+ namespace="im.telepathy.v1.Channel.Type.RoomList1">Server</tp:dbus-ref>
+ property provided was not a valid DNS name.
+ </tp:docstring>
+ </tp:error>
+ <tp:error name="im.telepathy.v1.Error.NotCapable">
+ <tp:docstring>
+ The requested channel cannot be created because the requested
+ contact is using a client that lacks a particular feature.
+ </tp:docstring>
+ </tp:error>
+ <tp:error name="im.telepathy.v1.Error.Offline">
+ <tp:docstring>
+ The requested channel cannot be created because the target is
+ offline.
+ </tp:docstring>
+ </tp:error>
+ <tp:error name="im.telepathy.v1.Error.NotAvailable">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The requested channel cannot be created, but in
+ principle, a similar request might succeed in future.
+ For instance, this might be because:</p>
+
+ <ul>
+ <li>a channel matching the request already exists and the
+ protocol requires that only one such channel can exist at a
+ time</li>
+ <li>a channel matching the request has already been requested
+ (by a previous call to CreateChannel,
+ <tp:member-ref>EnsureChannel</tp:member-ref>,
+ or similar) and the protocol requires that only one such
+ channel can exist at a time</li>
+ </ul>
+ </tp:docstring>
+ </tp:error>
+ <tp:error name="im.telepathy.v1.Error.Channel.Banned"/>
+ <tp:error name="im.telepathy.v1.Error.Channel.Full"/>
+ <tp:error name="im.telepathy.v1.Error.Channel.InviteOnly"/>
+ <tp:error name="im.telepathy.v1.Error.PermissionDenied"/>
+ </tp:possible-errors>
+ </method>
+
+ <method name="EnsureChannel" tp:name-for-bindings="Ensure_Channel">
+ <tp:added version="0.99.UNRELEASED">(as part of Connection)</tp:added>
+
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Request that channels are ensured to exist.</p>
+
+ <tp:rationale>
+ <p>The connection manager is in the best position to determine which
+ existing channels could satisfy which requests.</p>
+ </tp:rationale>
+
+ </tp:docstring>
+
+ <arg direction="in" name="Request" type="a{sv}"
+ tp:type="Qualified_Property_Value_Map">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>A dictionary containing desirable properties, with the same
+ semantics as the corresponding parameter to
+ <tp:member-ref>CreateChannel</tp:member-ref>.</p>
+ </tp:docstring>
+ </arg>
+
+ <arg name="Yours" direction="out" type="b">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>If false, the caller of EnsureChannel MUST assume that some
+ other process is handling this channel; if true, the caller of
+ EnsureChannel SHOULD handle it themselves or delegate it to another
+ client.</p>
+
+ <p>If the creation of a channel makes several calls to EnsureChannel
+ (and no other requests) successful, exactly one of those calls MUST
+ return a true value for this argument.</p>
+
+ <p>If the creation of a channel makes other requests successful,
+ the value returned for this argument MUST be such that exactly
+ one of the clients making requests ends up responsible for the
+ channel. In particular, if
+ <tp:member-ref>CreateChannel</tp:member-ref> returns a channel
+ <em>C</em>, any EnsureChannel calls that also return <em>C</em>
+ MUST return a false value for this argument.</p>
+ </tp:docstring>
+ </arg>
+
+ <arg name="Channel" direction="out" type="o">
+ <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
+ returns.
+
+ <tp:rationale>
+ <p>This allows the requester to alter its handling of
+ NewChannels by knowing whether one of the channels satisfied
+ a request it made.</p>
+ </tp:rationale>
+ </tp:docstring>
+ </arg>
+
+ <arg name="Properties" direction="out" type="a{sv}"
+ tp:type="Qualified_Property_Value_Map">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Properties of the channel that was produced, equivalent to
+ the properties in <tp:type>Channel_Details</tp:type>.
+ Connection managers MUST NOT include properties here whose
+ values can change, for the same reasons as in
+ <tp:type>Channel_Details</tp:type>.</p>
+ </tp:docstring>
+ </arg>
+
+ <tp:possible-errors>
+ <tp:error name="im.telepathy.v1.Error.Disconnected"/>
+ <tp:error name="im.telepathy.v1.Error.NetworkError"/>
+ <tp:error name="im.telepathy.v1.Error.NotImplemented">
+ <tp:docstring>
+ The channel request was one that can never succeed,
+ such as requesting an unsupported channel type, or requesting
+ a channel type which this connection manager does not support with
+ the given target handle type.
+ </tp:docstring>
+ </tp:error>
+ <tp:error name="im.telepathy.v1.Error.InvalidHandle">
+ <tp:docstring>
+ An invalid handle was requested as the value of a property whose
+ value is a handle (like
+ <tp:dbus-ref namespace="im.telepathy.v1">Channel.TargetHandle</tp:dbus-ref>),
+ or a syntactically invalid identifier was requested as the value
+ of a property whose value is the string corresponding to a handle
+ (like <tp:dbus-ref
+ namespace="im.telepathy.v1">Channel.TargetID</tp:dbus-ref>).
+ </tp:docstring>
+ </tp:error>
+ <tp:error name="im.telepathy.v1.Error.InvalidArgument">
+ <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
+ 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
+ namespace="im.telepathy.v1.Channel.Type.RoomList1">Server</tp:dbus-ref>
+ property provided was not a valid DNS name.
+ </tp:docstring>
+ </tp:error>
+ <tp:error name="im.telepathy.v1.Error.NotCapable">
+ <tp:docstring>
+ The requested channel cannot be created because the requested
+ contact is using a client that lacks a particular feature.
+ </tp:docstring>
+ </tp:error>
+ <tp:error name="im.telepathy.v1.Error.Offline">
+ <tp:docstring>
+ The requested channel cannot be created because the target is
+ offline.
+ </tp:docstring>
+ </tp:error>
+ <tp:error name="im.telepathy.v1.Error.NotAvailable">
+ <tp:docstring>
+ The requested channel cannot be created, but in
+ principle, a similar request might succeed in future.
+ </tp:docstring>
+ </tp:error>
+ <tp:error name="im.telepathy.v1.Error.Channel.Banned"/>
+ <tp:error name="im.telepathy.v1.Error.Channel.Full"/>
+ <tp:error name="im.telepathy.v1.Error.Channel.InviteOnly"/>
+ <tp:error name="im.telepathy.v1.Error.PermissionDenied"/>
+ </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>
+
+ <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>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
+ separately, or not expose the Text channel on the bus
+ until it's actually requested (or an incoming message
+ appears).</p>
+
+ <tp:rationale>
+ <p>Signalling the creation of multiple channels together
+ makes writing simple clients much more complicated, can
+ result in lost messages, and isn't nearly as useful in
+ practice as it sounds.</p>
+ </tp:rationale>
+ </tp:docstring>
+
+ <arg name="Channels" type="a(oa{sv})" tp:type="Channel_Details[]">
+ <tp:docstring>
+ The channels and their details.
+ </tp:docstring>
+ </arg>
+ </signal>
+
+ <property name="Channels" tp:name-for-bindings="Channels"
+ type="a(oa{sv})" access="read" tp:type="Channel_Details[]">
+ <tp:added version="0.17.11">(as stable API)</tp:added>
+ <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>ChannelClosed</tp:member-ref> signals.
+ </tp:docstring>
+ </property>
+
+ <signal name="ChannelClosed" tp:name-for-bindings="Channel_Closed">
+ <tp:added version="0.17.11">(as stable API)</tp:added>
+ <tp:docstring>
+ Emitted when a channel is closed and hence disappears from the
+ <tp:member-ref>Channels</tp:member-ref> property.
+
+ <tp:rationale>
+ This is redundant with the <tp:dbus-ref
+ namespace="im.telepathy.v1.Channel">Closed</tp:dbus-ref>
+ signal on the channel itself, but it does provide full change
+ notification for the Channels property.
+ </tp:rationale>
+ </tp:docstring>
+
+ <arg name="Removed" type="o">
+ <tp:docstring>
+ The channel which has been removed from the Channels property
+ </tp:docstring>
+ </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>
+
<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
@@ -927,6 +1455,9 @@ USA.</p>
<tp:changed version="0.99.6">The former Contacts interface
is now part of Connection.</tp:changed>
+
+ <tp:changed version="0.99.UNRELEASED">The Requests interface
+ is now part of Connection.</tp:changed>
</interface>
</node>
<!-- vim:set sw=2 sts=2 et ft=xml: -->
diff --git a/spec/Connection_Interface_Contact_Capabilities1.xml b/spec/Connection_Interface_Contact_Capabilities1.xml
index 51400cbf..6a30c9d7 100644
--- a/spec/Connection_Interface_Contact_Capabilities1.xml
+++ b/spec/Connection_Interface_Contact_Capabilities1.xml
@@ -194,7 +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"
+ namespace="im.telepathy.v1.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
diff --git a/spec/Connection_Interface_Requests.xml b/spec/Connection_Interface_Requests.xml
deleted file mode 100644
index c34b8c15..00000000
--- a/spec/Connection_Interface_Requests.xml
+++ /dev/null
@@ -1,590 +0,0 @@
-<?xml version="1.0" ?>
-<node name="/Connection_Interface_Requests"
- xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"
- >
- <tp:copyright>Copyright (C) 2008 Collabora Limited</tp:copyright>
- <tp:copyright>Copyright (C) 2008 Nokia Corporation</tp:copyright>
- <tp:license xmlns="http://www.w3.org/1999/xhtml">
- <p>This library is free software; you can redistribute it and/or
- modify it under the terms of the GNU Lesser General Public
- License as published by the Free Software Foundation; either
- version 2.1 of the License, or (at your option) any later version.</p>
-
- <p>This library is distributed in the hope that it will be useful,
- but WITHOUT ANY WARRANTY; without even the implied warranty of
- MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
- Lesser General Public License for more details.</p>
-
- <p>You should have received a copy of the GNU Lesser General Public
- License along with this library; if not, write to the Free Software
- Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301,
- USA.</p>
- </tp:license>
-
- <interface name="im.telepathy.v1.Connection.Interface.Requests">
- <tp:requires interface="im.telepathy.v1.Connection"/>
- <tp:added version="0.17.11">(as stable API)</tp:added>
-
- <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
- <p>An interface for channel requests and channel lists. Under
- normal circumstances, applications should deal with this
- interface via the <tp:dbus-ref
- namespace="imt1">ChannelDispatcher</tp:dbus-ref>,
- but lower-level Telepathy applications (such as the
- ChannelDispatcher itself) might need to use this interface
- directly.</p>
-
- <p>This interface is conceptually part of the core Connection
- interface, but is kept separate so that its properties will
- normally only need to be retrieved by the ChannelDispatcher,
- and its signals will normally only wake up the ChannelDispatcher.</p>
- </tp:docstring>
-
- <tp:struct name="Channel_Details" array-name="Channel_Details_List">
- <tp:added version="0.17.11">(as stable API)</tp:added>
-
- <tp:docstring>
- Enough details of a channel that clients can work out how to dispatch
- or handle it.
- </tp:docstring>
-
- <tp:member name="Channel" type="o">
- <tp:docstring>
- The object path of the channel.
- </tp:docstring>
- </tp:member>
-
- <tp:member name="Properties" type="a{sv}"
- tp:type="Qualified_Property_Value_Map">
- <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
- <p>Properties of the channel.</p>
-
- <p>Connection managers MUST NOT include properties in this mapping
- if their values can change. Clients MUST ignore properties
- that appear in this mapping if their values can change.</p>
-
- <tp:rationale>
- <p>If properties that could change were included, the following
- race condition would be likely to exist in some cases:</p>
-
- <ul>
- <li>NewChannels 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>
- <li>Client connects to PChanged signal</li>
- <li>Client should call Get("P") or GetAll here, to avoid the
- race, but client's author has forgotten to do so</li>
- <li>Proxy object thinks P == V1, but actually P == V2</li>
- </ul>
-
- <p>We've taken the opportunity to make the API encourage the
- client author to get it right. Where possible, we intend that
- properties whose value will be used in channel dispatching
- or other "early" processing will be defined so that they are
- immutable (can never change).</p>
- </tp:rationale>
-
- <p>Each dictionary MUST contain the keys
- <tp:dbus-ref>im.telepathy.v1.Channel.ChannelType</tp:dbus-ref>,
- <tp:dbus-ref>im.telepathy.v1.Channel.TargetHandleType</tp:dbus-ref>,
- <tp:dbus-ref>im.telepathy.v1.Channel.TargetHandle</tp:dbus-ref>,
- <tp:dbus-ref>im.telepathy.v1.Channel.TargetID</tp:dbus-ref>
- and
- <tp:dbus-ref>im.telepathy.v1.Channel.Requested</tp:dbus-ref>.
- </p>
-
- <tp:rationale>
- <p>We expect these to be crucial to the channel-dispatching
- process.</p>
- </tp:rationale>
- </tp:docstring>
- </tp:member>
- </tp:struct>
-
- <method name="CreateChannel" tp:name-for-bindings="Create_Channel">
- <tp:added version="0.17.11">(as stable API)</tp:added>
- <tp:changed version="0.17.14">It is now guaranteed that
- CreateChannel returns the channel before NewChannels announces it
- (the reverse was previously guaranteed).</tp:changed>
-
- <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
- <p>Request that an entirely new channel is created.</p>
- </tp:docstring>
-
- <arg direction="in" name="Request" type="a{sv}"
- tp:type="Qualified_Property_Value_Map">
- <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
- <p>A dictionary containing desirable properties, which MUST include
- <tp:dbus-ref
- namespace="im.telepathy.v1.Channel">ChannelType</tp:dbus-ref>.
- Some properties
- are defined such that only an exact match makes sense, and
- connection managers MUST NOT satisfy a request with a channel
- where that property does not match; some properties are defined
- such that the connection manager MAY treat the request as merely
- a hint, and make a best-effort attempt to satisfy it. This is
- documented separately for each property.</p>
-
- <p>If this dictionary contains a property whose semantics
- are not known to the connection manager, this method MUST fail
- without side-effects (in particular it must not create a new
- channel).</p>
-
- <tp:rationale>
- <p>This is necessary if we want to be able to invent properties
- in future that, when used in a request, are hard requirements
- rather than just hints. A connection manager that did not know
- the semantics of those properties could incorrectly return a
- new channel that did not satisfy the requirements.</p>
- </tp:rationale>
-
- <p>The connection manager MUST NOT respond successfully,
- and SHOULD NOT create a new channel or cause any other
- side-effects, unless it can create a new channel that satisfies
- the client's requirements.</p>
-
- <p>Properties that will be set by this argument need not have write
- access after the channel has been created - indeed, it is
- expected that most will be read-only.</p>
- </tp:docstring>
- </arg>
-
- <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
- returns.</p>
-
- <tp:rationale>
- <p>This allows the requester to alter its handling of
- NewChannels by knowing whether one of the channels satisfied
- a request it made.</p>
- </tp:rationale>
- </tp:docstring>
- </arg>
-
- <arg name="Properties" direction="out" type="a{sv}"
- tp:type="Qualified_Property_Value_Map">
- <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
- <p>Properties of the channel that was produced, equivalent to
- the properties in <tp:type>Channel_Details</tp:type>.
- Connection managers MUST NOT include properties here whose
- values can change, for the same reasons as in
- <tp:type>Channel_Details</tp:type>.</p>
- </tp:docstring>
- </arg>
-
- <tp:possible-errors>
- <tp:error name="im.telepathy.v1.Error.Disconnected"/>
- <tp:error name="im.telepathy.v1.Error.NetworkError"/>
- <tp:error name="im.telepathy.v1.Error.NotImplemented">
- <tp:docstring>
- The channel request was one that can never succeed,
- such as requesting an unsupported channel type, or requesting
- a channel type which this connection manager does not support with
- the given target handle type.
- </tp:docstring>
- </tp:error>
- <tp:error name="im.telepathy.v1.Error.InvalidHandle">
- <tp:docstring>
- An invalid handle was requested as the value of a property whose
- value is a handle (like
- <tp:dbus-ref namespace="im.telepathy.v1">Channel.TargetHandle</tp:dbus-ref>),
- or a syntactically invalid identifier was requested as the value
- of a property whose value is the string corresponding to a handle
- (like <tp:dbus-ref
- namespace="im.telepathy.v1">Channel.TargetID</tp:dbus-ref>).
- </tp:docstring>
- </tp:error>
- <tp:error name="im.telepathy.v1.Error.InvalidArgument">
- <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
- 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
- namespace="im.telepathy.v1.Channel.Type.RoomList1">Server</tp:dbus-ref>
- property provided was not a valid DNS name.
- </tp:docstring>
- </tp:error>
- <tp:error name="im.telepathy.v1.Error.NotCapable">
- <tp:docstring>
- The requested channel cannot be created because the requested
- contact is using a client that lacks a particular feature.
- </tp:docstring>
- </tp:error>
- <tp:error name="im.telepathy.v1.Error.Offline">
- <tp:docstring>
- The requested channel cannot be created because the target is
- offline.
- </tp:docstring>
- </tp:error>
- <tp:error name="im.telepathy.v1.Error.NotAvailable">
- <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
- <p>The requested channel cannot be created, but in
- principle, a similar request might succeed in future.
- For instance, this might be because:</p>
-
- <ul>
- <li>a channel matching the request already exists and the
- protocol requires that only one such channel can exist at a
- time</li>
- <li>a channel matching the request has already been requested
- (by a previous call to CreateChannel,
- <tp:member-ref>EnsureChannel</tp:member-ref>,
- or similar) and the protocol requires that only one such
- channel can exist at a time</li>
- </ul>
- </tp:docstring>
- </tp:error>
- <tp:error name="im.telepathy.v1.Error.Channel.Banned"/>
- <tp:error name="im.telepathy.v1.Error.Channel.Full"/>
- <tp:error name="im.telepathy.v1.Error.Channel.InviteOnly"/>
- <tp:error name="im.telepathy.v1.Error.PermissionDenied"/>
- </tp:possible-errors>
- </method>
-
- <method name="EnsureChannel" tp:name-for-bindings="Ensure_Channel">
- <tp:added version="0.17.12"/>
- <tp:changed version="0.17.14">It is now guaranteed that if
- the channel was created by this call to EnsureChannel, it's returned
- before NewChannels announces it (the reverse was previously
- guaranteed).</tp:changed>
-
- <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
- <p>Request that channels are ensured to exist.</p>
-
- <tp:rationale>
- <p>The connection manager is in the best position to determine which
- existing channels could satisfy which requests.</p>
- </tp:rationale>
-
- </tp:docstring>
-
- <arg direction="in" name="Request" type="a{sv}"
- tp:type="Qualified_Property_Value_Map">
- <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
- <p>A dictionary containing desirable properties, with the same
- semantics as the corresponding parameter to
- <tp:member-ref>CreateChannel</tp:member-ref>.</p>
- </tp:docstring>
- </arg>
-
- <arg name="Yours" direction="out" type="b">
- <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
- <p>If false, the caller of EnsureChannel MUST assume that some
- other process is handling this channel; if true, the caller of
- EnsureChannel SHOULD handle it themselves or delegate it to another
- client.</p>
-
- <p>If the creation of a channel makes several calls to EnsureChannel
- (and no other requests) successful, exactly one of those calls MUST
- return a true value for this argument.</p>
-
- <p>If the creation of a channel makes other requests successful,
- the value returned for this argument MUST be such that exactly
- one of the clients making requests ends up responsible for the
- channel. In particular, if
- <tp:member-ref>CreateChannel</tp:member-ref> returns a channel
- <em>C</em>, any EnsureChannel calls that also return <em>C</em>
- MUST return a false value for this argument.</p>
- </tp:docstring>
- </arg>
-
- <arg name="Channel" direction="out" type="o">
- <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
- returns.
-
- <tp:rationale>
- <p>This allows the requester to alter its handling of
- NewChannels by knowing whether one of the channels satisfied
- a request it made.</p>
- </tp:rationale>
- </tp:docstring>
- </arg>
-
- <arg name="Properties" direction="out" type="a{sv}"
- tp:type="Qualified_Property_Value_Map">
- <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
- <p>Properties of the channel that was produced, equivalent to
- the properties in <tp:type>Channel_Details</tp:type>.
- Connection managers MUST NOT include properties here whose
- values can change, for the same reasons as in
- <tp:type>Channel_Details</tp:type>.</p>
- </tp:docstring>
- </arg>
-
- <tp:possible-errors>
- <tp:error name="im.telepathy.v1.Error.Disconnected"/>
- <tp:error name="im.telepathy.v1.Error.NetworkError"/>
- <tp:error name="im.telepathy.v1.Error.NotImplemented">
- <tp:docstring>
- The channel request was one that can never succeed,
- such as requesting an unsupported channel type, or requesting
- a channel type which this connection manager does not support with
- the given target handle type.
- </tp:docstring>
- </tp:error>
- <tp:error name="im.telepathy.v1.Error.InvalidHandle">
- <tp:docstring>
- An invalid handle was requested as the value of a property whose
- value is a handle (like
- <tp:dbus-ref namespace="im.telepathy.v1">Channel.TargetHandle</tp:dbus-ref>),
- or a syntactically invalid identifier was requested as the value
- of a property whose value is the string corresponding to a handle
- (like <tp:dbus-ref
- namespace="im.telepathy.v1">Channel.TargetID</tp:dbus-ref>).
- </tp:docstring>
- </tp:error>
- <tp:error name="im.telepathy.v1.Error.InvalidArgument">
- <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
- 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
- namespace="im.telepathy.v1.Channel.Type.RoomList1">Server</tp:dbus-ref>
- property provided was not a valid DNS name.
- </tp:docstring>
- </tp:error>
- <tp:error name="im.telepathy.v1.Error.NotCapable">
- <tp:docstring>
- The requested channel cannot be created because the requested
- contact is using a client that lacks a particular feature.
- </tp:docstring>
- </tp:error>
- <tp:error name="im.telepathy.v1.Error.Offline">
- <tp:docstring>
- The requested channel cannot be created because the target is
- offline.
- </tp:docstring>
- </tp:error>
- <tp:error name="im.telepathy.v1.Error.NotAvailable">
- <tp:docstring>
- The requested channel cannot be created, but in
- principle, a similar request might succeed in future.
- </tp:docstring>
- </tp:error>
- <tp:error name="im.telepathy.v1.Error.Channel.Banned"/>
- <tp:error name="im.telepathy.v1.Error.Channel.Full"/>
- <tp:error name="im.telepathy.v1.Error.Channel.InviteOnly"/>
- <tp:error name="im.telepathy.v1.Error.PermissionDenied"/>
- </tp:possible-errors>
- </method>
-
- <signal name="NewChannels" tp:name-for-bindings="New_Channels">
- <tp:added version="0.17.11">(as stable API)</tp:added>
- <tp:changed version="0.17.14">Added a guarantee of ordering
- relative to the old NewChannel signal (now removed)</tp:changed>
- <tp:changed version="0.27.1">Added recommendation against
- announcing channels together</tp:changed>
-
- <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>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
- separately, or not expose the Text channel on the bus
- until it's actually requested (or an incoming message
- appears).</p>
-
- <tp:rationale>
- <p>Signalling the creation of multiple channels together
- makes writing simple clients much more complicated, can
- result in lost messages, and isn't nearly as useful in
- practice as it sounds.</p>
- </tp:rationale>
- </tp:docstring>
-
- <arg name="Channels" type="a(oa{sv})" tp:type="Channel_Details[]">
- <tp:docstring>
- The channels and their details.
- </tp:docstring>
- </arg>
- </signal>
-
- <property name="Channels" tp:name-for-bindings="Channels"
- type="a(oa{sv})" access="read" tp:type="Channel_Details[]">
- <tp:added version="0.17.11">(as stable API)</tp:added>
- <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>ChannelClosed</tp:member-ref> signals.
- </tp:docstring>
- </property>
-
- <signal name="ChannelClosed" tp:name-for-bindings="Channel_Closed">
- <tp:added version="0.17.11">(as stable API)</tp:added>
- <tp:docstring>
- Emitted when a channel is closed and hence disappears from the
- <tp:member-ref>Channels</tp:member-ref> property.
-
- <tp:rationale>
- This is redundant with the <tp:dbus-ref
- namespace="im.telepathy.v1.Channel">Closed</tp:dbus-ref>
- signal on the channel itself, but it does provide full change
- notification for the Channels property.
- </tp:rationale>
- </tp:docstring>
-
- <arg name="Removed" type="o">
- <tp:docstring>
- The channel which has been removed from the Channels property
- </tp:docstring>
- </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: -->
diff --git a/spec/Protocol.xml b/spec/Protocol.xml
index a7293936..d80074f1 100644
--- a/spec/Protocol.xml
+++ b/spec/Protocol.xml
@@ -137,10 +137,6 @@ allowed=im.telepathy.v1.Channel.TargetHandle;im.telepathy.v1.Channel.TargetID;
<code>.manager</code> file, using the key
<code>ConnectionInterfaces</code>. The corresponding value
is a list of D-Bus interface names, each followed by a semicolon.</p>
-
- <p>As a special case, the mandatory <tp:dbus-ref
- namespace="imt1.Connection.Interface">Requests</tp:dbus-ref>
- interface SHOULD NOT be listed in this property.</p>
</tp:docstring>
</property>
@@ -153,7 +149,7 @@ 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"
+ namespace="im.telepathy.v1.Connection"
>RequestableChannelClasses</tp:dbus-ref> property).</p>
<p>Whether a Connection will have all, some or none of these
diff --git a/spec/Protocol_Interface_Addressing1.xml b/spec/Protocol_Interface_Addressing1.xml
index f42770ff..2312822e 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
<tp:dbus-ref
- namespace="im.telepathy.v1.Connection.Interface">Requests.RequestableChannelClasses</tp:dbus-ref>'s
+ namespace="im.telepathy.v1.Connection">RequestableChannelClasses</tp:dbus-ref>'s
TargetURIScheme fixed-property instead.</p>
<p>Connection managers with a <code>.manager</code> file
diff --git a/spec/all.xml b/spec/all.xml
index abd3c299..e3926881 100644
--- a/spec/all.xml
+++ b/spec/all.xml
@@ -48,8 +48,6 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
</p>
</tp:docstring>
<xi:include href="Connection.xml"/>
- <xi:include href="Connection_Interface_Requests.xml"/>
-
<tp:section name="Contact list interfaces">
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
<p>