diff options
Diffstat (limited to 'spec/Connection.xml')
| -rw-r--r-- | spec/Connection.xml | 165 |
1 files changed, 157 insertions, 8 deletions
diff --git a/spec/Connection.xml b/spec/Connection.xml index 3109670..a694e24 100644 --- a/spec/Connection.xml +++ b/spec/Connection.xml @@ -722,7 +722,7 @@ USA.</p> 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> + <code>org.freedesktop.Telepathy.Error.<tp:error-ref>Disconnected</tp:error-ref></code>.</p> </tp:docstring> </tp:enumvalue> @@ -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"> @@ -952,7 +985,7 @@ USA.</p> <tp:type>Connection_Status_Reason</tp:type>, or may be a more specific Telepathy error (such as - <code>org.freedesktop.Telepathy.Errors.ConnectionRefused</code> + <code>org.freedesktop.Telepathy.Error.ConnectionRefused</code> for Connection_Status_Reason_Network_Error) or a protocol-specific or connection-manager-specific error in a suitable namespace. @@ -977,13 +1010,10 @@ 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>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> - <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> @@ -1020,6 +1050,125 @@ USA.</p> </tp:docstring> </tp:contact-attribute> + <method name="AddClientInterest" tp:name-for-bindings="Add_Client_Interest"> + <tp:added version="0.21.3"/> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Register a client's interest in notifications related to one or + more interfaces.</p> + + <p>Groups of notifications are identified by a token which is either + a D-Bus interface name, or a string that starts with a D-Bus + interface name. The meaning of each token is given by that D-Bus + interface, which MUST define it in its documentation.</p> + + <tp:rationale> + <p>Initially, all interests are in entire interface, but allowing + other strings allows subscription to part of an interface; for + instance, an interest in ...MailNotification/count could track + the number of messages without caring about their detailed + content.</p> + </tp:rationale> + + <p>For each token with which this method interacts, the + Connection tracks an "interest count" (like a reference count) for + each unique bus name that has called this method. When a client + calls this method, for each token, the interest count for its + unique bus name is incremented; when + <tp:member-ref>RemoveClientInterest</tp:member-ref> is called, + all interest counts for that unique bus name are decremented. + If the unique bus name leaves the bus (for instance, if the + client crashes or exits), all interest counts for that unique bus + name are set to zero.</p> + + <p>The Connection can then use these reference counts to + avoid subscribing to protocol-level notifications unless at least + one client has a non-zero interest count for the relevant + token.</p> + + <tp:rationale> + <p>This method exists to reduce memory and network overhead when + there is no active subscription.</p> + + <p>One situation where this is useful is <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Connection.Interface" + >Location</tp:dbus-ref>: on XMPP, location updates are received + over PEP. If the Connection advertises the + <code>geoloc+notify</code> capability, it will be sent location + updates for all contacts. To avoid consuming resources for this, + the connection should avoid advertising that capability until + a client has expressed an interest in contacts' locations.</p> + + <p>Another example of a protocol that benefits from this method is + the Google XMPP Mail Notification extension, which can be used + to implement <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Connection.Interface" + >MailNotification</tp:dbus-ref>. In this protocol, the CM + receives a notification that something has changed, but to get + more information, the CM must request this information. Knowing + that nobody is currently interested in this information, the CM + can avoid generating useless network traffic. Similarly, the CM + may free the list of unread messages to reduce memory overhead.</p> + </tp:rationale> + + <p>If this method is called for an interface that might require + protocol-level subscription, but the connection cannot set up + that subscription yet (for instance because the + <tp:member-ref>Status</tp:member-ref> is not Connected yet), the + Connection MUST remember the client's interest, and attempt to + subscribe to the appropriate protocol feature when this becomes + possible.</p> + + <p>Clients MAY ignore any errors raised by this method; it is intended + to be called with the reply ignored.</p> + + <tp:rationale> + <p>The only reason it could fail is if it's unimplemented, in which + case the only thing the client can usefully do is to proceed as if + it had succeeded.</p> + </tp:rationale> + </tp:docstring> + + <arg name="Tokens" type="as" direction="in"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Interfaces or parts of interfaces in which to register an + interest, represented by either a + <tp:type>DBus_Interface</tp:type>, or a string prefixed with a + <tp:type>DBus_Interface</tp:type>.</p> + + <p>If the Connection does not support one of these tokens, this + is not considered to be an error; the unsupported token is + simply ignored.</p> + </tp:docstring> + </arg> + </method> + + <method name="RemoveClientInterest" + tp:name-for-bindings="Remove_Client_Interest"> + <tp:added version="0.21.3"/> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Release an interest registered using + <tp:member-ref>AddClientInterest</tp:member-ref>. See that + method's documentation for details.</p> + + <p>Clients MAY ignore any errors raised by this method; it is intended + to be called with the reply ignored.</p> + + <tp:rationale> + <p>The only reasons it could fail are if it's unimplemented, or if + the client's reference-counting is wrong and it has tried to + remove a client interest that it did not add. In both cases, + there's nothing the client could do about it.</p> + </tp:rationale> + </tp:docstring> + + <arg name="Tokens" type="as" direction="in"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Interfaces or parts of interfaces that were previously passed to + <tp:member-ref>AddClientInterest</tp:member-ref>.</p> + </tp:docstring> + </arg> + </method> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>This models a connection to a single user account on a communication service. Its basic capability is to provide the facility to request and |