diff options
Diffstat (limited to 'spec')
| -rw-r--r-- | spec/Account_Interface_External_Password_Storage.xml | 18 | ||||
| -rw-r--r-- | spec/Channel_Type_Server_TLS_Connection.xml | 60 | ||||
| -rw-r--r-- | spec/Connection.xml | 6 | ||||
| -rw-r--r-- | spec/Connection_Interface_Contact_Blocking.xml | 207 | ||||
| -rw-r--r-- | spec/Connection_Manager_Interface_Account_Storage.xml | 29 | ||||
| -rw-r--r-- | spec/Makefile.am | 1 | ||||
| -rw-r--r-- | spec/all.xml | 12 |
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"> |