[telepathy-mission-control/master] fd.o #20903: ContactCapabilities: update draft from telepathy-spec 0.17.26
Simon McVittie
simon.mcvittie at collabora.co.uk
Mon Jul 27 10:36:55 PDT 2009
This requires that Requestable_Channel_Class is added to all.xml as an
externally-defined type.
Incompatible changes in ContactCapabilities, none of which actually affect
MC:
* ContactCapabilitiesChanged acts on multiple contacts (but MC never
connects to this signal)
* Contact_Handle_Enhanced_Contact_Capability_Map renamed to
Contact_Capabilities_Map (but MC never mentions this type by name, and
the D-Bus signature is the same)
* Enhanced_Contact_Capability is replaced by the Requestable_Channel_Class
type first defined in Requests (but MC never mentions this type by
name, and the D-Bus signature is the same)
---
xml/Connection_Interface_Contact_Capabilities.xml | 90 ++++++++++-----------
xml/all.xml | 2 +
2 files changed, 44 insertions(+), 48 deletions(-)
diff --git a/xml/Connection_Interface_Contact_Capabilities.xml b/xml/Connection_Interface_Contact_Capabilities.xml
index 4d1d632..042b24b 100644
--- a/xml/Connection_Interface_Contact_Capabilities.xml
+++ b/xml/Connection_Interface_Contact_Capabilities.xml
@@ -18,13 +18,15 @@ Lesser General Public License for more details.</p>
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="org.freedesktop.Telepathy.Connection.Interface.ContactCapabilities.DRAFT">
+ <interface name="org.freedesktop.Telepathy.Connection.Interface.ContactCapabilities.DRAFT"
+ tp:causes-havoc="experimental">
<tp:requires interface="org.freedesktop.Telepathy.Connection"/>
+ <tp:added version="0.17.16">(as a draft)</tp:added>
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
- <p>An interface to get contact capabilities in order to know what channel
- classes may be created with a contact before the request is made to the
- connection object. Each capability represents a commitment by the
+ <p>Contact capabilities describe the channel classes which may be
+ created with a given contact in advance of attempting to create a
+ channel. Each capability represents a commitment by the
connection manager that it will ordinarily be able to create a channel
with a contact when given a request with the properties defined by the
channel class.</p>
@@ -35,9 +37,10 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
<p>This interface also enables user interfaces to notify the connection
manager what capabilities to advertise for the user to other contacts.
- This is done by using the SetSelfCapabilities method, and deals with
- channel properties values pertaining to them which are implemented by
- available client processes.</p>
+ This is done by using the
+ <tp:member-ref>SetSelfCapabilities</tp:member-ref> method, and deals
+ with channel property values pertaining to them which are implemented
+ by available client processes.</p>
</tp:docstring>
@@ -47,7 +50,9 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
tp:type="String_Variant_Map[]">
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
An array of channel classes to replace to the list of what the
- connection can handle
+ connection can handle. If you include optional properties, they
+ may not get advertised. The given properties are matched to the
+ mandatory properties.
</tp:docstring>
</arg>
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
@@ -60,9 +65,20 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
class are added.</p>
<p>Upon a successful invocation of this method, the
- ContactCapabilitiesChanged signal will be emitted for the user's own
- handle (as returned by GetSelfHandle) by the connection manager to
- indicate the changes that have been made.</p>
+ <tp:member-ref>ContactCapabilitiesChanged</tp:member-ref> signal
+ will only be emitted for the user's own
+ handle (as returned by GetSelfHandle) by the connection manager if, in
+ the given protocol, the given capabilities are distinct from the
+ previous state.</p>
+
+ <tp:rationale>
+ <p>The connection manager will essentially intersect the provided
+ capabilities and the channel classes it implements. Therefore,
+ certain properties which are never fixed for a channel class
+ (such as the target handle, or the Parameters property of a tube
+ channel) will almost certainly not be advertised.</p>
+ </tp:rationale>
+
</tp:docstring>
<tp:possible-errors>
<tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/>
@@ -85,7 +101,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
Now there is a fix, so we don't use the workaround anymore.
-->
<arg direction="out" type="a{ua(a{sv}as)}"
- tp:type="Contact_Handle_Enhanced_Contact_Capability_Map">
+ tp:type="Contact_Capabilities_Map" name="Contact_Capabilities">
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
An array of structures containing:
<ul>
@@ -109,49 +125,27 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
<signal name="ContactCapabilitiesChanged"
tp:name-for-bindings="Contact_Capabilities_Changed">
- <arg name="handle" type="u" tp:type="Contact_Handle">
- <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
- <p>A contact handle.</p>
- </tp:docstring>
- </arg>
- <arg name="caps" type="a(a{sv}as)"
- tp:type="Enhanced_Contact_Capability[]">
+ <arg name="caps" type="a{ua(a{sv}as)}"
+ tp:type="Contact_Capabilities_Map">
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
- All the capabilities of the contact
+ All the capabilities of the contacts
</tp:docstring>
</arg>
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
<p>Announce that there has been a change of capabilities on the
- given handle.</p>
- </tp:docstring>
- </signal>
+ given handles. A single signal can be emitted for several
+ contacts.</p>
+
+ <tp:rationale>
+ <p>The underlying protocol can get several contacts' capabilities at
+ the same time.</p>
+ </tp:rationale>
- <tp:struct name="Enhanced_Contact_Capability"
- array-name="Enhanced_Contact_Capability_List">
- <tp:docstring>
- A struct representing a capability posessed by a contact,
- as returned by GetContactCapabilities on the ContactCapabilities
- interface. The channel creation will succeed if the request contains
- all the Fixed_Properties will the values specified in this struct. The
- request can contain additional properties from Allowed_Properties. If
- the request contains a property which does not belong to
- Fixed_Properties nor to Allowed_Properties, the request will fail.
</tp:docstring>
- <tp:member type="a{sv}" tp:type="Channel_Class"
- name="Fixed_Properties">
- <tp:docstring>
- A dictionary mapping the channel properties to their values.
- </tp:docstring>
- </tp:member>
- <tp:member type="as" name="Allowed_Properties">
- <tp:docstring>
- An array of additional allowed properties.
- </tp:docstring>
- </tp:member>
- </tp:struct>
+ </signal>
- <tp:mapping name="Contact_Handle_Enhanced_Contact_Capability_Map"
- array-name="Contact_Handle_Enhanced_Contact_Capability_Map_List">
+ <tp:mapping name="Contact_Capabilities_Map"
+ array-name="Contact_Capabilities_Map_List">
<tp:docstring>A mapping from contact handle to their capabilities.
</tp:docstring>
<tp:member type="u" name="Key" tp:type="Contact_Handle">
@@ -160,7 +154,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
</tp:docstring>
</tp:member>
<tp:member type="a(a{sv}as)" name="Value"
- tp:type="Enhanced_Contact_Capability[]">
+ tp:type="Requestable_Channel_Class[]">
<tp:docstring>
The contact capabilities.
</tp:docstring>
diff --git a/xml/all.xml b/xml/all.xml
index e70c2db..96dc6c4 100644
--- a/xml/all.xml
+++ b/xml/all.xml
@@ -23,6 +23,8 @@
from="Telepathy specification (SimplePresence)"/>
<tp:external-type name="Conn_Mgr_Param_Flags" type="u"
from="Telepathy specification (ConnectionManager)"/>
+ <tp:external-type name="Requestable_Channel_Class" type="(a{sv}as)"
+ from="Telepathy specification (Requests)"/>
</tp:generic-types>
<xi:include href="generic-types.xml"/>
--
1.5.6.5
More information about the telepathy-commits
mailing list