diff options
author | Olli Salli <ollisal@gmail.com> | 2010-08-24 18:06:51 +0300 |
---|---|---|
committer | Olli Salli <ollisal@gmail.com> | 2010-08-24 18:06:51 +0300 |
commit | e7e20030d5db7ab4315394bb9871cc2bb916ae86 (patch) | |
tree | 2700dc0abb6da20d37192a314406b597033cf9d6 /spec | |
parent | 6f7402e4cd5ce8419b0fa692711518318bd414a9 (diff) |
Pull in XML from spec 0.19.11
Diffstat (limited to 'spec')
-rw-r--r-- | spec/Authentication_TLS_Certificate.xml | 304 | ||||
-rw-r--r-- | spec/Call_Content.xml | 13 | ||||
-rw-r--r-- | spec/Call_Stream.xml | 11 | ||||
-rw-r--r-- | spec/Channel_Interface_Call_State.xml | 14 | ||||
-rw-r--r-- | spec/Channel_Interface_Room.xml | 373 | ||||
-rw-r--r-- | spec/Channel_Type_Room_List.xml | 17 | ||||
-rw-r--r-- | spec/Channel_Type_Server_TLS_Connection.xml | 60 | ||||
-rw-r--r-- | spec/Channel_Type_Text.xml | 14 | ||||
-rw-r--r-- | spec/Connection.xml | 44 | ||||
-rw-r--r-- | spec/Connection_Interface_Client_Types.xml | 203 | ||||
-rw-r--r-- | spec/Protocol.xml | 65 | ||||
-rw-r--r-- | spec/all.xml | 16 | ||||
-rw-r--r-- | spec/errors.xml | 72 |
13 files changed, 1182 insertions, 24 deletions
diff --git a/spec/Authentication_TLS_Certificate.xml b/spec/Authentication_TLS_Certificate.xml new file mode 100644 index 00000000..709ea282 --- /dev/null +++ b/spec/Authentication_TLS_Certificate.xml @@ -0,0 +1,304 @@ +<?xml version="1.0" ?> +<node name="/Authentication_TLS_Certificate" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> + <tp:copyright>Copyright © 2010 Collabora Limited</tp:copyright> + <tp:license> + 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="org.freedesktop.Telepathy.Authentication.TLSCertificate.DRAFT" + tp:causes-havoc="experimental"> + <tp:added version="0.19.11">(draft 1)</tp:added> + + <tp:docstring> + This object represents a TLS certificate. + </tp:docstring> + + <tp:simple-type name="Certificate_Data" array-name="Certificate_Data_List" + type="ay"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The raw data contained in a TLS certificate.</p> + + <p>For X.509 certificates (<tp:member-ref>CertificateType</tp:member-ref> + = "x509"), this MUST be in DER format, as defined by the + <a href="http://www.itu.int/ITU-T/studygroups/com17/languages/X.690-0207.pdf">X.690</a> + ITU standard.</p> + + <p>For PGP certificates (<tp:member-ref>CertificateType</tp:member-ref> + = "pgp"), this MUST be a binary OpenPGP key as defined by section 11.1 + of <a href="http://www.rfc-editor.org/rfc/4880.txt">RFC 4880</a>.</p> + </tp:docstring> + </tp:simple-type> + + <tp:enum type="u" name="TLS_Certificate_State"> + <tp:docstring> + The possible states for a <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Authentication">TLSCertificate.DRAFT</tp:dbus-ref> + object. + </tp:docstring> + + <tp:enumvalue suffix="Pending" value="0"> + <tp:docstring> + The certificate is currently waiting to be accepted or rejected. + </tp:docstring> + </tp:enumvalue> + + <tp:enumvalue suffix="Accepted" value="1"> + <tp:docstring> + The certificate has been verified. + </tp:docstring> + </tp:enumvalue> + + <tp:enumvalue suffix="Rejected" value="2"> + <tp:docstring> + The certificate has been rejected. + </tp:docstring> + </tp:enumvalue> + </tp:enum> + + <tp:enum type="u" name="TLS_Certificate_Reject_Reason"> + <tp:docstring> + Possible reasons to reject a TLS certificate. + </tp:docstring> + + <tp:enumvalue suffix="Unknown" value="0"> + <tp:docstring> + The certificate has been rejected for another reason + not listed in this enumeration. + </tp:docstring> + </tp:enumvalue> + + <tp:enumvalue suffix="Untrusted" value="1"> + <tp:docstring> + The certificate is not trusted. + </tp:docstring> + </tp:enumvalue> + + <tp:enumvalue suffix="Expired" value="2"> + <tp:docstring> + The certificate is expired. + </tp:docstring> + </tp:enumvalue> + + <tp:enumvalue suffix="Not_Activated" value="3"> + <tp:docstring> + The certificate is not active yet. + </tp:docstring> + </tp:enumvalue> + + <tp:enumvalue suffix="Fingerprint_Mismatch" value="4"> + <tp:docstring> + The certificate provided does not have the expected + fingerprint. + </tp:docstring> + </tp:enumvalue> + + <tp:enumvalue suffix="Hostname_Mismatch" value="5"> + <tp:docstring> + The hostname certified does not match the provided one. + </tp:docstring> + </tp:enumvalue> + + <tp:enumvalue suffix="Self_Signed" value="6"> + <tp:docstring> + The certificate is self-signed. + </tp:docstring> + </tp:enumvalue> + + <tp:enumvalue suffix="Revoked" value="7"> + <tp:docstring> + The certificate has been revoked. + </tp:docstring> + </tp:enumvalue> + + <tp:enumvalue suffix="Insecure" value="8"> + <tp:docstring> + The certificate uses an insecure cipher algorithm, or is + cryptographically weak. + </tp:docstring> + </tp:enumvalue> + + <tp:enumvalue suffix="Limit_Exceeded" value="9"> + <tp:docstring> + The length in bytes of the certificate, or the depth of the + certificate chain exceed the limits imposed by the crypto + library. + </tp:docstring> + </tp:enumvalue> + </tp:enum> + + <property name="State" type="u" access="read" + tp:type="TLS_Certificate_State" + tp:name-for-bindings="State"> + <tp:docstring> + The current state of this certificate. + State change notifications happen by means of the + <tp:member-ref>Accepted</tp:member-ref> and + <tp:member-ref>Rejected</tp:member-ref> signals. + </tp:docstring> + </property> + + <property name="RejectError" type="s" access="read" + tp:type="DBus_Error_Name" + tp:name-for-bindings="Reject_Error"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>If the <tp:member-ref>State</tp:member-ref> is Rejected, + the reason why the certificate was rejected; this MAY correspond to + the <tp:member-ref>RejectReason</tp:member-ref>, or MAY be a more + specific D-Bus error name, perhaps implementation-specific.</p> + <p>If the <tp:member-ref>State</tp:member-ref> is not Rejected, + this property is not meaningful, and SHOULD be set to an empty + string.</p> + </tp:docstring> + </property> + + <property name="RejectDetails" type="a{sv}" access="read" + tp:type="String_Variant_Map" + tp:name-for-bindings="Reject_Details"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>If the <tp:member-ref>State</tp:member-ref> is Rejected, + additional information about why the certificate was rejected.</p> + <p>If the <tp:member-ref>State</tp:member-ref> is not Rejected, + this property is not meaningful and SHOULD be set to an empty + map.</p> + <p>The additional information MAY also include + one or more of the following well-known keys:</p> + <dl> + <dt>user-requested (b)</dt> + <dd>True if the error was due to an user-requested rejection of + the certificate; False if there was an unrecoverable error in the + verification process.</dd> + <dt>expected-hostname (s)</dt> + <dd>If the rejection reason is Hostname_Mismatch, the hostname that + the server certificate was expected to have.</dd> + <dt>certificate-hostname (s)</dt> + <dd>If the rejection reason is Hostname_Mismatch, the hostname of + the certificate that was presented. + <tp:rationale> + <p>For instance, if you try to connect to gmail.com but are presented + with a TLS certificate issued to evil.example.org, the error details + for Hostname_Mismatch MAY include:</p> + <pre> + { + 'expected-hostname': 'gmail.com', + 'certificate-hostname': 'evil.example.org', + } + </pre> + </tp:rationale> + </dd> + <dt>debug-message (s)</dt> + <dd>Debugging information on the error, corresponding to the + message part of a D-Bus error message, which SHOULD NOT be + displayed to users under normal circumstances</dd> + </dl> + </tp:docstring> + </property> + + <property name="RejectReason" type="u" access="read" + tp:type="TLS_Certificate_Reject_Reason" + tp:name-for-bindings="Reject_Reason"> + <tp:docstring> + If the <tp:member-ref>State</tp:member-ref> is Rejected, the + reason why the certificate was rejected. + <tp:rationale> + Clients that do not understand the <tp:member-ref>RejectError</tp:member-ref>, + which may be implementation-specific, can use this property to + classify rejection reasons into common categories. + </tp:rationale> + Otherwise, this property is not meaningful, and SHOULD be set to + Unknown. + </tp:docstring> + </property> + + <property name="CertificateType" type="s" access="read" + tp:name-for-bindings="Certificate_Type"> + <tp:docstring> + The type of this TLS certificate (e.g. 'x509' or 'pgp'). + <p>This property is immutable</p> + </tp:docstring> + </property> + + <property name="CertificateChainData" type="aay" access="read" + tp:type="Certificate_Data[]" tp:name-for-bindings="Certificate_Chain_Data"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>One or more TLS certificates forming a trust chain, each encoded as + specified by <tp:type>Certificate_Data</tp:type>.</p> + <p>The first certificate in the chain MUST be the server certificate, + followed by the issuer's certificate, followed by the issuer's issuer + and so on.</p> + </tp:docstring> + </property> + + <signal name="Accepted" + tp:name-for-bindings="Accepted"> + <tp:docstring> + The <tp:member-ref>State</tp:member-ref> of this certificate has changed to Accepted. + </tp:docstring> + </signal> + + <signal name="Rejected" + tp:name-for-bindings="Rejected"> + <tp:docstring> + The <tp:member-ref>State</tp:member-ref> of this certificate has changed to Rejected. + </tp:docstring> + <arg name="Reason" type="u" tp:type="TLS_Certificate_Reject_Reason"> + <tp:docstring> + The new value of <tp:member-ref>RejectReason</tp:member-ref>. + </tp:docstring> + </arg> + <arg name="Error" type="s" tp:type="DBus_Error_Name"> + <tp:docstring> + The new value of <tp:member-ref>RejectError</tp:member-ref>. + </tp:docstring> + </arg> + <arg name="Details" type="a{sv}" tp:type="String_Variant_Map"> + <tp:docstring> + The new value of <tp:member-ref>RejectDetails</tp:member-ref> + </tp:docstring> + </arg> + </signal> + + <method name="Accept" tp:name-for-bindings="Accept"> + <tp:docstring> + Accepts this certificate, i.e. marks it as verified. + </tp:docstring> + </method> + + <method name="Reject" tp:name-for-bindings="Reject"> + <tp:docstring> + Rejects this certificate. + </tp:docstring> + <arg direction="in" type="u" name="Reason" + tp:type="TLS_Certificate_Reject_Reason"> + <tp:docstring> + The new value of <tp:member-ref>RejectReason</tp:member-ref>. + </tp:docstring> + </arg> + <arg direction="in" type="s" name="Error" + tp:type="DBus_Error_Name"> + <tp:docstring> + The new value of <tp:member-ref>RejectError</tp:member-ref>. + </tp:docstring> + </arg> + <arg direction="in" type="a{sv}" name="Details" + tp:type="String_Variant_Map"> + <tp:docstring> + The new value of <tp:member-ref>RejectDetails</tp:member-ref>. + </tp:docstring> + </arg> + </method> + + </interface> +</node> +<!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/spec/Call_Content.xml b/spec/Call_Content.xml index 3e585b49..8df078b6 100644 --- a/spec/Call_Content.xml +++ b/spec/Call_Content.xml @@ -47,6 +47,19 @@ </tp:possible-errors> </method> + <property name="Interfaces" tp:name-for-bindings="Interfaces" + type="as" tp:type="DBus_Interface[]" access="read"> + <tp:added version="0.19.11"/> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Extra interfaces provided by this content, such as <tp:dbus-ref + namespace="ofdT.Call">Content.Interface.Media.DRAFT</tp:dbus-ref> or + <tp:dbus-ref + namespace="ofdT.Call">Content.Interface.Mute.DRAFT</tp:dbus-ref>. + This SHOULD NOT include the Content interface itself, and cannot + change once the content has been created.</p> + </tp:docstring> + </property> + <property name="Name" tp:name-for-bindings="Name" type="s" access="read"> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>The name of the content. diff --git a/spec/Call_Stream.xml b/spec/Call_Stream.xml index dc7d7849..0fbb9c8a 100644 --- a/spec/Call_Stream.xml +++ b/spec/Call_Stream.xml @@ -139,6 +139,17 @@ </tp:member> </tp:mapping> + <property name="Interfaces" tp:name-for-bindings="Interfaces" + type="as" tp:type="DBus_Interface[]" access="read"> + <tp:added version="0.19.11"/> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Extra interfaces provided by this stream, such as <tp:dbus-ref + namespace="ofdT.Call">Stream.Interface.Media.DRAFT</tp:dbus-ref>. + This SHOULD NOT include the Stream interface itself, and cannot + change once the stream has been created.</p> + </tp:docstring> + </property> + <property name="Senders" tp:name-for-bindings="Senders" type="a{uu}" access="read" tp:type="Contact_Sending_State_Map"> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> diff --git a/spec/Channel_Interface_Call_State.xml b/spec/Channel_Interface_Call_State.xml index b569a7ff..b0aea591 100644 --- a/spec/Channel_Interface_Call_State.xml +++ b/spec/Channel_Interface_Call_State.xml @@ -126,6 +126,20 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ outgoing call has reached a gateway, for instance. </tp:docstring> </tp:flag> + + <tp:flag suffix="Conference_Host" value="32"> + <tp:added version='0.19.11'/> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + This contact has merged this call into a conference. Note that GSM + provides a notification when the remote party merges a call into a + conference, but not when it is split out again; thus, this flag can + only indicate that the call has been part of a conference at some + point. If a GSM connection manager receives a notification that a + call has been merged into a conference a second time, it SHOULD + represent this by clearing and immediately re-setting this flag on + the remote contact. + </tp:docstring> + </tp:flag> </tp:flags> </interface> diff --git a/spec/Channel_Interface_Room.xml b/spec/Channel_Interface_Room.xml new file mode 100644 index 00000000..ffdf4a96 --- /dev/null +++ b/spec/Channel_Interface_Room.xml @@ -0,0 +1,373 @@ +<?xml version="1.0" ?> +<node name="/Channel_Interface_Room" + xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> + + <tp:copyright>Copyright © 2010 Collabora Ltd.</tp:copyright> + <tp:copyright>Copyright © 2010 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="org.freedesktop.Telepathy.Channel.Interface.Room.DRAFT" + tp:causes-havoc="experimental"> + <tp:requires interface="org.freedesktop.Telepathy.Channel"/> + <tp:added version="0.19.11">(draft 1)</tp:added> + + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Different IM protocols use a variety of ways to name chat rooms. The + simplest example is perhaps IRC, where chat rooms have short, + persistent, human-readable string names, and are generally global + across the network. Skype chat rooms have persistent string names, so + you can leave and re-join a room, but these names are opaque unique + identifiers. MSN chat rooms are unnamed, and you can only join one by + being invited. And XMPP wins the coveted “most complicated chat rooms” + prize: chat rooms may be hosted by different servers with different DNS + names; normally they have human-readable names, except that all MUCs on + Google Talk's conference server have UUIDs as names, and <a + href="http://xmpp.org/extensions/xep-0045.html#createroom-unique"><acronym + title="XMPP Extension Protocol">XEP</acronym>-0045 §10.1.4 + <q>Requesting a Unique Room Name</q></a> defines a protocol for + requesting a unique, opaque room name on the server.</p> + + <p>This interface intends to support and differentiate these mechanisms + more clearly than the <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel">TargetHandleType</tp:dbus-ref> + and <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel">TargetID</tp:dbus-ref> + properties can alone. It initially contains a pair of properties used + to represent the human-readable parts of a + <tp:type>Room_Handle</tp:type>'s identifier, if any. The above examples + for different protocols are represented as follows:</p> + + <ul> + <li>The IRC channel <tt>#telepathy</tt> on Freenode is represented by a + channel with properties + <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel">TargetHandleType</tp:dbus-ref> + = <code>Room</code>, + <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel">TargetID</tp:dbus-ref> + = <code>"#telepathy"</code>, + <tp:member-ref>RoomID</tp:member-ref> = <code>"#telepathy"</code>, + <tp:member-ref>Server</tp:member-ref> = <code>""</code>, indicating + that the room has a human-readable identifier, and is not confined to + a particular server on the network. + + <tp:rationale> + Actually, IRC supports creating “local” channels specific to the + server they are created on. These channels have identifiers + starting with <tt>&</tt> rather than <tt>#</tt>. These could be + represented by setting <tp:member-ref>Server</tp:member-ref> + appropriately. + </tp:rationale> + </li> + + <li>A Skype group chat with opaque identifier <tt>0xdeadbeef</tt> has + <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel">TargetHandleType</tp:dbus-ref> + = <code>Room</code>, + <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel">TargetID</tp:dbus-ref> + = <code>"0xdeadbeef"</code>, + <tp:member-ref>RoomID</tp:member-ref> = <code>""</code>, + <tp:member-ref>Server</tp:member-ref> = <code>""</code>, indicating + that the room has an identifier but no human-readable name. + </li> + + <li>An MSN group chat has + <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel">TargetHandleType</tp:dbus-ref> + = <code>None</code>, + <tp:member-ref>RoomID</tp:member-ref> = <code>""</code>, + <tp:member-ref>Server</tp:member-ref> = <code>""</code>, indicating + that the room has neither an identifier (so it cannot be re-joined + later) nor a human-readable name. + </li> + + <li>A standard Jabber multi-user chat + <tt>jdev@conference.jabber.org</tt> has + <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel">TargetHandleType</tp:dbus-ref> + = <code>Room</code>, + <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel">TargetID</tp:dbus-ref> + = <code>"jdev@conference.jabber.org"</code>, + <tp:member-ref>RoomID</tp:member-ref> = <code>"jdev"</code>, + <tp:member-ref>Server</tp:member-ref> = <code>"conference.jabber.org"</code>. + </li> + + <li>A Google Talk private MUC <tt>private-chat-11111x1x-11xx-111x-1111-111x1xx11x11@groupchat.google.com</tt> has + <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel">TargetHandleType</tp:dbus-ref> + = <code>Room</code>, + <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel">TargetID</tp:dbus-ref> + = <code>"private-chat-11111x1x-11xx-111x-1111-111x1xx11x11@groupchat.google.com"</code>, + <tp:member-ref>RoomID</tp:member-ref> = <code>""</code>, + <tp:member-ref>Server</tp:member-ref> = + <code>"groupchat.google.com"</code>, indicating that the room has a + persistent identifier, no human-readable name, and is hosted by a + particular server. + </li> + + <li>Similarly, a XEP-0045 §10.1.4 uniquely-named room + <tt>lrcgsnthzvwm@conference.jabber.org</tt> has + <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel">TargetHandleType</tp:dbus-ref> + = <code>Room</code>, + <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel">TargetID</tp:dbus-ref> + = <code>"lrcgsnthzvwm@conference.jabber.org"</code>, + <tp:member-ref>RoomID</tp:member-ref> = <code>""</code>, + <tp:member-ref>Server</tp:member-ref> = + <code>"conference.jabber.org"</code>, indicating that the room has a + persistent identifier, no human-readable name, and is hosted by a + particular server. + </li> + </ul> + + <h4>Requestable channel classes</h4> + + <p>If the connection supports joining text chat rooms by unique + identifier, like Skype, it should advertise a + <tp:type>Requestable_Channel_Class</tp:type> matching:</p> + + <blockquote> + <pre> +( Fixed = { ...<tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel" + >ChannelType</tp:dbus-ref>: ...<tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel.Type" + >Text</tp:dbus-ref>, + ...<tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel" + >TargetHandleType</tp:dbus-ref>: Room, + }, + Allowed = [ ...<tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel" + >TargetID</tp:dbus-ref>, + ...<tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel" + >TargetHandle</tp:dbus-ref>, + ] +)</pre></blockquote> + + <p>Channel requests must specify either <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel" + >TargetID</tp:dbus-ref> or <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel" + >TargetHandle</tp:dbus-ref>.</p> + + <p>If, like IRC, the room identifiers are also human-readable, the + RCCs should also include RoomID in <var>Allowed_Properties</var>:</p> + + <blockquote> + <pre> +( Fixed = { ...<tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel" + >ChannelType</tp:dbus-ref>: ...<tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel.Type" + >Text</tp:dbus-ref>, + ...<tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel" + >TargetHandleType</tp:dbus-ref>: Room, + }, + Allowed = [ ...<tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel" + >TargetID</tp:dbus-ref>, + ...<tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel" + >TargetHandle</tp:dbus-ref>, + ...<tp:member-ref>RoomID</tp:member-ref> + ] +), + +( Fixed = { ...<tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel" + >ChannelType</tp:dbus-ref>: ...<tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel.Type" + >Text</tp:dbus-ref> + }, + Allowed = [ ...<tp:member-ref>RoomID</tp:member-ref>, + ] +)</pre></blockquote> + + <p>Requests may specify the RoomID in place of + <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">TargetID</tp:dbus-ref> or + <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">TargetHandle</tp:dbus-ref> + . Note how <tp:member-ref>RoomID</tp:member-ref> appears + in <var>Allowed_Properties</var> of a different RCC because + when <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel" + >TargetHandleType</tp:dbus-ref> is omitted (or is None), both + <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel" + >TargetHandle</tp:dbus-ref> and + <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel" + >TargetID</tp:dbus-ref> must also be omitted. + <tp:member-ref>RoomID</tp:member-ref> is allowed in conjuction + with + <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">TargetID</tp:dbus-ref> or + <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">TargetHandle</tp:dbus-ref> + in some situations, as explained below in the <em>Requesting room + channels</em> section. + </p> + + <p>If rooms may be on different servers, <tp:member-ref>Server</tp:member-ref> + should also be included in the allowed properties, but + CMs MUST use a reasonable default + <tp:member-ref>Server</tp:member-ref> if not explicitly + specified in a channel request. The CM's default server MAY + be configurable by a connection parameter specified on a + <tp:dbus-ref namespace="org.freedesktop.Telepathy.ConnectionManager" + >RequestConnection</tp:dbus-ref> call, similarly to how the + fallback conference server is specified on jabber connections in + gabble.</p> + + <p>If the protocol supports unnamed rooms, <tp:member-ref>RoomID</tp:member-ref> + should be fixed to the empty string, and + <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">TargetHandleType</tp:dbus-ref> + should be None:</p> + + <blockquote> + <pre> +( Fixed = { ...<tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel" + >ChannelType</tp:dbus-ref>: ...<tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel.Type" + >Text</tp:dbus-ref>, + ...<tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel" + >TargetHandleType</tp:dbus-ref>: None, + ...<tp:member-ref>RoomID</tp:member-ref>: "", + }, + Allowed = [ ] +)</pre></blockquote> + + <h4>Requesting room channels</h4> + + <p>When explicitly joining a room, the CM cannot know whether the room + ID is unique or not. As a result, if this is the case, adding an + empty string <tp:member-ref>RoomID</tp:member-ref> into the channel + request will ensure the CM knows. For example:</p> + + <blockquote> + <pre> +{ ...<tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">ChannelType</tp:dbus-ref>: ...<tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel.Type">Text</tp:dbus-ref>, + ...<tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">TargetHandleType</tp:dbus-ref>: Room, + ...<tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">TargetID</tp:dbus-ref>: "qwerasdfzxcv@conference.jabber.org", + ...<tp:member-ref>RoomID</tp:member-ref>: "" +}</pre></blockquote> + + <p>If <tp:member-ref>RoomID</tp:member-ref> features in + <var>Allowed_Properties</var> then the only value allowed in conjunction + with <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">TargetID</tp:dbus-ref> + or <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">TargetHandle</tp:dbus-ref> + is the empty string. Requests with conflicting + <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">TargetID</tp:dbus-ref> + and <tp:member-ref>RoomID</tp:member-ref> properties + will fail with InvalidArgument.</p> + + <p>To create a XEP-0045 §10.1.4 uniquely-named room channel + on the conference.jabber.org server, then the following channel + request should be made:</p> + + <blockquote> + <pre> +{ ...<tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">ChannelType</tp:dbus-ref>: ...<tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel.Type">Text</tp:dbus-ref>, + ...<tp:member-ref>RoomID</tp:member-ref>: "" + ...<tp:member-ref>Server</tp:member-ref>: "conference.jabber.org" +}</pre> + </blockquote> + + <p>If everything is successful, then when the channel request is + satisfied, a new channel will appear with the following properties:</p> + + <blockquote> + <pre> +{ ...<tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">ChannelType</tp:dbus-ref>: ...<tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel.Type">Text</tp:dbus-ref>, + ...<tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">TargetHandleType</tp:dbus-ref>: Room, + ...<tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">TargetID</tp:dbus-ref>: "kajsdhkajshdfjkshdfjkhs@conference.jabber.org", + ...<tp:member-ref>RoomID</tp:member-ref>: "" + ...<tp:member-ref>Server</tp:member-ref>: "conference.jabber.org" +}</pre> + </blockquote> + + <p>The CM will have received the unique room name (kajsdhkajshdfjkshdfjkhs) + and then created a room with such a name on the said server. The empty + <tp:member-ref>RoomID</tp:member-ref> property shows that the room name + is not human-readable.</p> + + </tp:docstring> + + <property name="RoomID" tp:name-for-bindings="Room_ID" type="s" + access="read"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The human-readable identifier of a chat room. Note that if + non-empty, this property (and perhaps also + <tp:member-ref>Server</tp:member-ref>) should be sufficient in + a channel request to join the room. XMPP MUCs have a room name + concept which is more like a topic, except more + persistent. This D-Bus property is <strong>not</strong> this + XMPP room name, but the bit before the @ in the room jid.</p> + + <p>This property cannot change during the lifetime of the channel. It + should appear in the <var>Allowed_Properties</var> of a + <tp:type>Requestable_Channel_Class</tp:type> for the connection if + rooms on this connection have human-readable names, and can be joined + by name.</p> + </tp:docstring> + </property> + + <property name="Server" tp:name-for-bindings="Server" type="s" + access="read"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>For protocols with a concept of chatrooms on multiple servers with + different DNS names (like XMPP), the DNS name of the server hosting + this channel (for example, <tt>"conference.jabber.org"</tt> or + <tt>"groupchat.google.com"</tt>). For other protocols, the empty + string.</p> + + <p>This property cannot change during the lifetime of the channel. It + should appear in the <var>Allowed_Properties</var> of a + <tp:type>Requestable_Channel_Class</tp:type> for the connection if + and only if non-empty values are supported.</p> + </tp:docstring> + </property> + + <tp:struct name="Room_Subject"> + <tp:docstring> + A struct representing the subject of a room channel. + </tp:docstring> + <tp:member type="s" name="Subject"> + <tp:docstring> + A human-readable description of the current subject of + conversation in the channel, similar to /topic in IRC. + </tp:docstring> + </tp:member> + <tp:member type="s" name="Actor"> + <tp:docstring> + A normalized contact ID representing who last modified the + subject, or the empty string if it is not known. + </tp:docstring> + </tp:member> + <tp:member type="x" tp:type="Unix_Timestamp64" name="Timestamp"> + <tp:docstring> + A unix timestamp indicating when the subject was last modified. + </tp:docstring> + </tp:member> + </tp:struct> + + <property name="Subject" tp:name-for-bindings="Subject" + type="(ssx)" tp:type="Room_Subject" access="read"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The subject on the room such as the topic in an IRC channel, + or the room name in XMPP MUCs. In protocols which do not support + subjects (like MSN), this property should be ("", "", 0).</p> + + <tp:rationale>This property replaces the subject, subject-contact, and + subject-timestamp Telepathy properties of Text channels, as Telepathy + properties are soon to be deprecated completely.</tp:rationale> + + <p>This property may change during the lifetime of the channel and + MUST not be included in a channel request.</p> + </tp:docstring> + </property> + + </interface> +</node> +<!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/spec/Channel_Type_Room_List.xml b/spec/Channel_Type_Room_List.xml index 6d6ce310..98f74582 100644 --- a/spec/Channel_Type_Room_List.xml +++ b/spec/Channel_Type_Room_List.xml @@ -84,7 +84,10 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ <dd>A description of the room's overall purpose</dd> <dt>subject (s)</dt> - <dd>The current subject of conversation in the room</dd> + <dd>The current subject of conversation in the room (as would + be returned by getting the string part of the <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel.Interface.Room.DRAFT" + >Subject</tp:dbus-ref> property)</dd> <dt>members (u)</dt> <dd>The number of members in the room</dd> @@ -94,6 +97,18 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ <dt>invite-only (b)</dt> <dd>True if you cannot join the room, but must be invited</dd> + + <dt>room-id (s)</dt> + <dd>The human-readable identifier of a chat room (as would be + returned by getting the <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel.Interface.Room.DRAFT" + >RoomID</tp:dbus-ref> property)</dd> + + <dt>server (s)</dt> + <dd>The DNS name of the server hosting these channels (as would be + returned by getting the <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel.Interface.Room.DRAFT" + >Server</tp:dbus-ref> property)</dd> </dl> </tp:docstring> </signal> diff --git a/spec/Channel_Type_Server_TLS_Connection.xml b/spec/Channel_Type_Server_TLS_Connection.xml new file mode 100644 index 00000000..1d705c55 --- /dev/null +++ b/spec/Channel_Type_Server_TLS_Connection.xml @@ -0,0 +1,60 @@ +<?xml version="1.0" ?> +<node name="/Channel_Type_Server_TLS_Connection" + xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> + <tp:copyright> Copyright © 2010 Collabora Limited </tp:copyright> + <tp:license> + 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="org.freedesktop.Telepathy.Channel.Type.ServerTLSConnection.DRAFT" + tp:causes-havoc="experimental"> + <tp:added version="0.19.11">(draft 1)</tp:added> + + <tp:requires interface="org.freedesktop.Telepathy.Channel"/> + + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>A channel type that carries a TLS certificate between a server + and a client connecting to it.</p> + <p>Channels of this kind always have <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel">Requested</tp:dbus-ref> = False, + <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">TargetHandleType</tp:dbus-ref> + = None and <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">TargetHandle</tp:dbus-ref> + = 0, and cannot be requested with methods such as <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Connection.Interface.Requests">CreateChannel</tp:dbus-ref>. + Also, they SHOULD be dispatched while the + <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection</tp:dbus-ref> + owning them is in the CONNECTING state.</p> + <p>In this case, handlers SHOULD accept or reject the certificate, using + the relevant methods on the provided object, or MAY just <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel">Close</tp:dbus-ref> the channel before doing so, to fall + back to a non-interactive verification process done inside the CM.</p> + <p>For example, channels of this kind can pop up while a client is + connecting to an XMPP server.</p> + </tp:docstring> + + <property name="ServerCertificate" type="o" access="read" + tp:name-for-bindings="ServerCertificate"> + <tp:docstring> + <p>A <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Authentication">TLSCertificate.DRAFT</tp:dbus-ref> + containing the certificate chain as sent by the server, + and other relevant information.</p> + <p>This property is immutable.</p> + </tp:docstring> + </property> + + </interface> +</node> +<!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/spec/Channel_Type_Text.xml b/spec/Channel_Type_Text.xml index e3cd6b98..9cbfea21 100644 --- a/spec/Channel_Type_Text.xml +++ b/spec/Channel_Type_Text.xml @@ -454,18 +454,28 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ <tp:property name="subject" type="s"> <tp:docstring> A human-readable description of the current subject of conversation in - the channel, similar to /topic in IRC. + the channel, similar to /topic in IRC. This is equivalent to the + <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel.Interface.Room.DRAFT" + >Subject</tp:dbus-ref> property in the Room interface which will replace + this Telepathy property. </tp:docstring> </tp:property> <tp:property name="subject-contact" type="u" tp:type="Contact_Handle"> <tp:docstring> A contact handle representing who last modified the subject, or 0 - if it isn't known. + if it isn't known. This is equivalent to the + <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel.Interface.Room.DRAFT" + >Subject</tp:dbus-ref> property in the Room interface which will replace + this Telepathy property. </tp:docstring> </tp:property> <tp:property name="subject-timestamp" type="u" tp:type="Unix_Timestamp"> <tp:docstring> A unix timestamp indicating when the subject was last modified. + This is equivalent to the + <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel.Interface.Room.DRAFT" + >Subject</tp:dbus-ref> property in the Room interface which will replace + this Telepathy property. </tp:docstring> </tp:property> diff --git a/spec/Connection.xml b/spec/Connection.xml index 3109670a..6587bb2d 100644 --- a/spec/Connection.xml +++ b/spec/Connection.xml @@ -896,7 +896,7 @@ USA.</p> <p>The server's SSL certificate is self-signed.</p> <p>When disconnected for this reason, the equivalent D-Bus error is - <code>org.freedesktop.Telepathy.Error.Cert.HostnameMismatch</code>. + <code>org.freedesktop.Telepathy.Error.Cert.SelfSigned</code>. </p> </tp:docstring> </tp:enumvalue> @@ -911,6 +911,39 @@ USA.</p> </p> </tp:docstring> </tp:enumvalue> + + <tp:enumvalue suffix="Cert_Revoked" value="14"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The server's SSL certificate has been revoked.</p> + + <p>When disconnected for this reason, the equivalent D-Bus error is + <code>org.freedesktop.Telepathy.Error.Cert.Revoked</code>. + </p> + </tp:docstring> + </tp:enumvalue> + + <tp:enumvalue suffix="Cert_Insecure" value="15"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The server's SSL certificate uses an insecure algorithm, + or is cryptographically weak.</p> + + <p>When disconnected for this reason, the equivalent D-Bus error is + <code>org.freedesktop.Telepathy.Error.Cert.Insecure</code>. + </p> + </tp:docstring> + </tp:enumvalue> + + <tp:enumvalue suffix="Cert_Limit_Exceeded" value="16"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The length in bytes of the server certificate, or the depth of the + sever certificate chain exceed the limits imposed by the crypto + library.</p> + + <p>When disconnected for this reason, the equivalent D-Bus error is + <code>org.freedesktop.Telepathy.Error.Cert.LimitExceeded</code> + </p> + </tp:docstring> + </tp:enumvalue> </tp:enum> <signal name="ConnectionError" tp:name-for-bindings="Connection_Error"> @@ -977,13 +1010,12 @@ USA.</p> <dd>Debugging information on the change, corresponding to the message part of a D-Bus error message, which SHOULD NOT be displayed to users under normal circumstances</dd> + <dt>expected-hostname (s), certificate-hostname (s)</dt> + <dd>The same details defined in <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Authentication">TLSCertificate.DRAFT.RejectDetails</tp:dbus-ref> + </dd> </dl> - <tp:rationale> - <p>This argument allows for future extensions. For instance, - if indicating DNS lookup failure, we could define a key - that indicates the hostname that could not be found.</p> - </tp:rationale> </tp:docstring> </arg> diff --git a/spec/Connection_Interface_Client_Types.xml b/spec/Connection_Interface_Client_Types.xml new file mode 100644 index 00000000..879095e7 --- /dev/null +++ b/spec/Connection_Interface_Client_Types.xml @@ -0,0 +1,203 @@ +<?xml version="1.0" ?> +<node name="/Connection_Interface_Client_Types" + xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> + <tp:copyright>Copyright (C) 2010 Collabora Ltd.</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="org.freedesktop.Telepathy.Connection.Interface.ClientTypes.DRAFT" + tp:causes-havoc="experimental"> + <tp:added version="0.19.11">(as draft)</tp:added> + <tp:requires interface="org.freedesktop.Telepathy.Connection"/> + + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>An interface on connections to support protocols which allows users to + subscribe to the client types of their contacts.</p> + + <p>One can connect to instant messaging networks on a huge variety of + devices, from PCs, to phones to consoles. It can be useful for users + to know what kind of device a contact is using so that he or she + can decide not to send that big file or start a video chat. This + interface exposes exactly this information for clients to display.</p> + + <p>The client types are represented in strings, using the values + <a href="http://xmpp.org/registrar/disco-categories.html#client"> + documented by the XMPP registrar</a> with some additional types + added for other protocols. A contact can set one or more client types + so this interface returns a list of strings to denote client types + for a contact. The well-known client types to be used are:</p> + + <ul> + <li>bot</li> + <li>console (minimal non-GUI client used on dumb terminals or + text-only screens, <strong>not</strong> a games console)</li> + <li>handheld</li> + <li>pc</li> + <li>phone</li> + <li>web</li> + <li>sms (the client is not actually an instant messaging client + but all messages sent to this contact will be delivered as SMSs)</li> + <li>game (a gaming device)</li> + </ul> + + <p>If the empty list is given as the client types, this means that + details about the contact's client types are unknown. If there are + multiple resources of a contact online at one point in time, the + client types of the most available resource will be returned. In + other words, the client types are the types of the client whose + SimplePresence we see. For example, if a contact has two + resources:</p> + + <ul> + <li>one his phone, with presence "available", and</li> + <li>one his pc, with presence "busy",</li> + </ul> + + <p>then the methods in this interface will return an array (with + one element: "phone") as the client types as that is the more + available resource. If some time later his phone's presence + moves to "away", then the + <tp:member-ref>ClientTypesUpdated</tp:member-ref> signal will + notify that his client type have changed from "phone" to "pc", + because "busy" is a more available presence than "away".</p> + + </tp:docstring> + + <tp:mapping name="Contact_Client_Types"> + <tp:docstring> + A mapping from contact handle to client types. + </tp:docstring> + <tp:member type="u" tp:type="Contact_Handle" name="Contact"> + <tp:docstring> + A contact. + </tp:docstring> + </tp:member> + <tp:member type="as" name="Client_Types"> + <tp:docstring> + The contact's client types as documented earlier in this interface. + </tp:docstring> + </tp:member> + </tp:mapping> + + <method name="GetClientTypes" tp:name-for-bindings="Get_Client_Types"> + <tp:docstring> + Return the client types of the given contacts, if they are + already known. If any of the given contacts' client types are + not known, request their current client types, but return + immediately without waiting for a reply; if a reply with a + non-empty client type array is later received for those + contacts, the + <tp:member-ref>ClientTypesUpdated</tp:member-ref> signal will + be emitted for them. + + <tp:rationale> + This method is appropriate for "lazy" client type finding, for instance + displaying the client types (if available) of everyone in your contact + list. + </tp:rationale> + </tp:docstring> + + <arg direction="in" name="Contacts" type="au" tp:type="Contact_Handle[]"> + <tp:docstring> + The contacts whose client types should be returned or signalled. + </tp:docstring> + </arg> + + <arg direction="out" name="Client_Types" type="a{uas}" + tp:type="Contact_Client_Types"> + <tp:docstring> + The contacts' client types, if already known. Contacts whose client + types are not already known are omitted from the mapping; contacts known + to have no client type information appear in the mapping with an empty + list. + </tp:docstring> + </arg> + + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> + <tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle"/> + </tp:possible-errors> + </method> + + <method name="RequestClientTypes" tp:name-for-bindings="Request_Client_Types"> + <tp:docstring> + Return the current client types of the given contact. If necessary, make + a request to the server for up-to-date information, and wait for a + reply. + + <tp:rationale> + This method is appropriate for use in a "Contact Information..." + dialog; it can be used to show progress information (while waiting + for the method to return), and can distinguish between various error + conditions. + </tp:rationale> + </tp:docstring> + + <arg direction="in" name="Contact" type="u" tp:type="Contact_Handle"> + <tp:docstring> + The contact whose client types should be returned. + </tp:docstring> + </arg> + + <arg direction="out" name="Client_Types" type="as"> + <tp:docstring> + The contact's client types. It MAY be empty, indicating that no client + type information was found. + </tp:docstring> + </arg> + + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> + <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/> + <tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle"/> + <tp:error name="org.freedesktop.Telepathy.Error.PermissionDenied"> + <tp:docstring> + The requested contact does not allow the local user to see their + client type information. + </tp:docstring> + </tp:error> + </tp:possible-errors> + </method> + + <signal name="ClientTypesUpdated" tp:name-for-bindings="Client_Types_Updated"> + <tp:docstring> + Emitted when a contact's client types change or become known. + </tp:docstring> + + <arg name="Contact" type="u" tp:type="Contact_Handle"> + <tp:docstring> + The contact. + </tp:docstring> + </arg> + <arg name="Client_Types" type="as"> + <tp:docstring> + The contact's client types, or an empty list to indicate that nothing + is known about the contact's client types. + </tp:docstring> + </arg> + </signal> + + <tp:contact-attribute name="client-types" type="as"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The same mapping that would be returned by + <tp:member-ref>GetClientTypes</tp:member-ref> for this contact. + Omitted from the result if the contact's client types are not + known.</p> + </tp:docstring> + </tp:contact-attribute> + + </interface> +</node> +<!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/spec/Protocol.xml b/spec/Protocol.xml index 91c350f5..50562c9b 100644 --- a/spec/Protocol.xml +++ b/spec/Protocol.xml @@ -45,6 +45,32 @@ <code>/org/freedesktop/Telepathy/ConnectionManager/salut/local_xmpp</code>, respectively.</p> </tp:rationale> + + <p>If the ConnectionManager has a <tt>.manager</tt> file, each + Protocol's immutable properties must be represented in that file; + the representation is described as part of the documentation for + each property. For instance, a very simple ConnectionManager with one + Protocol might be represented like this:</p> + +<pre> +[ConnectionManager] +Interfaces= + +[Protocol example] +Interfaces= +ConnectionInterfaces=org.freedesktop.Telepathy.Connection.Interface.Requests; +param-account=s required +param-password=s required secret +RequestableChannelClasses=text; +VCardField=x-example +EnglishName=Example +Icon=im-example + +[text] +org.freedesktop.Telepathy.Channel.ChannelType s=org.freedesktop.Telepathy.Channel.Type.Text +org.freedesktop.Telepathy.Channel.TargetHandleType u=1 +allowed=org.freedesktop.Telepathy.Channel.TargetHandle;org.freedesktop.Telepathy.Channel.TargetID; +</pre> </tp:docstring> <property name="Interfaces" tp:name-for-bindings="Interfaces" @@ -136,6 +162,12 @@ of those strings is the name of a group in the <code>.manager</code> file which represents a channel class.</p> + <p>The names of the groups representing channel classes are not + significant, and MUST NOT be interpreted. When writing + <tt>.manager</tt> files, authors MAY choose mnemonic group names, + generate group names mechanically (e.g. with an incrementing + integer), or use some combination of these.</p> + <p>Each group representing a channel class has a key <code>allowed</code> which is a list of D-Bus property names representing allowed parameters. Any other keys that do not contain @@ -152,17 +184,23 @@ <code>.manager</code> files.</p> <p>For instance, this <code>.manager</code> file could represent - a simple Text-only connection manager:</p> + a connection manager that supports 1-1 Text messages and + StreamedMedia audio calls:</p> <pre>[Protocol jabber] param-account=s required param-password=s required -RequestableChannelClasses=text +RequestableChannelClasses=rcc0;rcc1; -[text] +[rcc0] org.freedesktop.Telepathy.Channel.ChannelType s=org.freedesktop.Telepathy.Channel.Type.Text org.freedesktop.Telepathy.Channel.TargetHandleType u=1 allowed=org.freedesktop.Telepathy.Channel.TargetHandle;org.freedesktop.Telepathy.Channel.TargetID; + +[rcc1] +org.freedesktop.Telepathy.Channel.ChannelType s=org.freedesktop.Telepathy.Channel.Type.StreamedMedia +org.freedesktop.Telepathy.Channel.TargetHandleType u=1 +allowed=org.freedesktop.Telepathy.Channel.TargetHandle;org.freedesktop.Telepathy.Channel.TargetID;org.freedesktop.Telepathy.Channel.Type.StreamedMedia.InitialAudio; </pre> </tp:docstring> </property> @@ -196,6 +234,13 @@ allowed=org.freedesktop.Telepathy.Channel.TargetHandle;org.freedesktop.Telepathy arbitrary handles/identifiers as vCard fields is a topic for future work.</p> </tp:rationale> + + <p>Connection managers with a <code>.manager</code> file + MUST cache this property in the protocol's section of the + <code>.manager</code> file if it is non-empty, using the key + <code>VCardField</code>. The corresponding value + is a string, following the syntax of the "localestring" type from + the Desktop Entry Specification.</p> </tp:docstring> </property> @@ -223,6 +268,13 @@ allowed=org.freedesktop.Telepathy.Channel.TargetHandle;org.freedesktop.Telepathy <p>If this property's value is empty, clients MAY fall back to using the Telepathy <tp:type>Protocol</tp:type> name, possibly with its capitalization adjusted.</p> + + <p>Connection managers with a <code>.manager</code> file + MUST cache this property in the protocol's section of the + <code>.manager</code> file if it is non-empty, using the key + <code>EnglishName</code>. The corresponding value + is a string, following the syntax of the "localestring" type from + the Desktop Entry Specification.</p> </tp:docstring> </property> @@ -243,6 +295,13 @@ allowed=org.freedesktop.Telepathy.Channel.TargetHandle;org.freedesktop.Telepathy <p>If this property's value is empty, clients MAY fall back to generating a name based on the <tp:type>Protocol</tp:type> name.</p> + + <p>Connection managers with a <code>.manager</code> file + MUST cache this property in the protocol's section of the + <code>.manager</code> file if it is non-empty, using the key + <code>Icon</code>. The corresponding value + is a string, following the syntax of the "localestring" type from + the Desktop Entry Specification.</p> </tp:docstring> </property> diff --git a/spec/all.xml b/spec/all.xml index 9140a1f3..0dd70c6f 100644 --- a/spec/all.xml +++ b/spec/all.xml @@ -3,7 +3,7 @@ xmlns:xi="http://www.w3.org/2001/XInclude"> <tp:title>Telepathy D-Bus Interface Specification</tp:title> -<tp:version>0.19.10</tp:version> +<tp:version>0.19.11.1</tp:version> <tp:copyright>Copyright © 2005-2010 Collabora Limited</tp:copyright> <tp:copyright>Copyright © 2005-2010 Nokia Corporation</tp:copyright> @@ -50,6 +50,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ <xi:include href="Connection_Interface_Balance.xml"/> <xi:include href="Connection_Interface_Capabilities.xml"/> <xi:include href="Connection_Interface_Cellular.xml"/> + <xi:include href="Connection_Interface_Client_Types.xml"/> <xi:include href="Connection_Interface_Contact_Capabilities.xml"/> <xi:include href="Connection_Interface_Contact_Groups.xml"/> <xi:include href="Connection_Interface_Contact_Info.xml"/> @@ -95,6 +96,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ <xi:include href="Channel_Type_DBus_Tube.xml"/> <xi:include href="Channel_Type_File_Transfer.xml"/> <xi:include href="Channel_Type_Room_List.xml"/> + <xi:include href="Channel_Type_Server_TLS_Connection.xml"/> <xi:include href="Channel_Type_Stream_Tube.xml"/> <xi:include href="Channel_Type_Streamed_Media.xml"/> <xi:include href="Channel_Type_Text.xml"/> @@ -121,12 +123,24 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ <xi:include href="Channel_Interface_Mergeable_Conference.xml"/> <xi:include href="Channel_Interface_Messages.xml"/> <xi:include href="Channel_Interface_Password.xml"/> + <xi:include href="Channel_Interface_Room.xml"/> <xi:include href="Channel_Interface_Service_Point.xml"/> <xi:include href="Channel_Interface_Splittable.xml"/> <xi:include href="Channel_Interface_Tube.xml"/> </tp:section> </tp:section> + <tp:section name="Authentication Objects"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p> + A set of objects to be used for authentication purposes, such + as TLS certificates or handshakes for negotiating end-to-end + security. + </p> + </tp:docstring> + <xi:include href="Authentication_TLS_Certificate.xml"/> + </tp:section> + <tp:section name="Media"> <xi:include href="Media_Session_Handler.xml"/> <xi:include href="Media_Stream_Handler.xml"/> diff --git a/spec/errors.xml b/spec/errors.xml index 60a93c95..e14dacbe 100644 --- a/spec/errors.xml +++ b/spec/errors.xml @@ -182,7 +182,8 @@ represent a self-signed certificate: see the Self Signed error for that. <tp:rationale> This corresponds to Cert_Untrusted in the - <tp:type>Connection_Status_Reason</tp:type> enum, with a clarification + <tp:type>Connection_Status_Reason</tp:type> enum and to Untrusted in the + <tp:type>TLS_Certificate_Reject_Reason</tp:type> enum, with a clarification to avoid ambiguity. </tp:rationale> </tp:docstring> @@ -193,7 +194,8 @@ Raised if the server provided an expired SSL/TLS certificate. <tp:rationale> This corresponds to Cert_Expired in the - <tp:type>Connection_Status_Reason</tp:type> enum. + <tp:type>Connection_Status_Reason</tp:type> enum and to Expired in + the <tp:type>TLS_Certificate_Reject_Reason</tp:type> enum. </tp:rationale> </tp:docstring> </tp:error> @@ -204,7 +206,8 @@ valid at some point in the future. <tp:rationale> This corresponds to Cert_Not_Activated in the - <tp:type>Connection_Status_Reason</tp:type> enum. + <tp:type>Connection_Status_Reason</tp:type> enum and to + Not_Activated in the <tp:type>TLS_Certificate_Reject_Reason</tp:type> enum. </tp:rationale> </tp:docstring> </tp:error> @@ -215,18 +218,23 @@ the expected fingerprint. <tp:rationale> This corresponds to Cert_Fingerprint_Mismatch in the - <tp:type>Connection_Status_Reason</tp:type> enum. + <tp:type>Connection_Status_Reason</tp:type> enum and to + Fingerprint_Mismatch in the <tp:type>TLS_Certificate_Reject_Reason</tp:type> enum. </tp:rationale> </tp:docstring> </tp:error> <tp:error name="Cert.Hostname Mismatch"> - <tp:docstring> - Raised if the server provided an SSL/TLS certificate that did not match - its hostname. + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Raised if the server provided an SSL/TLS certificate that did not match + its hostname.</p> + <p>You MAY be able to get more details about the expected and certified + hostnames by looking up the 'expected-hostname' and 'certificate-hostname' + keys in the details map that came together with this error.</p> <tp:rationale> This corresponds to Cert_Hostname_Mismatch in the - <tp:type>Connection_Status_Reason</tp:type> enum. + <tp:type>Connection_Status_Reason</tp:type> enum and to Hostname_Mismatch + in the <tp:type>TLS_Certificate_Reject_Reason</tp:type> enum. </tp:rationale> </tp:docstring> </tp:error> @@ -236,19 +244,61 @@ Raised if the server provided an SSL/TLS certificate that is self-signed and untrusted. <tp:rationale> - This corresponds to Cert_Hostname_Mismatch in the - <tp:type>Connection_Status_Reason</tp:type> enum. + This corresponds to Cert_Self_Signed in the + <tp:type>Connection_Status_Reason</tp:type> enum and to Self_Signed + in the <tp:type>TLS_Certificate_Reject_Reason</tp:type> enum. + </tp:rationale> + </tp:docstring> + </tp:error> + + <tp:error name="Cert.Revoked"> + <tp:docstring> + Raised if the server provided an SSL/TLS certificate that has been + revoked. + <tp:rationale> + This corresponds to Cert_Revoked in the + <tp:type>Connection_Status_Reason</tp:type> enum and to Revoked + in the <tp:type>TLS_Certificate_Reject_Reason</tp:type> enum. + </tp:rationale> + </tp:docstring> + </tp:error> + + <tp:error name="Cert.Insecure"> + <tp:added version="0.19.11"/> + <tp:docstring> + Raised if the server provided an SSL/TLS certificate that uses an + insecure cipher algorithm or is cryptographically weak. + <tp:rationale> + This corresponds to Cert_Insecure in the + <tp:type>Connection_Status_Reason</tp:type> enum and to Insecure + in the <tp:type>TLS_Certificate_Reject_Reason</tp:type> enum. </tp:rationale> </tp:docstring> </tp:error> <tp:error name="Cert.Invalid"> + <tp:added version="0.19.11"/> <tp:docstring> Raised if the server provided an SSL/TLS certificate that is unacceptable in some way that does not have a more specific error. <tp:rationale> This corresponds to Cert_Other_Error in the - <tp:type>Connection_Status_Reason</tp:type> enum. + <tp:type>Connection_Status_Reason</tp:type> enum and to Unknown + in the <tp:type>TLS_Certificate_Reject_Reason</tp:type> enum. + </tp:rationale> + </tp:docstring> + </tp:error> + + <tp:error name="Cert.Limit Exceeded"> + <tp:added version="0.19.11"/> + <tp:docstring> + Raised if the length in bytes of the server certificate, or the depth of the + sever certificate chain exceed the limits imposed by the crypto + library. + <tp:rationale> + This corresponds to Cert_Limit_Exceeded in the + <tp:type>Connection_Status_Reason</tp:type> enum and to Limit_Exceeded + in the <tp:type>TLS_Certificate_Reject_Reason</tp:type> enum. </tp:rationale> </tp:docstring> </tp:error> |