[Telepathy-commits] [telepathy-glib/master] Update spec to 0.17.19 prerelease
Simon McVittie
simon.mcvittie at collabora.co.uk
Wed Jan 28 02:56:28 PST 2009
---
docs/reference/telepathy-glib-sections.txt | 3 +
spec/Channel_Interface_Group.xml | 29 +++-
spec/Channel_Interface_Tube.xml | 6 +-
spec/Channel_Type_DBus_Tube.xml | 2 +-
spec/Channel_Type_File_Transfer.xml | 2 +-
spec/Connection.xml | 259 ++++++++++++++++++++++++----
spec/Connection_Interface_Contact_Info.xml | 2 +-
spec/Connection_Interface_Location.xml | 2 +-
spec/Connection_Interface_Requests.xml | 18 ++-
spec/all.xml | 2 +-
spec/errors.xml | 162 +++++++++++++++++-
11 files changed, 437 insertions(+), 50 deletions(-)
diff --git a/docs/reference/telepathy-glib-sections.txt b/docs/reference/telepathy-glib-sections.txt
index 55364a6..90a29c8 100644
--- a/docs/reference/telepathy-glib-sections.txt
+++ b/docs/reference/telepathy-glib-sections.txt
@@ -705,6 +705,7 @@ tp_svc_connection_return_from_request_handles
tp_svc_connection_emit_new_channel
tp_svc_connection_emit_self_handle_changed
tp_svc_connection_emit_status_changed
+tp_svc_connection_emit_connection_error
<SUBSECTION Standard>
TP_SVC_CONNECTION
TP_IS_SVC_CONNECTION
@@ -2288,6 +2289,8 @@ tp_cli_connection_signal_callback_self_handle_changed
tp_cli_connection_connect_to_self_handle_changed
tp_cli_connection_signal_callback_status_changed
tp_cli_connection_connect_to_status_changed
+tp_cli_connection_signal_callback_connection_error
+tp_cli_connection_connect_to_connection_error
</SECTION>
<SECTION>
diff --git a/spec/Channel_Interface_Group.xml b/spec/Channel_Interface_Group.xml
index 019e848..de429b9 100644
--- a/spec/Channel_Interface_Group.xml
+++ b/spec/Channel_Interface_Group.xml
@@ -593,8 +593,13 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
</tp:docstring>
</tp:enumvalue>
<tp:enumvalue suffix="Banned" value="5">
- <tp:docstring>
- The change is due to a kick+ban operation.
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The change is due to a kick+ban operation.</p>
+
+ <p>If the <tp:member-ref>SelfHandle</tp:member-ref> is removed
+ from a group for this reason, the equivalent D-Bus error is
+ <code>org.freedesktop.Telepathy.Error.Channel.Banned</code>.
+ </p>
</tp:docstring>
</tp:enumvalue>
<tp:enumvalue suffix="Error" value="6">
@@ -603,8 +608,16 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
</tp:docstring>
</tp:enumvalue>
<tp:enumvalue suffix="Invalid_Contact" value="7">
- <tp:docstring>
- The change is because the requested contact does not exist.
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The change is because the requested contact does not exist.</p>
+
+ <tp:rationale>
+ <p>For instance, if the user invites a nonexistent contact to a
+ chatroom or attempts to call a nonexistent contact, this could
+ be indicated by the CM adding that contact's handle to
+ remote-pending for reason None or Invited, then removing it for
+ reason Invalid_Contact.</p>
+ </tp:rationale>
</tp:docstring>
</tp:enumvalue>
<tp:enumvalue suffix="No_Answer" value="8">
@@ -937,6 +950,14 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
should be emitted when information
is retrieved from the server, or changes occur.</p>
+ <p>If the <tp:member-ref>MembersChanged</tp:member-ref> or
+ <tp:member-ref>MembersChangedDetailed</tp:member-ref> signal indicates
+ that the <tp:member-ref>SelfHandle</tp:member-ref> has been removed from
+ the channel, and the channel subsequently emits <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Channel">Closed</tp:dbus-ref>,
+ clients SHOULD consider the details given in the MembersChanged or
+ MembersChangedDetailed signal to be the reason why the channel closed.</p>
+
<p>Addition of members to the channel may be requested by using
<tp:member-ref>AddMembers</tp:member-ref>. If
remote acknowledgement is required, use of the AddMembers method will cause
diff --git a/spec/Channel_Interface_Tube.xml b/spec/Channel_Interface_Tube.xml
index ff249eb..b2d0f31 100644
--- a/spec/Channel_Interface_Tube.xml
+++ b/spec/Channel_Interface_Tube.xml
@@ -68,10 +68,10 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
</tp:docstring>
</property>
- <property name="Status" type="u" tp:type="Tube_Channel_State" access="read"
- tp:name-for-bindings="Status">
+ <property name="State" type="u" tp:type="Tube_Channel_State" access="read"
+ tp:name-for-bindings="State">
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
- <p>Status of the tube in this channel.</p>
+ <p>State of the tube in this channel.</p>
<p>When requesting a channel with
<tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.Interface.Requests.CreateChannel</tp:dbus-ref>,
this property MUST NOT be included in the request.</p>
diff --git a/spec/Channel_Type_DBus_Tube.xml b/spec/Channel_Type_DBus_Tube.xml
index 34130c2..2671a17 100644
--- a/spec/Channel_Type_DBus_Tube.xml
+++ b/spec/Channel_Type_DBus_Tube.xml
@@ -128,7 +128,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
For a multi-user (i.e. Handle_Type_Room) D-Bus tube, a mapping
between contact handles and their unique bus names on this tube.
For a peer-to-peer (i.e. Handle_Type_Contact) D-Bus tube, the empty
- list. Change notification is via
+ dictionary. Change notification is via
<tp:member-ref>DBusNamesChanged</tp:member-ref>.
</tp:docstring>
</property>
diff --git a/spec/Channel_Type_File_Transfer.xml b/spec/Channel_Type_File_Transfer.xml
index f5268c8..c88834c 100644
--- a/spec/Channel_Type_File_Transfer.xml
+++ b/spec/Channel_Type_File_Transfer.xml
@@ -20,7 +20,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
</tp:license>
<interface name="org.freedesktop.Telepathy.Channel.Type.FileTransfer">
<tp:requires interface="org.freedesktop.Telepathy.Channel"/>
- <tp:added version="0.17.UNRELEASED">(as stable API)</tp:added>
+ <tp:added version="0.17.18">(as stable API)</tp:added>
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
<p>A channel type for transferring files. The
transmission of data between contacts is achieved by reading from
diff --git a/spec/Connection.xml b/spec/Connection.xml
index bc46ecf..84f54a7 100644
--- a/spec/Connection.xml
+++ b/spec/Connection.xml
@@ -492,6 +492,12 @@ USA.</p>
The requested channel type cannot be created with the given handle
</tp:docstring>
</tp:error>
+ <tp:error name="org.freedesktop.Telepathy.Error.NotCapable">
+ <tp:docstring>
+ The requested channel cannot be created because contact doesn't
+ have the required capabilities.
+ </tp:docstring>
+ </tp:error>
<tp:error name="org.freedesktop.Telepathy.Error.Channel.Banned"/>
<tp:error name="org.freedesktop.Telepathy.Error.Channel.Full"/>
<tp:error name="org.freedesktop.Telepathy.Error.Channel.InviteOnly"/>
@@ -633,83 +639,274 @@ USA.</p>
</tp:docstring>
</tp:enumvalue>
</tp:enum>
+
<tp:enum name="Connection_Status_Reason" type="u">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>A reason why the status of the connection changed. Apart from
+ Requested, the values of this enumeration only make sense as
+ reasons why the status changed to Disconnected.</p>
+ </tp:docstring>
+
<tp:enumvalue suffix="None_Specified" value="0">
- <tp:docstring>
- There is no reason set for this state change.
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>There is no reason set for this state change. Unknown status
+ reasons SHOULD be treated like this reason.</p>
+
+ <p>When disconnected for this reason, the equivalent D-Bus error is
+ <code>org.freedesktop.Telepathy.Error.Disconnected</code>.</p>
</tp:docstring>
</tp:enumvalue>
+
<tp:enumvalue suffix="Requested" value="1">
- <tp:docstring>
- The change is in response to a user request.
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The change is in response to a user request. Changes to the
+ Connecting or Connected status SHOULD always indicate this reason;
+ changes to the Disconnected status SHOULD indicate this reason
+ if and only if the disconnection was requested by the user.</p>
+
+ <p>When disconnected for this reason, the equivalent D-Bus error is
+ <code>org.freedesktop.Telepathy.Error.Cancelled</code>.</p>
</tp:docstring>
</tp:enumvalue>
+
<tp:enumvalue suffix="Network_Error" value="2">
- <tp:docstring>
- There was an error sending or receiving on the network socket.
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>There was an error sending or receiving on the network socket.</p>
+
+ <p>When disconnected for this reason, the equivalent D-Bus error is
+ <code>org.freedesktop.Telepathy.Error.NetworkError</code>.</p>
</tp:docstring>
</tp:enumvalue>
+
<tp:enumvalue suffix="Authentication_Failed" value="3">
- <tp:docstring>
- The username or password was invalid.
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The username or password was invalid.</p>
+
+ <p>When disconnected for this reason, the equivalent D-Bus error is
+ <code>org.freedesktop.Telepathy.Error.AuthenticationFailed</code>.
+ </p>
</tp:docstring>
</tp:enumvalue>
+
<tp:enumvalue suffix="Encryption_Error" value="4">
- <tp:docstring>
- There was an error negotiating SSL on this connection, or
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>There was an error negotiating SSL on this connection, or
encryption was unavailable and require-encryption was set when the
- connection was created.
+ connection was created.</p>
+
+ <p>When disconnected for this reason, the equivalent D-Bus error is
+ <code>org.freedesktop.Telepathy.Error.EncryptionNotAvailable</code>
+ if encryption was not available at all, or
+ <code>org.freedesktop.Telepathy.Error.EncryptionError</code>
+ if encryption failed.</p>
</tp:docstring>
</tp:enumvalue>
+
<tp:enumvalue suffix="Name_In_Use" value="5">
- <tp:docstring>
- Someone is already connected to the server using the name
- you are trying to connect with.
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>In general, this reason indicates that the requested account
+ name or other identification could not be used due to conflict
+ with another connection. It can be divided into three cases:</p>
+
+ <ul>
+ <li>If the status change is from Connecting to Disconnected
+ and the 'register' parameter to RequestConnection was present
+ and true, the requested account could not be created on the
+ server because it already exists.</li>
+
+ <li>If the status change is from Connecting to Disconnected
+ but the 'register' parameter is absent or false, the connection
+ manager could not connect to the specified account because
+ a connection to that account already exists.
+
+ <tp:rationale>
+ In some protocols, like XMPP (when connecting with the same
+ JID and resource as an existing connection), the existing
+ connection "wins" and the new one fails to connect.
+ </tp:rationale>
+ </li>
+
+ <li>If the status change is from Connected to Disconnected,
+ the existing connection was automatically disconnected because
+ a new connection to the same account (perhaps from a different
+ client or location) was established.
+
+ <tp:rationale>
+ In some protocols, like MSNP (when connecting twice with the
+ same Passport), the new connection "wins" and the
+ existing one is automatically disconnected.
+ </tp:rationale>
+ </li>
+ </ul>
+
+ <p>When disconnected for this reason, the equivalent D-Bus error is
+ <code>org.freedesktop.Telepathy.Error.NotYours</code>.
+ </p>
+
+ <tp:rationale>
+ These three errors are distinct but very similar, and can be
+ distinguished by other factors.
+ </tp:rationale>
</tp:docstring>
</tp:enumvalue>
+
<tp:enumvalue suffix="Cert_Not_Provided" value="6">
- <tp:docstring>
- The server did not provide a SSL certificate.
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The server did not provide a SSL certificate.</p>
+
+ <p>When disconnected for this reason, the equivalent D-Bus error is
+ <code>org.freedesktop.Telepathy.Error.Cert.NotProvided</code>.
+ </p>
</tp:docstring>
</tp:enumvalue>
+
<tp:enumvalue suffix="Cert_Untrusted" value="7">
- <tp:docstring>
- The server's SSL certificate could not be trusted.
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The server's SSL certificate is signed by an untrusted certifying
+ authority. This error SHOULD NOT be used to represent a self-signed
+ certificate: use the more specific Cert_Self_Signed reason for
+ that.</p>
+
+ <p>When disconnected for this reason, the equivalent D-Bus error is
+ <code>org.freedesktop.Telepathy.Error.Cert.Untrusted</code>.
+ </p>
</tp:docstring>
</tp:enumvalue>
+
<tp:enumvalue suffix="Cert_Expired" value="8">
- <tp:docstring>
- The server's SSL certificate has expired.
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The server's SSL certificate has expired.</p>
+
+ <p>When disconnected for this reason, the equivalent D-Bus error is
+ <code>org.freedesktop.Telepathy.Error.Cert.Expired</code>.
+ </p>
</tp:docstring>
</tp:enumvalue>
+
<tp:enumvalue suffix="Cert_Not_Activated" value="9">
- <tp:docstring>
- The server's SSL certificate is not yet valid.
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The server's SSL certificate is not yet valid.</p>
+
+ <p>When disconnected for this reason, the equivalent D-Bus error is
+ <code>org.freedesktop.Telepathy.Error.Cert.NotActivated</code>.
+ </p>
</tp:docstring>
</tp:enumvalue>
+
<tp:enumvalue suffix="Cert_Hostname_Mismatch" value="10">
- <tp:docstring>
- The server's SSL certificate did not match its hostname.
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The server's SSL certificate did not match its hostname.</p>
+
+ <p>When disconnected for this reason, the equivalent D-Bus error is
+ <code>org.freedesktop.Telepathy.Error.Cert.HostnameMismatch</code>.
+ </p>
</tp:docstring>
</tp:enumvalue>
+
<tp:enumvalue suffix="Cert_Fingerprint_Mismatch" value="11">
- <tp:docstring>
- The server's SSL certificate does not have the expected
- fingerprint.
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The server's SSL certificate does not have the expected
+ fingerprint.</p>
+
+ <p>When disconnected for this reason, the equivalent D-Bus error is
+ <code>org.freedesktop.Telepathy.Error.Cert.FingerprintMismatch</code>.
+ </p>
</tp:docstring>
</tp:enumvalue>
+
<tp:enumvalue suffix="Cert_Self_Signed" value="12">
- <tp:docstring>
- The server's SSL certificate is self-signed.
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <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>.
+ </p>
</tp:docstring>
</tp:enumvalue>
+
<tp:enumvalue suffix="Cert_Other_Error" value="13">
- <tp:docstring>
- There was some other error validating the server's SSL certificate.
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>There was some other error validating the server's SSL
+ certificate.</p>
+
+ <p>When disconnected for this reason, the equivalent D-Bus error is
+ <code>org.freedesktop.Telepathy.Error.Cert.Invalid</code>.
+ </p>
</tp:docstring>
</tp:enumvalue>
</tp:enum>
+ <signal name="ConnectionError" tp:name-for-bindings="Connection_Error">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Emitted when an error occurs that renders this connection unusable.
+ </p>
+
+ <p>Whenever this signal is emitted, it MUST immediately be followed by
+ a <tp:member-ref>StatusChanged</tp:member-ref> signal with status
+ Connection_Status_Reason_Disconnected and an appropriate reason
+ code.</p>
+
+ <p>Connection managers SHOULD emit this signal on disconnection, but
+ need not do so. Clients MUST support connection managers that emit
+ StatusChanged(Disconnected, ...) without first emitting
+ ConnectionError.</p>
+
+ <tp:rationale>
+ <p>This signal provides additional information about the reason
+ for disconnection. The reason for connection is always
+ straightforward - it was requested - so it does not need further
+ explanation. However, on errors, it can be useful to provide
+ additional information.</p>
+
+ <p>The <tp:type>Connection_Status_Reason</tp:type> is not given
+ here, since it will be signalled in
+ <tp:member-ref>StatusChanged</tp:member-ref>. A reasonable client
+ implementation would be to store the information given by this
+ signal until StatusChanged is received, at which point the
+ information given by this signal can be used to supplement the
+ StatusChanged signal.</p>
+ </tp:rationale>
+
+ <arg name="Error" type="s" tp:type="DBus_Error_Name">
+ <tp:docstring>
+ The name of a D-Bus error describing the error that occurred,
+ which may correspond to a
+ <tp:type>Connection_Status_Reason</tp:type> or be a
+ protocol-specific or connection-manager-specific error in a
+ suitable namespace.
+
+ <tp:rationale>
+ For instance, a SIP connection manager could signal
+ "402 Payment Required" as an error in a
+ connection-manager-specific namespace, or a link-local
+ XMPP implementation that used Avahi could provide the error
+ given to it by the avahi-daemon.
+ </tp:rationale>
+ </tp:docstring>
+ </arg>
+
+ <arg name="Details" type="a{sv}" tp:type="String_Variant_Map">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Additional information about the error, which may include
+ the following well-known keys:</p>
+
+ <dl>
+ <dt>debug-message (s)</dt>
+ <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>
+ </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>
+ </tp:docstring>
+ </signal>
+
<signal name="StatusChanged" tp:name-for-bindings="Status_Changed">
<arg name="Status" type="u" tp:type="Connection_Status">
<tp:docstring>
diff --git a/spec/Connection_Interface_Contact_Info.xml b/spec/Connection_Interface_Contact_Info.xml
index c29f9fe..e7b033b 100644
--- a/spec/Connection_Interface_Contact_Info.xml
+++ b/spec/Connection_Interface_Contact_Info.xml
@@ -19,7 +19,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
</tp:license>
<interface name="org.freedesktop.Telepathy.Connection.Interface.ContactInfo.DRAFT"
tp:causes-havoc="experimental">
- <tp:added version="0.17.UNRELEASED">(as a draft)</tp:added>
+ <tp:added version="0.17.18">(as a draft)</tp:added>
<tp:requires interface="org.freedesktop.Telepathy.Connection"/>
<tp:struct name="Contact_Info_Field" array-name="Contact_Info_Field_List">
diff --git a/spec/Connection_Interface_Location.xml b/spec/Connection_Interface_Location.xml
index dbd8d83..8821ec0 100644
--- a/spec/Connection_Interface_Location.xml
+++ b/spec/Connection_Interface_Location.xml
@@ -20,7 +20,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
</tp:license>
<interface name="org.freedesktop.Telepathy.Connection.Interface.Location.DRAFT"
tp:causes-havoc='experimental'>
- <tp:added version="0.17.UNRELEASED">(as a draft)</tp:added>
+ <tp:added version="0.17.18">(as a draft)</tp:added>
<tp:requires interface="org.freedesktop.Telepathy.Connection"/>
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
diff --git a/spec/Connection_Interface_Requests.xml b/spec/Connection_Interface_Requests.xml
index 203421b..3e47262 100644
--- a/spec/Connection_Interface_Requests.xml
+++ b/spec/Connection_Interface_Requests.xml
@@ -211,6 +211,12 @@
property provided was not a valid DNS name.
</tp:docstring>
</tp:error>
+ <tp:error name="org.freedesktop.Telepathy.Error.NotCapable">
+ <tp:docstring>
+ The requested channel cannot be created because the requested
+ contact is using a client that lacks a particular feature.
+ </tp:docstring>
+ </tp:error>
<tp:error name="org.freedesktop.Telepathy.Error.NotAvailable">
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
<p>The requested channel cannot be created, but in
@@ -218,8 +224,6 @@
For instance, this might be because:</p>
<ul>
- <li>the requested contact is using a client
- that lacks a particular feature</li>
<li>a channel matching the request already exists and the
protocol requires that only one such channel can exist at a
time</li>
@@ -346,12 +350,16 @@
property provided was not a valid DNS name.
</tp:docstring>
</tp:error>
+ <tp:error name="org.freedesktop.Telepathy.Error.NotCapable">
+ <tp:docstring>
+ The requested channel cannot be created because the requested
+ contact is using a client that lacks a particular feature.
+ </tp:docstring>
+ </tp:error>
<tp:error name="org.freedesktop.Telepathy.Error.NotAvailable">
<tp:docstring>
The requested channel cannot be created, but in
- principle, a similar request might succeed in future. For instance,
- this might be because the requested contact is using a client
- that lacks a particular feature.
+ principle, a similar request might succeed in future.
</tp:docstring>
</tp:error>
<tp:error name="org.freedesktop.Telepathy.Error.Channel.Banned"/>
diff --git a/spec/all.xml b/spec/all.xml
index cee9b92..7fc0e75 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.17.18</tp:version>
+<tp:version>0.17.18.1</tp:version>
<tp:copyright>Copyright (C) 2005-2008 Collabora Limited</tp:copyright>
<tp:copyright>Copyright (C) 2005-2008 Nokia Corporation</tp:copyright>
diff --git a/spec/errors.xml b/spec/errors.xml
index 679e3f4..954a575 100644
--- a/spec/errors.xml
+++ b/spec/errors.xml
@@ -35,7 +35,17 @@
<tp:error name="Disconnected">
<tp:docstring>
- The connection is not currently connected and cannot be used.
+ The connection is not currently connected and cannot be used.
+ This error may also be raised when operations are performed on a
+ Connection for which
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy.Connection">StatusChanged</tp:dbus-ref>
+ has signalled status Disconnected for reason None.
+
+ <tp:rationale>
+ The second usage corresponds to None in the
+ <tp:type>Connection_Status_Reason</tp:type> enum; if a better reason
+ is available, the corresponding error should be used instead.
+ </tp:rationale>
</tp:docstring>
</tp:error>
@@ -73,10 +83,158 @@
<tp:error name="Cancelled">
<tp:docstring>
Raised by an ongoing request if it is cancelled by user request before
- it has completed.
+ it has completed, or when operations are performed on an object which
+ the user has asked to close (for instance, a Connection where the user
+ has called Disconnect, or a Channel where the user has called Close).
+
+ <tp:rationale>
+ The second form can be used to correspond to the Requested member in
+ the <tp:type>Connection_Status_Reason</tp:type> enum, or to
+ to represent the situation where disconnecting a Connection,
+ closing a Channel, etc. has been requested by the user but this
+ request has not yet been acted on, for instance because the
+ service will only act on the request when it has finished processing
+ an event queue.
+ </tp:rationale>
+ </tp:docstring>
+ </tp:error>
+
+ <tp:error name="Authentication Failed">
+ <tp:docstring>
+ Raised when authentication with a service was unsuccessful.
+ <tp:rationale>
+ This corresponds to Authentication_Failed in the
+ <tp:type>Connection_Status_Reason</tp:type> enum.
+ </tp:rationale>
+ </tp:docstring>
+ </tp:error>
+
+ <tp:error name="Encryption Not Available">
+ <tp:docstring>
+ Raised if a user request insisted that encryption should be used,
+ but encryption was not actually available.
+
+ <tp:rationale>
+ This corresponds to part of Encryption_Error in the
+ <tp:type>Connection_Status_Reason</tp:type> enum. It's been separated
+ into a distinct error here because the two concepts that were part
+ of EncryptionError seem to be things that could reasonably appear
+ differently in the UI.
+ </tp:rationale>
+ </tp:docstring>
+ </tp:error>
+
+ <tp:error name="Encryption Error">
+ <tp:docstring>
+ Raised if encryption appears to be available, but could not actually be
+ used (for instance if SSL/TLS negotiation fails).
+ <tp:rationale>
+ This corresponds to part of Encryption_Error in the
+ <tp:type>Connection_Status_Reason</tp:type> enum.
+ </tp:rationale>
+ </tp:docstring>
+ </tp:error>
+
+ <tp:error name="Cert.Not Provided">
+ <tp:docstring>
+ Raised if the server did not provide a SSL/TLS certificate. This error
+ MUST NOT be used to represent the absence of a client certificate
+ provided by the Telepathy connection manager.
+ <tp:rationale>
+ This corresponds to Cert_Not_Provided in the
+ <tp:type>Connection_Status_Reason</tp:type> enum. That error
+ explicitly applied only to server SSL certificates, so this one
+ is similarly limited; having the CM present a client certificate
+ is a possible future feature, but it should have its own error
+ handling.
+ </tp:rationale>
+ </tp:docstring>
+ </tp:error>
+
+ <tp:error name="Cert.Untrusted">
+ <tp:docstring>
+ Raised if the server provided a SSL/TLS certificate signed by an
+ untrusted certifying authority. This error SHOULD NOT be used to
+ 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
+ to avoid ambiguity.
+ </tp:rationale>
+ </tp:docstring>
+ </tp:error>
+
+ <tp:error name="Cert.Expired">
+ <tp:docstring>
+ 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:rationale>
</tp:docstring>
</tp:error>
+ <tp:error name="Cert.Not Activated">
+ <tp:docstring>
+ Raised if the server provided an SSL/TLS certificate that will become
+ 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:rationale>
+ </tp:docstring>
+ </tp:error>
+
+ <tp:error name="Cert.Fingerprint Mismatch">
+ <tp:docstring>
+ Raised if the server provided an SSL/TLS certificate that did not have
+ the expected fingerprint.
+ <tp:rationale>
+ This corresponds to Cert_Fingerprint_Mismatch in the
+ <tp:type>Connection_Status_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:rationale>
+ This corresponds to Cert_Hostname_Mismatch in the
+ <tp:type>Connection_Status_Reason</tp:type> enum.
+ </tp:rationale>
+ </tp:docstring>
+ </tp:error>
+
+ <tp:error name="Cert.Self Signed">
+ <tp:docstring>
+ 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.
+ </tp:rationale>
+ </tp:docstring>
+ </tp:error>
+
+ <tp:error name="Cert.Invalid">
+ <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:rationale>
+ </tp:docstring>
+ </tp:error>
+
+ <tp:error name="Not Capable">
+ <tp:docstring>
+ Raised when requested functionality is unavailable due to contact
+ not having required capabilities.
+ </tp:docstring>
+ </tp:error>
<tp:copyright>Copyright (C) 2005-2008 Collabora Limited</tp:copyright>
<tp:copyright>Copyright (C) 2005-2008 Nokia Corporation</tp:copyright>
<tp:license xmlns="http://www.w3.org/1999/xhtml">
--
1.5.6.5
More information about the telepathy-commits
mailing list