summaryrefslogtreecommitdiff
path: root/spec
diff options
context:
space:
mode:
Diffstat (limited to 'spec')
-rw-r--r--spec/Account_Interface_External_Password_Storage.xml18
-rw-r--r--spec/Channel_Type_Server_TLS_Connection.xml60
-rw-r--r--spec/Connection.xml6
-rw-r--r--spec/Connection_Interface_Contact_Blocking.xml207
-rw-r--r--spec/Connection_Manager_Interface_Account_Storage.xml29
-rw-r--r--spec/Makefile.am1
-rw-r--r--spec/all.xml12
7 files changed, 303 insertions, 30 deletions
diff --git a/spec/Account_Interface_External_Password_Storage.xml b/spec/Account_Interface_External_Password_Storage.xml
index 71a542428..5bd1bfce0 100644
--- a/spec/Account_Interface_External_Password_Storage.xml
+++ b/spec/Account_Interface_External_Password_Storage.xml
@@ -27,24 +27,30 @@
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
<p>An interface for Accounts whose passwords are stored externally and
- SHOULD NOT be stored by either the <tp:dbus-ref
- namespace="org.freedesktop.Telepathy">AccountManager</tp:dbus-ref> nor
- any <tp:dbus-ref
- namespace="org.freedesktop.Telepathy.Channel.Type">ServerAuthentication</tp:dbus-ref>
+ SHOULD NOT be stored by either the
+ <tp:dbus-ref namespace="ofdT">AccountManager</tp:dbus-ref> nor any
+ <tp:dbus-ref namespace="ofdT.Channel.Type">ServerAuthentication</tp:dbus-ref>
handler.</p>
+
+ <p>This interface SHOULD only appear on accounts for which the
+ related Connection Manager implements
+ <tp:dbus-ref namespace="ofdT">ConnectionManager.Interface.AccountStorage.DRAFT</tp:dbus-ref>.</p>
</tp:docstring>
<method name="ForgetPassword" tp:name-for-bindings="Forget_Password">
<tp:docstring>
- <p>Clears any saved password associated with this account.</p>
+ Clears any saved password associated with this account.
</tp:docstring>
</method>
<property name="PasswordSaved"
tp:name-for-bindings="Password_Saved"
type="b" access="read">
- <tp:docstring>
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
<p>Indicates whether the account has a saved password or not.</p>
+
+ <p>Change notification for this property is provided by the
+ standard D-Bus <code>PropertiesChanged</code> signal.</p>
</tp:docstring>
</property>
diff --git a/spec/Channel_Type_Server_TLS_Connection.xml b/spec/Channel_Type_Server_TLS_Connection.xml
index 1f3348e12..97efd1b36 100644
--- a/spec/Channel_Type_Server_TLS_Connection.xml
+++ b/spec/Channel_Type_Server_TLS_Connection.xml
@@ -44,23 +44,71 @@
</tp:docstring>
<property name="ServerCertificate" type="o" access="read"
- tp:name-for-bindings="Server_Certificate">
+ tp:name-for-bindings="Server_Certificate"
+ tp:immutable='yeah'>
<tp:docstring>
<p>A <tp:dbus-ref
namespace="org.freedesktop.Telepathy.Authentication">TLSCertificate</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>
<property name="Hostname" type="s" access="read"
- tp:name-for-bindings="Hostname">
+ tp:name-for-bindings="Hostname"
+ tp:immutable='sharks'>
<tp:added version="0.19.12"/>
<tp:docstring>
- The hostname of the server we expect <tp:member-ref>ServerCertificate</tp:member-ref>
- to certify; clients SHOULD verify <tp:member-ref>ServerCertificate</tp:member-ref> against
- this hostname when checking its validity.
+ <p>The hostname or domain that the user expects to connect to. Clients
+ SHOULD use the <tp:member-ref>ReferenceIdentities</tp:member-ref>
+ property to verify the identity of the certificate. Clients MAY display
+ this hostname to the user as the expected identity. Clients SHOULD use
+ this property to lookup pinned certificates or other user preferences
+ for the connection.</p>
+ </tp:docstring>
+ </property>
+
+ <property name="ReferenceIdentities" type="as" access="read"
+ tp:name-for-bindings="Reference_Identities"
+ tp:immutable='plz'>
+ <tp:added version="0.21.10">
+ If this property is not present, clients SHOULD use the
+ <tp:member-ref>Hostname</tp:member-ref> property as the reference
+ identity to validate server certificates against.
+ </tp:added>
+
+ <tp:docstring>
+ <p>The identities of the server we expect
+ <tp:member-ref>ServerCertificate</tp:member-ref> to certify; clients
+ SHOULD verify that <tp:member-ref>ServerCertificate</tp:member-ref>
+ matches one of these identities when checking its validity.</p>
+
+ <p>This property MUST NOT be the empty list; it MUST
+ contain the value of the <tp:member-ref>Hostname</tp:member-ref>
+ property. All other identities included in this property MUST be derived from
+ explicit user input or choices, such as <tp:dbus-ref
+ namespace='ofdT.Account'>Parameters</tp:dbus-ref> passed to
+ <tp:dbus-ref
+ namespace='ofdT.ConnectionManager'>RequestConnection</tp:dbus-ref>.</p>
+
+ <tp:rationale>
+ <p>The primary use for this property is for XMPP services hosted by
+ <a href='http://www.google.com/apps/intl/en/business/gmail.html'>Google
+ Apps</a>. When connecting to Google Talk using an
+ <tt>@gmail.com</tt> JID, the server correctly presents a
+ certificate for <tt>gmail.com</tt>; however, for domains hosted via
+ Google Apps, a certificate for <tt>talk.google.com</tt> is
+ offered, due to unresolved technical limitations.</p>
+
+ <p>If the user has explicitly chosen to create a <q>Google Talk</q>
+ account, then trusting a certificate for <tt>talk.google.com</tt>
+ is reasonable. To handle this case, the connection manager may add
+ the values of any or all of the <tt>server</tt>,
+ <tt>fallback-server</tt> and <tt>extra-identities</tt> parameters;
+ the Google Talk account creation user interface may set these
+ parameters appropriately, or the user may set them for accounts
+ with other services.</p>
+ </tp:rationale>
</tp:docstring>
</property>
diff --git a/spec/Connection.xml b/spec/Connection.xml
index 51ec1ab23..0ba095a9e 100644
--- a/spec/Connection.xml
+++ b/spec/Connection.xml
@@ -1033,6 +1033,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>server-message (s)</dt>
+ <dd>A human-readable message from the server explaining what
+ happened. This may be in the user's native language, or in the
+ server operator's native language, or even in Lojban.</dd>
+
<dt>user-requested (b), expected-hostname (s), certificate-hostname (s)</dt>
<dd>The same details defined in <tp:type>TLS_Certificate_Rejection</tp:type>.</dd>
</dl>
diff --git a/spec/Connection_Interface_Contact_Blocking.xml b/spec/Connection_Interface_Contact_Blocking.xml
new file mode 100644
index 000000000..756fd4db8
--- /dev/null
+++ b/spec/Connection_Interface_Contact_Blocking.xml
@@ -0,0 +1,207 @@
+<?xml version="1.0" ?>
+<node name="/Connection_Interface_Contact_Blocking" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
+ <tp:copyright>Copyright © 2009–2011 Collabora Ltd.</tp:copyright>
+ <tp:copyright>Copyright © 2009 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.Connection.Interface.ContactBlocking">
+ <tp:requires interface="org.freedesktop.Telepathy.Connection"/>
+ <tp:requires interface="org.freedesktop.Telepathy.Connection.Interface.ContactList"/>
+ <tp:added version='0.21.13'>Changes from the draft:
+ methods and signals now return <tp:type>Handle_Identifier_Map</tp:type>
+ (<code>a{us}</code>) rather than bare lists of contact handles
+ (<code>au</code>)</tp:added>
+
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>An interface for connections where contacts can be blocked from
+ communicating with this user and receiving this user's presence.
+ Clients may retrieve a list of currently-blocked contacts using
+ <tp:member-ref>RequestBlockedContacts</tp:member-ref>, and listen for
+ <tp:member-ref>BlockedContactsChanged</tp:member-ref> to be notified
+ when contacts are blocked and unblocked. The
+ <tp:member-ref>BlockContacts</tp:member-ref> and
+ <tp:member-ref>UnblockContacts</tp:member-ref> methods do what they say
+ on the tin; depending on the value of the
+ <tp:member-ref>ContactBlockingCapabilities</tp:member-ref> property,
+ contacts may be reported for spam or other abuse when calling
+ <tp:member-ref>BlockContacts</tp:member-ref>.</p>
+
+ <p>This interface is intended for protocols where blocking contacts
+ persists on the server between connections; connection managers for
+ protocols with no server-side support for blocking contacts MAY choose
+ to implement this interface using an on-disk file of blocked
+ contacts or some other means to store blocked contacts between
+ connections.</p>
+
+ <p>This interface is intended to replace the
+ <tp:dbus-ref namespace="ofdT.Channel.Type">ContactList</tp:dbus-ref>
+ channel with <tp:dbus-ref
+ namespace='ofdT.Channel'>TargetHandleType</tp:dbus-ref>
+ <code>List</code> and <tp:dbus-ref
+ namespace='ofdT.Channel'>TargetID</tp:dbus-ref> <code>"deny"</code>
+ (along with the <tp:dbus-ref
+ namespace='ofdT.Connection.Interface'>ContactList</tp:dbus-ref> and
+ <tp:dbus-ref
+ namespace='ofdT.Connection.Interface'>ContactGroups</tp:dbus-ref>
+ interfaces replacing other channels with <tp:dbus-ref
+ namespace='ofdT.Channel'>TargetHandleType</tp:dbus-ref>
+ <code>List</code> and <tp:dbus-ref
+ namespace='ofdT.Channel'>TargetHandleType</tp:dbus-ref>
+ <code>Group</code>, respectively).</p>
+ </tp:docstring>
+
+ <method name="BlockContacts" tp:name-for-bindings="Block_Contacts">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Direct the server to block some contacts. The precise effect is
+ protocol-dependent, but SHOULD include ignoring all current and
+ subsequent communications from the given contacts, avoiding sending
+ presence to them in future, and if they were already receiving the
+ local user's presence, behaving as if the local user went
+ offline.</p>
+ </tp:docstring>
+
+ <arg name="Contacts" type="au" direction="in" tp:type="Contact_Handle[]">
+ <tp:docstring>Some contacts to block. If some of the contacts in this
+ list are already blocked, the connection manager MUST act as if they
+ were not specified in this list.</tp:docstring>
+ </arg>
+
+ <arg name="Report_Abusive" type="b" direction="in">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>In addition to blocking, report these contacts as abusive to the
+ server administrators.</p>
+
+ <p>Clients can determine whether this capability is available by
+ checking the
+ <tp:member-ref>ContactBlockingCapabilities</tp:member-ref>
+ property. If this argument is set to <code>True</code> by a client
+ despite <tp:member-ref>ContactBlockingCapabilities</tp:member-ref>
+ not containing the <code>Can_Report_Abusive</code> flag, the
+ connection manager SHOULD act as if it were <code>False</code> and
+ simply block the supplied contacts.</p>
+
+ <tp:rationale>
+ <p>A correct user interface shouldn't get this far without knowing
+ that reporting abusive contacts is not supported. If it does,
+ then the user has expressed their intention to block these
+ contacts. Returning an error would leave the UI with three
+ options:</p>
+
+ <ul>
+ <li>Ignore the error, leaving the contacts not actually blocked;</li>
+ <li>Display an error to the user;</li>
+ <li>Call this method again, passing <code>False</code> for this
+ argument.</li>
+ </ul>
+
+ <p>None of these seem preferable to the CM just ignoring this flag
+ if it doesn't support it: that way, the contacts will be blocked,
+ as the user requested, and UIs have fewer ways to mess up
+ entirely.</p>
+ </tp:rationale>
+ </tp:docstring>
+ </arg>
+ </method>
+
+ <method name="UnblockContacts" tp:name-for-bindings="Unblock_Contacts">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Direct the server to unblock some contacts.</p>
+ </tp:docstring>
+
+ <arg name="Contacts" type="au" direction="in" tp:type="Contact_Handle[]">
+ <tp:docstring>Some contacts to unblock. If some of the contacts in this
+ list are not currently blocked, the connection manager MUST act as if
+ they were not specified in this list.</tp:docstring>
+ </arg>
+ </method>
+
+ <method name="RequestBlockedContacts"
+ tp:name-for-bindings="Request_Blocked_Contacts">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>List the contacts that are blocked.</p>
+
+ <p>Clients SHOULD allow a relatively long timeout for calls to this
+ method, since on some protocols contact blocking is part of the
+ contact list, which can take a significant time to retrieve.</p>
+ </tp:docstring>
+
+ <arg name="Contacts" type="a{us}" direction="out"
+ tp:type="Handle_Identifier_Map">
+ <tp:docstring>The blocked contacts’ handles, together with their
+ identifiers.</tp:docstring>
+ </arg>
+ </method>
+
+ <signal name="BlockedContactsChanged"
+ tp:name-for-bindings="Blocked_Contacts_Changed">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Emitted when the list of blocked contacts is first retrieved
+ (before returning from any pending calls to
+ <tp:member-ref>RequestBlockedContacts</tp:member-ref>), and
+ whenever the list of blocked contacts subsequently changes.</p>
+ </tp:docstring>
+
+ <arg name="Blocked_Contacts" type="a{us}" tp:type="Handle_Identifier_Map">
+ <tp:docstring>Contacts added to the result of
+ <tp:member-ref>RequestBlockedContacts</tp:member-ref>.</tp:docstring>
+ </arg>
+
+ <arg name="Unblocked_Contacts" type="a{us}"
+ tp:type="Handle_Identifier_Map">
+ <tp:docstring>Contacts removed from the result of
+ <tp:member-ref>RequestBlockedContacts</tp:member-ref>.</tp:docstring>
+ </arg>
+ </signal>
+
+ <tp:contact-attribute name="blocked" type="b">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p><code>True</code> if the contact would be in the result of
+ <tp:member-ref>RequestBlockedContacts</tp:member-ref>;
+ <code>False</code> or omitted if the contact is not blocked, or if it
+ is unknown whether the contact is blocked.</p>
+ </tp:docstring>
+ </tp:contact-attribute>
+
+ <property name="ContactBlockingCapabilities"
+ tp:name-for-bindings="Contact_Blocking_Capabilities"
+ tp:type="Contact_Blocking_Capabilities" type="u" access="read"
+ tp:immutable="yes">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Additional capabilities for contact blocking; currently, this is
+ limited to whether contacts may be reported as abusive.</p>
+
+ <p>Note that there is no capability for supporting blocking itself:
+ the presence of this interface on a <tp:dbus-ref
+ namespace='ofdT'>Connection</tp:dbus-ref> indicates that blocking
+ contacts is supported.</p>
+ </tp:docstring>
+ </property>
+
+ <tp:flags name="Contact_Blocking_Capabilities" type="u"
+ value-prefix="Contact_Blocking_Capability">
+ <tp:flag suffix="Can_Report_Abusive" value="1">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ When calling <tp:member-ref>BlockContacts</tp:member-ref>, the
+ contacts may be reporting as abusive to the server administrators by
+ setting <var>Report_Abusive</var> to <code>True</code>.
+ </tp:docstring>
+ </tp:flag>
+ </tp:flags>
+
+ </interface>
+</node>
+<!-- vim:set sw=2 sts=2 et ft=xml: -->
diff --git a/spec/Connection_Manager_Interface_Account_Storage.xml b/spec/Connection_Manager_Interface_Account_Storage.xml
index 143d5de73..2f4f4bf78 100644
--- a/spec/Connection_Manager_Interface_Account_Storage.xml
+++ b/spec/Connection_Manager_Interface_Account_Storage.xml
@@ -29,18 +29,18 @@
<p>An interface for connection managers that store account details
internally. At the moment this consists only of storing an account's
credentials, but other functionality may be added in the future.</p>
- <p><tp:dbus-ref
- namespace="org.freedesktop.Telepathy">Account</tp:dbus-ref> objects
+
+ <p><tp:dbus-ref namespace="ofdT">Account</tp:dbus-ref> objects
representing accounts on a connection manager that implements this
- interface should implement the <tp:dbus-ref
- namespace="org.freedesktop.Telepathy.Account.Interface">ExternalPasswordStorage.DRAFT</tp:dbus-ref>
+ interface should implement the
+ <tp:dbus-ref namespace="ofdT.Account.Interface">ExternalPasswordStorage.DRAFT</tp:dbus-ref>
interface.</p>
-
</tp:docstring>
<tp:flags name="Account_Flags" value-prefix="Account_Flag" type="u">
<tp:docstring>
- A set of flags representing the status of the Account stored in the Connection Manager.
+ A set of flags representing the status of the Account stored in the
+ Connection Manager.
</tp:docstring>
<tp:flag suffix="Credentials_Stored" value="1">
@@ -61,9 +61,12 @@
<property name="Accounts"
tp:name-for-bindings="Accounts"
type="a{su}" tp:type="Account_Flags_Map" access="read">
- <tp:docstring>
- The set of Accounts stored in this connection manager, and flags
- indicating their status.
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The set of Accounts stored in this Connection Manager, and flags
+ indicating their status.</p>
+
+ <p>Change notification for this property is provided by the standard
+ D-Bus <code>PropertiesChanged</code> signal.</p>
</tp:docstring>
</property>
@@ -76,8 +79,8 @@
<arg direction="in" name="Account_Id"
type="s">
<tp:docstring>
- An account id as returned from <tp:dbus-ref
- namespace="org.freedesktop.Telepathy">Protocol.IdentifyAccount</tp:dbus-ref>.
+ An account id as returned from
+ <tp:dbus-ref namespace="ofdT">Protocol.IdentifyAccount</tp:dbus-ref>.
</tp:docstring>
</arg>
@@ -99,8 +102,8 @@
<arg direction="in" name="Account_Id"
type="s">
<tp:docstring>
- An account id as returned from <tp:dbus-ref
- namespace="org.freedesktop.Telepathy">Protocol.IdentifyAccount</tp:dbus-ref>.
+ An account id as returned from
+ <tp:dbus-ref namespace="ofdT">Protocol.IdentifyAccount</tp:dbus-ref>.
</tp:docstring>
</arg>
diff --git a/spec/Makefile.am b/spec/Makefile.am
index e8e3e0cc5..767780e59 100644
--- a/spec/Makefile.am
+++ b/spec/Makefile.am
@@ -75,6 +75,7 @@ EXTRA_DIST = \
Connection_Interface_Cellular.xml \
Connection_Interface_Client_Types.xml \
Connection_Interface_Communication_Policy.xml \
+ Connection_Interface_Contact_Blocking.xml \
Connection_Interface_Contact_Capabilities.xml \
Connection_Interface_Contact_Groups.xml \
Connection_Interface_Contact_Info.xml \
diff --git a/spec/all.xml b/spec/all.xml
index fccf75c95..a5644a90f 100644
--- a/spec/all.xml
+++ b/spec/all.xml
@@ -3,10 +3,10 @@
xmlns:xi="http://www.w3.org/2001/XInclude">
<tp:title>Telepathy D-Bus Interface Specification</tp:title>
-<tp:version>0.21.12</tp:version>
+<tp:version>0.22.0</tp:version>
-<tp:copyright>Copyright © 2005-2010 Collabora Limited</tp:copyright>
-<tp:copyright>Copyright © 2005-2010 Nokia Corporation</tp:copyright>
+<tp:copyright>Copyright © 2005-2011 Collabora Limited</tp:copyright>
+<tp:copyright>Copyright © 2005-2011 Nokia Corporation</tp:copyright>
<tp:copyright>Copyright © 2006 INdT</tp:copyright>
<tp:license xmlns="http://www.w3.org/1999/xhtml">
@@ -56,13 +56,15 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
<p>
On protocols that support contact lists, these interface expose the user's
- contact lists, along with presence subscription information and contact
- list groups (if supported).
+ contact lists, along with presence subscription information, contact
+ list groups (if supported), and the ability to block and unblock contacts
+ (if supported).
</p>
</tp:docstring>
<xi:include href="Connection_Interface_Contact_List.xml"/>
<xi:include href="Connection_Interface_Contact_Groups.xml"/>
+ <xi:include href="Connection_Interface_Contact_Blocking.xml"/>
</tp:section>
<tp:section name="Contact metadata interfaces">