Attachment 88630 Details for Bug 69430 – [02/12] Flatten Requests interface into Connection

[02/12] Flatten Requests interface into Connection

0002-Flatten-Requests-interface-into-Connection.patch (text/plain), 89.57 KB, created by Simon McVittie on 2013-11-04 18:22:45 UTC

(hide)

Description:

Filename:

MIME Type:

Creator: Simon McVittie

Created: 2013-11-04 18:22:45 UTC

Size: 89.57 KB

patch

obsolete

>From 5b60145b258e1682cb2eb16530211cc4e0cb9935 Mon Sep 17 00:00:00 2001
>From: Simon McVittie <simon.mcvittie@collabora.co.uk>
>Date: Mon, 4 Nov 2013 14:13:48 +0000
>Subject: [PATCH 02/12] Flatten Requests interface into Connection
>
>We keep meaning to do this one day. That day has arrived.
>---
> doc/templates/interface.html | 20 +-
> spec/Channel.xml | 4 +-
> spec/Channel_Dispatch_Operation.xml | 2 +-
> spec/Channel_Dispatcher.xml | 6 +-
> spec/Channel_Dispatcher_Interface_Messages1.xml | 2 +-
> spec/Channel_Interface_Addressing1.xml | 2 +-
> spec/Channel_Interface_Conference1.xml | 14 +-
> spec/Channel_Interface_SMS1.xml | 2 +-
> spec/Channel_Interface_Tube1.xml | 6 +-
> spec/Channel_Request.xml | 6 +-
> spec/Channel_Type_Call1.xml | 8 +-
> spec/Channel_Type_Contact_Search1.xml | 12 +-
> spec/Channel_Type_DBus_Tube1.xml | 4 +-
> spec/Channel_Type_File_Transfer1.xml | 18 +-
> spec/Channel_Type_Room_List1.xml | 2 +-
> spec/Channel_Type_Server_Authentication1.xml | 2 +-
> spec/Channel_Type_Server_TLS_Connection1.xml | 2 +-
> spec/Channel_Type_Stream_Tube1.xml | 4 +-
> spec/Channel_Type_Text.xml | 2 +-
> spec/Client_Observer.xml | 4 +-
> spec/Connection.xml | 538 ++++++++++++++++++-
> .../Connection_Interface_Contact_Capabilities1.xml | 2 +-
> spec/Connection_Interface_Requests.xml | 582 ---------------------
> spec/Protocol.xml | 4 +-
> spec/Protocol_Interface_Addressing1.xml | 2 +-
> spec/all.xml | 1 -
> 26 files changed, 602 insertions(+), 649 deletions(-)
> delete mode 100644 spec/Connection_Interface_Requests.xml
>
>diff --git a/doc/templates/interface.html b/doc/templates/interface.html
>index ed67a92..981f67e 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 requestable, 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 requestable, 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 fa208d2..69f52d6 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">
> 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>.
>+ <tp:dbus-ref namespace="im.telepathy.v1">Connection.CreateChannel</tp:dbus-ref>.
> 
> <tp:rationale>
> 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.</
> 
> 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 4225dc3..9da09fd 100644
>--- a/spec/Channel_Dispatch_Operation.xml
>+++ b/spec/Channel_Dispatch_Operation.xml
>@@ -36,7 +36,7 @@
> from outgoing requests for channels.
> 
> 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 434dd11..b8f5f87 100644
>--- a/spec/Channel_Dispatcher.xml
>+++ b/spec/Channel_Dispatcher.xml
>@@ -153,7 +153,7 @@
> <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
> 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>.
> 
> 
> Certain properties will not necessarily make sense in this
>@@ -318,7 +318,7 @@
> <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
> 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>.
> 
> 
> 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 9b92acb..95fd08a 100644
>--- a/spec/Channel_Dispatcher_Interface_Messages1.xml
>+++ b/spec/Channel_Dispatcher_Interface_Messages1.xml
>@@ -126,7 +126,7 @@
> 
> 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 ac6c198..3179cb6 100644
>--- a/spec/Channel_Interface_Addressing1.xml
>+++ b/spec/Channel_Interface_Addressing1.xml
>@@ -54,7 +54,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
> <tp:rationale>
> 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.
> </tp:rationale>
> 
>diff --git a/spec/Channel_Interface_Conference1.xml b/spec/Channel_Interface_Conference1.xml
>index ae2ee3b..baf3677 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:
> 
> <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:
> 
> <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.
> 
>- <h4>Sample <tp:dbus-ref namespace='imt1.Connection.Interface.Requests'
>+ <h4>Sample <tp:dbus-ref namespace='imt1.Connection'
> >RequestableChannelClasses</tp:dbus-ref></h4>
> 
> 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.
>@@ -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.
>@@ -521,7 +521,7 @@
> 
> 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.
> 
>diff --git a/spec/Channel_Interface_SMS1.xml b/spec/Channel_Interface_SMS1.xml
>index 226505d..a4f1d74 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.
> 
> 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.
> 
> <tp:rationale>
>diff --git a/spec/Channel_Interface_Tube1.xml b/spec/Channel_Interface_Tube1.xml
>index d97b0ae..d4eeb6a 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.
> 
> 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.
> 
> 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.
> </tp:docstring>
> </property>
>@@ -93,7 +93,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
> 
> 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.
> </tp:docstring>
> </property>
>diff --git a/spec/Channel_Request.xml b/spec/Channel_Request.xml
>index 7529098..4e52d5b 100644
>--- a/spec/Channel_Request.xml
>+++ b/spec/Channel_Request.xml
>@@ -154,7 +154,7 @@
> 
> 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">
> 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>.
>@@ -322,7 +322,7 @@
> tp:type="Qualified_Property_Value_Map">
> <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
> 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.
> </tp:docstring>
> </arg>
>diff --git a/spec/Channel_Type_Call1.xml b/spec/Channel_Type_Call1.xml
>index 4c30466..5260e8e 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.
> 
> 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:
> 
> <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>
> 
> 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:
>diff --git a/spec/Channel_Type_Contact_Search1.xml b/spec/Channel_Type_Contact_Search1.xml
>index cfc3a62..9fdab7f 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.
> 
> 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.</
> 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>).
>+ namespace='imt1.Connection'>RequestableChannelClasses</tp:dbus-ref>).
> 
> 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>.
> 
> 
> 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).
> 
> 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.
> 
> <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 6f7f6f1..4917643 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.
> 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.
> </tp:docstring>
> </property>
>@@ -190,7 +190,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
> </tp:rationale>
> 
> 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.
> 
> </tp:docstring>
>diff --git a/spec/Channel_Type_File_Transfer1.xml b/spec/Channel_Type_File_Transfer1.xml
>index 67ccf11..04258f9 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.
> 
> 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.
> </tp:docstring>
>@@ -120,7 +120,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
> be set to monkey.pdf.
> 
> 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.
> </tp:docstring>
> </property>
>@@ -138,7 +138,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
> to the byte.
> 
> 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.
> </tp:docstring>
>@@ -151,15 +151,15 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
> The type of the <tp:member-ref>ContentHash</tp:member-ref> property.
> 
> 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.
> 
> 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.
> 
> 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.
> 
> 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.
> </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
> 
> 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.
> </tp:docstring>
> </property>
>diff --git a/spec/Channel_Type_Room_List1.xml b/spec/Channel_Type_Room_List1.xml
>index 91d86ac..5ae45ab 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.</
> 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 dcd1e34..d3ebfc6 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.</
> 
> 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 a0a5b41..c2bfcf6 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.
>diff --git a/spec/Channel_Type_Stream_Tube1.xml b/spec/Channel_Type_Stream_Tube1.xml
>index 1081de2..7b192cc 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.
> When the tube is offered, the service name is transmitted to the
> other end.
> 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.
> </tp:docstring>
> </property>
>@@ -286,7 +286,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
> access control.
> 
> 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.
> 
> </tp:docstring>
>diff --git a/spec/Channel_Type_Text.xml b/spec/Channel_Type_Text.xml
>index cebc2ec..5c1707a 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 1cfd596..5ad32eb 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.
> 
> 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">
> 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.
> 
> If the same NewChannels signal announces some channels that match
>diff --git a/spec/Connection.xml b/spec/Connection.xml
>index 51a2ca7..b4414ca 100644
>--- a/spec/Connection.xml
>+++ b/spec/Connection.xml
>@@ -22,7 +22,6 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301,
> USA.
> </tp:license>
> <interface name="im.telepathy.v1.Connection">
>- <tp:requires interface="im.telepathy.v1.Connection.Interface.Requests"/>
> <tp:requires interface="im.telepathy.v1.Connection.Interface.Contacts"/>
> 
> <method name="Connect" tp:name-for-bindings="Connect">
>@@ -668,6 +667,540 @@ USA.
> </arg>
> </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">
>+ Properties of the channel.
>+
>+ 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.
>+
>+ <tp:rationale>
>+ If properties that could change were included, the following
>+ race condition would be likely to exist in some cases:
>+
>+ <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>
>+
>+ 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).
>+ </tp:rationale>
>+
>+ 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>.
>+ 
>+
>+ <tp:rationale>
>+ We expect these to be crucial to the channel-dispatching
>+ process.
>+ </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">
>+ Request that an entirely new channel is created.
>+ </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">
>+ 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.
>+
>+ 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).
>+
>+ <tp:rationale>
>+ 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.
>+ </tp:rationale>
>+
>+ 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.
>+
>+ 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.
>+ </tp:docstring>
>+ </arg>
>+
>+ <arg name="Channel" direction="out" type="o">
>+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
>+ The Channel object, which MUST NOT be signalled with
>+ <tp:member-ref>NewChannels</tp:member-ref> until after this method
>+ returns.
>+
>+ <tp:rationale>
>+ This allows the requester to alter its handling of
>+ NewChannels by knowing whether one of the channels satisfied
>+ a request it made.
>+ </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">
>+ 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>.
>+ </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">
>+ The requested channel cannot be created, but in
>+ principle, a similar request might succeed in future.
>+ For instance, this might be because:
>+
>+ <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">
>+ Request that channels are ensured to exist.
>+
>+ <tp:rationale>
>+ The connection manager is in the best position to determine which
>+ existing channels could satisfy which requests.
>+ </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">
>+ A dictionary containing desirable properties, with the same
>+ semantics as the corresponding parameter to
>+ <tp:member-ref>CreateChannel</tp:member-ref>.
>+ </tp:docstring>
>+ </arg>
>+
>+ <arg name="Yours" direction="out" type="b">
>+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
>+ 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.
>+
>+ 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.
>+
>+ 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
>+ C, any EnsureChannel calls that also return C
>+ MUST return a false value for this argument.
>+ </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>
>+ This allows the requester to alter its handling of
>+ NewChannels by knowing whether one of the channels satisfied
>+ a request it made.
>+ </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">
>+ 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>.
>+ </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">
>+ A new channel has been created. The connection manager
>+ SHOULD emit a single signal for each channel created.
>+
>+ 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).
>+
>+ <tp:rationale>
>+ 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.
>+ </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">
>+ Mapping representing a class of channels that can be requested
>+ from a connection manager, can be handled by a user interface,
>+ are supported by a contact, etc.
>+
>+ Classes of channel are identified by the fixed values of
>+ a subset of their properties.
>+
>+ Channel classes SHOULD always include the keys
>+ <tp:dbus-ref>im.telepathy.v1.Channel.ChannelType</tp:dbus-ref>
>+ and
>+ <tp:dbus-ref>im.telepathy.v1.Channel.TargetHandleType</tp:dbus-ref>.
>+ </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">
>+ Structure representing a class of channels that can be requested,
>+ identified by a set of properties that identify that class of
>+ channel.
>+
>+ <tp:rationale>
>+ 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.
>+ </tp:rationale>
>+
>+ 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.
>+
>+ <tp:rationale>
>+ 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:
>+
>+ <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">
>+ The property values that identify this requestable channel class.
>+ These properties MUST be included in requests for a channel of this
>+ class, and MUST take these values.
>+
>+ Clients that do not understand the semantics of all the
>+ Fixed_Properties MUST NOT request channels of this class, since
>+ they would be unable to avoid making an incorrect request.
>+
>+ This implies that connection managers wishing to make channels
>+ available to old or minimal clients SHOULD have a channel class
>+ with the minimum number of Fixed_Properties, and MAY additionally
>+ have channel classes with extra Fixed_Properties.
>+
>+ Interface designers SHOULD avoid introducing fixed properties
>+ whose types are not serializable in a <code>.manager</code>
>+ file.
>+
>+ <tp:rationale>
>+ Connection managers with a fixed property that is not
>+ serializable cannot have a complete <code>.manager</code>
>+ file.
>+ </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">
>+ Properties that MAY be set when requesting a channel of this
>+ channel type and handle type.
>+
>+ This array MUST NOT include properties that are in the
>+ Fixed_Properties mapping.
>+
>+ Properties in this array may either be required or optional,
>+ according to their documented semantics.
>+
>+ <tp:rationale>
>+ 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.
>+ </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">
>+ 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.
>+
>+ 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.
>+
>+ <tp:rationale>
>+ 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).
>+ </tp:rationale>
>+ </tp:docstring>
>+ </property>
>+
> <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
> This models a connection to a single user account on a communication
> service. Its basic capability is to provide the facility to request and
>@@ -747,6 +1280,9 @@ USA.
> and signals have been removed from this interface including
> anything to do with handle reference counting.</tp:changed>
> 
>+ <tp:changed version="0.99.UNRELEASED">The Requests interface
>+ is now part of Connection.</tp:changed>
>+
> </interface>
> </node>
> 
>diff --git a/spec/Connection_Interface_Contact_Capabilities1.xml b/spec/Connection_Interface_Contact_Capabilities1.xml
>index 51400cb..6a30c9d 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">
> 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 c08860f..0000000
>--- a/spec/Connection_Interface_Requests.xml
>+++ /dev/null
>@@ -1,582 +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">
>- 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.
>-
>- 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.
>-
>- 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.
>- </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">
>- An enhanced version of the Telepathy connection interface, which can
>- represent bundles of channels that should be dispatched together, and
>- does not assume any particular properties by which channels are
>- uniquely identifiable.
>- </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">
>- Properties of the channel.
>-
>- 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.
>-
>- <tp:rationale>
>- If properties that could change were included, the following
>- race condition would be likely to exist in some cases:
>-
>- <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>
>-
>- 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).
>- </tp:rationale>
>-
>- 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>.
>- 
>-
>- <tp:rationale>
>- We expect these to be crucial to the channel-dispatching
>- process.
>- </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">
>- Request that an entirely new channel is created.
>- </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">
>- 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.
>-
>- 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).
>-
>- <tp:rationale>
>- 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.
>- </tp:rationale>
>-
>- 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.
>-
>- 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.
>- </tp:docstring>
>- </arg>
>-
>- <arg name="Channel" direction="out" type="o">
>- <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
>- The Channel object, which MUST NOT be signalled with
>- <tp:member-ref>NewChannels</tp:member-ref> until after this method
>- returns.
>-
>- <tp:rationale>
>- This allows the requester to alter its handling of
>- NewChannels by knowing whether one of the channels satisfied
>- a request it made.
>- </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">
>- 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>.
>- </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">
>- The requested channel cannot be created, but in
>- principle, a similar request might succeed in future.
>- For instance, this might be because:
>-
>- <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">
>- Request that channels are ensured to exist.
>-
>- <tp:rationale>
>- The connection manager is in the best position to determine which
>- existing channels could satisfy which requests.
>- </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">
>- A dictionary containing desirable properties, with the same
>- semantics as the corresponding parameter to
>- <tp:member-ref>CreateChannel</tp:member-ref>.
>- </tp:docstring>
>- </arg>
>-
>- <arg name="Yours" direction="out" type="b">
>- <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
>- 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.
>-
>- 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.
>-
>- 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
>- C, any EnsureChannel calls that also return C
>- MUST return a false value for this argument.
>- </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>
>- This allows the requester to alter its handling of
>- NewChannels by knowing whether one of the channels satisfied
>- a request it made.
>- </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">
>- 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>.
>- </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">
>- A new channel has been created. The connection manager
>- SHOULD emit a single signal for each channel created.
>-
>- 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).
>-
>- <tp:rationale>
>- 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.
>- </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">
>- Mapping representing a class of channels that can be requested
>- from a connection manager, can be handled by a user interface,
>- are supported by a contact, etc.
>-
>- Classes of channel are identified by the fixed values of
>- a subset of their properties.
>-
>- Channel classes SHOULD always include the keys
>- <tp:dbus-ref>im.telepathy.v1.Channel.ChannelType</tp:dbus-ref>
>- and
>- <tp:dbus-ref>im.telepathy.v1.Channel.TargetHandleType</tp:dbus-ref>.
>- </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">
>- Structure representing a class of channels that can be requested,
>- identified by a set of properties that identify that class of
>- channel.
>-
>- <tp:rationale>
>- 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.
>- </tp:rationale>
>-
>- 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.
>-
>- <tp:rationale>
>- 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:
>-
>- <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">
>- The property values that identify this requestable channel class.
>- These properties MUST be included in requests for a channel of this
>- class, and MUST take these values.
>-
>- Clients that do not understand the semantics of all the
>- Fixed_Properties MUST NOT request channels of this class, since
>- they would be unable to avoid making an incorrect request.
>-
>- This implies that connection managers wishing to make channels
>- available to old or minimal clients SHOULD have a channel class
>- with the minimum number of Fixed_Properties, and MAY additionally
>- have channel classes with extra Fixed_Properties.
>-
>- Interface designers SHOULD avoid introducing fixed properties
>- whose types are not serializable in a <code>.manager</code>
>- file.
>-
>- <tp:rationale>
>- Connection managers with a fixed property that is not
>- serializable cannot have a complete <code>.manager</code>
>- file.
>- </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">
>- Properties that MAY be set when requesting a channel of this
>- channel type and handle type.
>-
>- This array MUST NOT include properties that are in the
>- Fixed_Properties mapping.
>-
>- Properties in this array may either be required or optional,
>- according to their documented semantics.
>-
>- <tp:rationale>
>- 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.
>- </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">
>- 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.
>-
>- 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.
>-
>- <tp:rationale>
>- 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).
>- </tp:rationale>
>- </tp:docstring>
>- </property>
>-
>- </interface>
>-</node>
>-
>diff --git a/spec/Protocol.xml b/spec/Protocol.xml
>index c77f508..0cd0786 100644
>--- a/spec/Protocol.xml
>+++ b/spec/Protocol.xml
>@@ -53,7 +53,7 @@ Interfaces=
> 
> [Protocol example]
> Interfaces=
>-ConnectionInterfaces=im.telepathy.v1.Connection.Interface.Requests;
>+ConnectionInterfaces=
> param-account=s required
> param-password=s required secret
> RequestableChannelClasses=text;
>@@ -149,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).
> 
> 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 f42770f..2312822 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.
> 
> Connection managers with a <code>.manager</code> file
>diff --git a/spec/all.xml b/spec/all.xml
>index 3f3ad63..20d15c8 100644
>--- a/spec/all.xml
>+++ b/spec/all.xml
>@@ -49,7 +49,6 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
> </tp:docstring>
> <xi:include href="Connection.xml"/>
> <xi:include href="Connection_Interface_Contacts.xml"/>
>- <xi:include href="Connection_Interface_Requests.xml"/>
> 
> <tp:section name="Contact list interfaces">
> <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
>-- 
>1.8.4.2
>

Actions: View

Attachments on bug 69430: 88629 | 88630 | 88631 | 88632 | 88633 | 88634 | 88635 | 88636 | 88637 | 88638 | 88639 | 88640 | 92141

Use of freedesktop.org services, including Bugzilla, is subject to our Code of Conduct. How we collect and use information is described in our Privacy Policy.