diff options
26 files changed, 671 insertions, 610 deletions
diff --git a/doc/templates/interface.html b/doc/templates/interface.html index 0ede0364..221b15f2 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.html#im.telepathy.v1.Connection.NewChannel">NewChannel</a> + of <a href="Connection_Interface_Requests.html#im.telepathy.v1.Connection.Interface.Requests.NewChannel">NewChannel</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.html#im.telepathy.v1.Connection.NewChannel">NewChannel</a> + of <a href="Connection_Interface_Requests.html#im.telepathy.v1.Connection.Interface.Requests.NewChannel">NewChannel</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.html#im.telepathy.v1.Connection.CreateChannel">CreateChannel</a> + <a href="Connection_Interface_Requests.html#im.telepathy.v1.Connection.Interface.Requests.CreateChannel">CreateChannel</a> and - <a href="Connection.html#im.telepathy.v1.Connection.EnsureChannel">EnsureChannel</a> + <a href="Connection_Interface_Requests.html#im.telepathy.v1.Connection.Interface.Requests.EnsureChannel">EnsureChannel</a> methods - on <a href="Connection.html">Connection</a> + on <a href="Connection_Interface_Requests.html">Requests</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.html#im.telepathy.v1.Connection.RequestableChannelClasses">RequestableChannelClass</a> + a <a href="Connection_Interface_Requests.html#im.telepathy.v1.Connection.Interface.Requests.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.html#im.telepathy.v1.Connection.CreateChannel">CreateChannel</a> + <a href="Connection_Interface_Requests.html#im.telepathy.v1.Connection.Interface.Requests.CreateChannel">CreateChannel</a> and - <a href="Connection.html#im.telepathy.v1.Connection.EnsureChannel">EnsureChannel</a> + <a href="Connection_Interface_Requests.html#im.telepathy.v1.Connection.Interface.Requests.EnsureChannel">EnsureChannel</a> methods - on <a href="Connection.html">Connection</a> + on <a href="Connection_Interface_Requests.html">Requests</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.html#im.telepathy.v1.Connection.RequestableChannelClasses">RequestableChannelClass</a> + a <a href="Connection_Interface_Requests.html#im.telepathy.v1.Connection.Interface.Requests.RequestableChannelClasses">RequestableChannelClass</a> advertised by the CM.</div> #end if diff --git a/spec/Channel.xml b/spec/Channel.xml index c5f219fb..36426e6d 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.CreateChannel</tp:dbus-ref>.</p> + <tp:dbus-ref namespace="im.telepathy.v1">Connection.Interface.Requests.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'>NewChannel</tp:dbus-ref>), + namespace='imt1.Connection.Interface.Requests'>NewChannel</tp:dbus-ref>), provided to clients in the <tp:dbus-ref namespace='imt1.Client.Observer'>ObserveChannel</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 6c770f25..85789fdb 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.NewChannel</tp:dbus-ref> + namespace="im.telepathy.v1">Connection.Interface.Requests.NewChannel</tp:dbus-ref> signal contains a channel whose <tp:dbus-ref namespace="im.telepathy.v1.Channel">Requested</tp:dbus-ref> property is false, a ChannelDispatchOperation diff --git a/spec/Channel_Dispatcher.xml b/spec/Channel_Dispatcher.xml index 3d7d52b1..1bf50e09 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.CreateChannel</tp:dbus-ref>. + <tp:dbus-ref namespace="im.telepathy.v1">Connection.Interface.Requests.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.EnsureChannel</tp:dbus-ref>. + <tp:dbus-ref namespace="im.telepathy.v1">Connection.Interface.Requests.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.EnsureChannel</tp:dbus-ref> + namespace="im.telepathy.v1">Connection.Interface.Requests.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 95fd08ae..9b92acba 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">EnsureChannel</tp:dbus-ref> + namespace="imt1.Connection.Interface">Requests.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 a61c0ead..7b4ff432 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">RequestableChannelClasses</tp:dbus-ref> + <tp:dbus-ref namespace="im.telepathy.v1.Connection.Interface.Requests">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 5bb53603..d4a42d5c 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">RequestableChannelClasses</tp:dbus-ref>, + namespace="im.telepathy.v1.Connection.Interface.Requests">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">CreateChannel</tp:dbus-ref>({ + <code><tp:dbus-ref namespace="im.telepathy.v1.Connection.Interface.Requests">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">EnsureChannel</tp:dbus-ref>({ + <code><tp:dbus-ref namespace="im.telepathy.v1.Connection.Interface.Requests">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' + <h4>Sample <tp:dbus-ref namespace='imt1.Connection.Interface.Requests' >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' + namespace='imt1.Connection.Interface.Requests' >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" + namespace="im.telepathy.v1.Connection.Interface.Requests" >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" + namespace="im.telepathy.v1.Connection.Interface.Requests" >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 ab23b3d5..5e601c76 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" + namespace="imt1.Connection.Interface.Requests" >NewChannel</tp:dbus-ref> signals.</p> <tp:rationale> diff --git a/spec/Channel_Interface_Tube1.xml b/spec/Channel_Interface_Tube1.xml index 3d43a2db..703a0ea0 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">CreateChannel</tp:dbus-ref>, + namespace="im.telepathy.v1.Connection.Interface.Requests">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">NewChannel</tp:dbus-ref> + namespace="im.telepathy.v1.Connection.Interface.Requests">NewChannel</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">CreateChannel</tp:dbus-ref>, + namespace="im.telepathy.v1.Connection.Interface.Requests">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 2b98284e..ba298208 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.CreateChannel</tp:dbus-ref> + namespace="im.telepathy.v1">Connection.Interface.Requests.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">CreateChannel</tp:dbus-ref>, + namespace="im.telepathy.v1.Connection.Interface.Requests">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" + in a <tp:dbus-ref namespace="imt1.Connection.Interface.Requests" >NewChannel</tp:dbus-ref> signal.</p> </tp:docstring> </arg> diff --git a/spec/Channel_Type_Call1.xml b/spec/Channel_Type_Call1.xml index 341b7534..40552383 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">CreateChannel</tp:dbus-ref>({ +<tp:dbus-ref namespace="imt1.Connection.Interface.Requests">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">NewChannel</tp:dbus-ref> + namespace="imt1.Connection.Interface.Requests">NewChannel</tp:dbus-ref> signal will occur:</p> <blockquote> <pre> -<tp:dbus-ref namespace="imt1.Connection">NewChannel</tp:dbus-ref>( +<tp:dbus-ref namespace="imt1.Connection.Interface.Requests">NewChannel</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">RequestableChannelClasses</tp:dbus-ref> + namespace="imt1.Connection.Interface.Requests">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 2841ae0d..535f8844 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' + in <tp:dbus-ref namespace='imt1.Connection.Interface.Requests' >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'>RequestableChannelClasses</tp:dbus-ref>).</p> + namespace='imt1.Connection.Interface.Requests'>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">CreateChannel</tp:dbus-ref>. + <tp:dbus-ref namespace="im.telepathy.v1.Connection.Interface.Requests">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">EnsureChannel</tp:dbus-ref>; + namespace="im.telepathy.v1.Connection.Interface.Requests">EnsureChannel</tp:dbus-ref>; clients SHOULD request channels of this type using <tp:dbus-ref - namespace="im.telepathy.v1.Connection">CreateChannel</tp:dbus-ref> + namespace="im.telepathy.v1.Connection.Interface.Requests">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">NewChannel</tp:dbus-ref> + namespace="im.telepathy.v1.Connection.Interface.Requests">NewChannel</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 4917643e..6f7f6f19 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">CreateChannel</tp:dbus-ref>, + namespace="im.telepathy.v1.Connection.Interface.Requests">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.CreateChannel</tp:dbus-ref>, + <tp:dbus-ref namespace="im.telepathy.v1">Connection.Interface.Requests.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 04258f90..67ccf11e 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.CreateChannel</tp:dbus-ref> + <tp:dbus-ref namespace="im.telepathy.v1">Connection.Interface.Requests.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.CreateChannel</tp:dbus-ref> + <tp:dbus-ref namespace="im.telepathy.v1">Connection.Interface.Requests.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.CreateChannel</tp:dbus-ref> + <tp:dbus-ref namespace="im.telepathy.v1">Connection.Interface.Requests.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.CreateChannel</tp:dbus-ref> + <tp:dbus-ref namespace="im.telepathy.v1">Connection.Interface.Requests.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.CreateChannel</tp:dbus-ref> + <tp:dbus-ref namespace="im.telepathy.v1">Connection.Interface.Requests.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">RequestableChannelClasses</tp:dbus-ref> + namespace="im.telepathy.v1.Connection.Interface.Requests">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.CreateChannel</tp:dbus-ref> + <tp:dbus-ref namespace="im.telepathy.v1">Connection.Interface.Requests.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.CreateChannel</tp:dbus-ref> + <tp:dbus-ref namespace="im.telepathy.v1">Connection.Interface.Requests.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.CreateChannel</tp:dbus-ref> + <tp:dbus-ref namespace="im.telepathy.v1">Connection.Interface.Requests.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 5ae45ab8..91d86ac4 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">CreateChannel</tp:dbus-ref> + namespace="imt1.Connection.Interface.Requests">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 d3ebfc68..dcd1e34b 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">CreateChannel</tp:dbus-ref>. + namespace="imt1.Connection.Interface.Requests">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 c2bfcf65..a0a5b412 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">CreateChannel</tp:dbus-ref>. + namespace="im.telepathy.v1.Connection.Interface.Requests">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 7b192cc6..1081de2b 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.CreateChannel</tp:dbus-ref>, + <tp:dbus-ref namespace="im.telepathy.v1">Connection.Interface.Requests.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.CreateChannel</tp:dbus-ref>, + <tp:dbus-ref namespace="im.telepathy.v1">Connection.Interface.Requests.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 780ff5f1..ca7fe587 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">NewChannel</tp:dbus-ref> + namespace="imt1.Connection.Interface.Requests">NewChannel</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 4511bfd3..6cba94da 100644 --- a/spec/Client_Observer.xml +++ b/spec/Client_Observer.xml @@ -122,7 +122,7 @@ interested. The <tp:member-ref>ObserveChannel</tp:member-ref> method should be called by the channel dispatcher whenever the new channel in a <tp:dbus-ref - namespace="im.telepathy.v1.Connection">NewChannel</tp:dbus-ref> + namespace="im.telepathy.v1.Connection.Interface.Requests">NewChannel</tp:dbus-ref> signal matches 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 a channel in which the observer has registered an interest are announced in a <tp:dbus-ref - namespace="im.telepathy.v1.Connection">NewChannel</tp:dbus-ref> + namespace="im.telepathy.v1.Connection.Interface.Requests">NewChannel</tp:dbus-ref> signal.</p> <p>The observer MUST NOT return from this method call until it is ready diff --git a/spec/Connection.xml b/spec/Connection.xml index fdb43877..86b9a053 100644 --- a/spec/Connection.xml +++ b/spec/Connection.xml @@ -22,6 +22,8 @@ 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 @@ -66,6 +68,10 @@ 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, @@ -840,549 +846,6 @@ 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>NewChannel 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>NewChannel</tp:member-ref> until after this method - returns.</p> - - <tp:rationale> - <p>This allows the requester to alter its handling of - NewChannel 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>NewChannel</tp:member-ref> until after this method - returns. - - <tp:rationale> - <p>This allows the requester to alter its handling of - NewChannel 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="NewChannel" tp:name-for-bindings="New_Channel"> - <tp:added version="0.99.UNRELEASED"/> - - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>A new channel has been created.</p> - - <p>Unlike in some previous Telepathy versions, the connection manager - cannot emit a single signal for multiple channels. - For example, joining a MUC Tube in XMPP requires joining the - corresponding MUC (chatroom). Either the connection manager - should announce a new <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="Channel" type="o"> - <tp:docstring> - The object path of the channel. - </tp:docstring> - </arg> - - <arg name="Properties" type="a{sv}" - tp:type="Qualified_Property_Value_Map"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>The same properties of the channel that would appear in the - <tp:type>Channel_Details</tp:type> struct.</p> - </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>NewChannel</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 @@ -1464,9 +927,6 @@ 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 6a30c9d7..51400cbf 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" + namespace="im.telepathy.v1.Connection.Interface.Requests" >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 new file mode 100644 index 00000000..d18e5e33 --- /dev/null +++ b/spec/Connection_Interface_Requests.xml @@ -0,0 +1,595 @@ +<?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>NewChannel 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 NewChannel 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>NewChannel</tp:member-ref> until after this method + returns.</p> + + <tp:rationale> + <p>This allows the requester to alter its handling of + NewChannel by knowing whether the channel 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 NewChannel 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>NewChannel</tp:member-ref> until after this method + returns. + + <tp:rationale> + <p>This allows the requester to alter its handling of + NewChannel by knowing whether the channel 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="NewChannel" tp:name-for-bindings="New_Channel"> + <tp:added version="0.99.UNRELEASED"/> + + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>A new channel has been created.</p> + + <p>Unlike in some previous Telepathy versions, the connection manager + cannot emit a single signal for multiple channels. + For example, joining a MUC Tube in XMPP requires joining the + corresponding MUC (chatroom). Either the connection manager + should announce a new <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="Channel" type="o"> + <tp:docstring> + The object path of the channel. + </tp:docstring> + </arg> + + <arg name="Properties" type="a{sv}" + tp:type="Qualified_Property_Value_Map"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The same properties of the channel that would appear in the + <tp:type>Channel_Details</tp:type> struct.</p> + </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>NewChannel</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 d80074f1..a7293936 100644 --- a/spec/Protocol.xml +++ b/spec/Protocol.xml @@ -137,6 +137,10 @@ 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> @@ -149,7 +153,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" + namespace="im.telepathy.v1.Connection.Interface.Requests" >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 2312822e..f42770ff 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">RequestableChannelClasses</tp:dbus-ref>'s + namespace="im.telepathy.v1.Connection.Interface">Requests.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 e3926881..abd3c299 100644 --- a/spec/all.xml +++ b/spec/all.xml @@ -48,6 +48,8 @@ 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> |