[Telepathy-commits] [telepathy-spec/master] Connection_Status_Reason: document equivalent D-Bus errors
Simon McVittie
simon.mcvittie at collabora.co.uk
Mon Jan 19 09:15:50 PST 2009
Also explain that changes to Connecting or Connected SHOULD always be for
reason Requested, explain the three possibilities for Name_In_Use, and
add more whitespace.
---
spec/Connection.xml | 182 ++++++++++++++++++++++++++++++++++++++++++---------
1 files changed, 151 insertions(+), 31 deletions(-)
diff --git a/spec/Connection.xml b/spec/Connection.xml
index 55545d8..a4287e9 100644
--- a/spec/Connection.xml
+++ b/spec/Connection.xml
@@ -633,79 +633,199 @@ 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>
--
1.5.6.5
More information about the Telepathy-commits
mailing list