From 25579765e5fe613a494030ec33a75fd038a3d813 Mon Sep 17 00:00:00 2001 From: Simon McVittie Date: Mon, 9 Aug 2010 18:52:03 +0100 Subject: Update to spec 0.19.11 + patch 78fa43292e2425780 --- spec/Authentication_TLS_Certificate.xml | 304 +++++++++++++++++++++++ spec/Call_Content.xml | 13 + spec/Call_Stream.xml | 11 + spec/Channel_Interface_Call_State.xml | 14 ++ spec/Channel_Interface_Room.xml | 373 ++++++++++++++++++++++++++++ spec/Channel_Type_Room_List.xml | 17 +- spec/Channel_Type_Server_TLS_Connection.xml | 60 +++++ spec/Channel_Type_Text.xml | 14 +- spec/Connection.xml | 44 +++- spec/Connection_Interface_Client_Types.xml | 203 +++++++++++++++ spec/Makefile.am | 4 + spec/Protocol.xml | 65 ++++- spec/all.xml | 16 +- spec/errors.xml | 72 +++++- 14 files changed, 1186 insertions(+), 24 deletions(-) create mode 100644 spec/Authentication_TLS_Certificate.xml create mode 100644 spec/Channel_Interface_Room.xml create mode 100644 spec/Channel_Type_Server_TLS_Connection.xml create mode 100644 spec/Connection_Interface_Client_Types.xml (limited to 'spec') diff --git a/spec/Authentication_TLS_Certificate.xml b/spec/Authentication_TLS_Certificate.xml new file mode 100644 index 000000000..709ea282c --- /dev/null +++ b/spec/Authentication_TLS_Certificate.xml @@ -0,0 +1,304 @@ + + + Copyright © 2010 Collabora Limited + + 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. + +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. + +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. + + + + (draft 1) + + + This object represents a TLS certificate. + + + + +

The raw data contained in a TLS certificate.

+ +

For X.509 certificates (CertificateType + = "x509"), this MUST be in DER format, as defined by the + X.690 + ITU standard.

+ +

For PGP certificates (CertificateType + = "pgp"), this MUST be a binary OpenPGP key as defined by section 11.1 + of RFC 4880.

+ + + + + + The possible states for a TLSCertificate.DRAFT + object. + + + + + The certificate is currently waiting to be accepted or rejected. + + + + + + The certificate has been verified. + + + + + + The certificate has been rejected. + + + + + + + Possible reasons to reject a TLS certificate. + + + + + The certificate has been rejected for another reason + not listed in this enumeration. + + + + + + The certificate is not trusted. + + + + + + The certificate is expired. + + + + + + The certificate is not active yet. + + + + + + The certificate provided does not have the expected + fingerprint. + + + + + + The hostname certified does not match the provided one. + + + + + + The certificate is self-signed. + + + + + + The certificate has been revoked. + + + + + + The certificate uses an insecure cipher algorithm, or is + cryptographically weak. + + + + + + The length in bytes of the certificate, or the depth of the + certificate chain exceed the limits imposed by the crypto + library. + + + + + + + The current state of this certificate. + State change notifications happen by means of the + Accepted and + Rejected signals. + + + + + +

If the State is Rejected, + the reason why the certificate was rejected; this MAY correspond to + the RejectReason, or MAY be a more + specific D-Bus error name, perhaps implementation-specific.

+

If the State is not Rejected, + this property is not meaningful, and SHOULD be set to an empty + string.

+ + + + + +

If the State is Rejected, + additional information about why the certificate was rejected.

+

If the State is not Rejected, + this property is not meaningful and SHOULD be set to an empty + map.

+

The additional information MAY also include + one or more of the following well-known keys:

+
+
user-requested (b)
+
True if the error was due to an user-requested rejection of + the certificate; False if there was an unrecoverable error in the + verification process.
+
expected-hostname (s)
+
If the rejection reason is Hostname_Mismatch, the hostname that + the server certificate was expected to have.
+
certificate-hostname (s)
+
If the rejection reason is Hostname_Mismatch, the hostname of + the certificate that was presented. + +

For instance, if you try to connect to gmail.com but are presented + with a TLS certificate issued to evil.example.org, the error details + for Hostname_Mismatch MAY include:

+ 
+              {
+                'expected-hostname': 'gmail.com',
+                'certificate-hostname': 'evil.example.org',
+              }
+
+ +
+
debug-message (s)
+
Debugging information on the error, corresponding to the + message part of a D-Bus error message, which SHOULD NOT be + displayed to users under normal circumstances
+
+ + + + + + If the State is Rejected, the + reason why the certificate was rejected. + + Clients that do not understand the RejectError, + which may be implementation-specific, can use this property to + classify rejection reasons into common categories. + + Otherwise, this property is not meaningful, and SHOULD be set to + Unknown. + + + + + + The type of this TLS certificate (e.g. 'x509' or 'pgp'). +

This property is immutable

+ + + + + +

One or more TLS certificates forming a trust chain, each encoded as + specified by Certificate_Data.

+

The first certificate in the chain MUST be the server certificate, + followed by the issuer's certificate, followed by the issuer's issuer + and so on.

+ + + + + + The State of this certificate has changed to Accepted. + + + + + + The State of this certificate has changed to Rejected. + + + + The new value of RejectReason. + + + + + The new value of RejectError. + + + + + The new value of RejectDetails + + + + + + + Accepts this certificate, i.e. marks it as verified. + + + + + + Rejects this certificate. + + + + The new value of RejectReason. + + + + + The new value of RejectError. + + + + + The new value of RejectDetails. + + + + + + + diff --git a/spec/Call_Content.xml b/spec/Call_Content.xml index 3e585b49a..8df078b66 100644 --- a/spec/Call_Content.xml +++ b/spec/Call_Content.xml @@ -47,6 +47,19 @@ + + + +

Extra interfaces provided by this content, such as Content.Interface.Media.DRAFT or + Content.Interface.Mute.DRAFT. + This SHOULD NOT include the Content interface itself, and cannot + change once the content has been created.

+ + +

The name of the content. diff --git a/spec/Call_Stream.xml b/spec/Call_Stream.xml index dc7d78490..0fbb9c8aa 100644 --- a/spec/Call_Stream.xml +++ b/spec/Call_Stream.xml @@ -139,6 +139,17 @@ + + + +

Extra interfaces provided by this stream, such as Stream.Interface.Media.DRAFT. + This SHOULD NOT include the Stream interface itself, and cannot + change once the stream has been created.

+ + + diff --git a/spec/Channel_Interface_Call_State.xml b/spec/Channel_Interface_Call_State.xml index b569a7ffd..b0aea5915 100644 --- a/spec/Channel_Interface_Call_State.xml +++ b/spec/Channel_Interface_Call_State.xml @@ -126,6 +126,20 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. + + + + + This contact has merged this call into a conference. Note that GSM + provides a notification when the remote party merges a call into a + conference, but not when it is split out again; thus, this flag can + only indicate that the call has been part of a conference at some + point. If a GSM connection manager receives a notification that a + call has been merged into a conference a second time, it SHOULD + represent this by clearing and immediately re-setting this flag on + the remote contact. + + diff --git a/spec/Channel_Interface_Room.xml b/spec/Channel_Interface_Room.xml new file mode 100644 index 000000000..ffdf4a96d --- /dev/null +++ b/spec/Channel_Interface_Room.xml @@ -0,0 +1,373 @@ + + + + Copyright © 2010 Collabora Ltd. + Copyright © 2010 Nokia Corporation + +

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.

+ +

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.

+ +

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.

+ + + + + (draft 1) + + +

Different IM protocols use a variety of ways to name chat rooms. The + simplest example is perhaps IRC, where chat rooms have short, + persistent, human-readable string names, and are generally global + across the network. Skype chat rooms have persistent string names, so + you can leave and re-join a room, but these names are opaque unique + identifiers. MSN chat rooms are unnamed, and you can only join one by + being invited. And XMPP wins the coveted “most complicated chat rooms” + prize: chat rooms may be hosted by different servers with different DNS + names; normally they have human-readable names, except that all MUCs on + Google Talk's conference server have UUIDs as names, and XEP-0045 §10.1.4 + Requesting a Unique Room Name defines a protocol for + requesting a unique, opaque room name on the server.

+ +

This interface intends to support and differentiate these mechanisms + more clearly than the TargetHandleType + and TargetID + properties can alone. It initially contains a pair of properties used + to represent the human-readable parts of a + Room_Handle's identifier, if any. The above examples + for different protocols are represented as follows:

+ +
    +
  • The IRC channel #telepathy on Freenode is represented by a + channel with properties + TargetHandleType + = Room, + TargetID + = "#telepathy", + RoomID = "#telepathy", + Server = "", indicating + that the room has a human-readable identifier, and is not confined to + a particular server on the network. + + + Actually, IRC supports creating “local” channels specific to the + server they are created on. These channels have identifiers + starting with & rather than #. These could be + represented by setting Server + appropriately. + +
    • + +
  • A Skype group chat with opaque identifier 0xdeadbeef has + TargetHandleType + = Room, + TargetID + = "0xdeadbeef", + RoomID = "", + Server = "", indicating + that the room has an identifier but no human-readable name. +
    • + +
  • An MSN group chat has + TargetHandleType + = None, + RoomID = "", + Server = "", indicating + that the room has neither an identifier (so it cannot be re-joined + later) nor a human-readable name. +
    • + +
  • A standard Jabber multi-user chat + jdev@conference.jabber.org has + TargetHandleType + = Room, + TargetID + = "jdev@conference.jabber.org", + RoomID = "jdev", + Server = "conference.jabber.org". +
    • + +
  • A Google Talk private MUC private-chat-11111x1x-11xx-111x-1111-111x1xx11x11@groupchat.google.com has + TargetHandleType + = Room, + TargetID + = "private-chat-11111x1x-11xx-111x-1111-111x1xx11x11@groupchat.google.com", + RoomID = "", + Server = + "groupchat.google.com", indicating that the room has a + persistent identifier, no human-readable name, and is hosted by a + particular server. +
    • + +
  • Similarly, a XEP-0045 §10.1.4 uniquely-named room + lrcgsnthzvwm@conference.jabber.org has + TargetHandleType + = Room, + TargetID + = "lrcgsnthzvwm@conference.jabber.org", + RoomID = "", + Server = + "conference.jabber.org", indicating that the room has a + persistent identifier, no human-readable name, and is hosted by a + particular server. +
    • +
+ +

Requestable channel classes

+ +

If the connection supports joining text chat rooms by unique + identifier, like Skype, it should advertise a + Requestable_Channel_Class matching:

+ +
+ 
+( Fixed = { ...ChannelType: ...Text,
+            ...TargetHandleType: Room,
+          },
+  Allowed = [ ...TargetID,
+              ...TargetHandle,
+            ]
+)
+ +

Channel requests must specify either TargetID or TargetHandle.

+ +

If, like IRC, the room identifiers are also human-readable, the + RCCs should also include RoomID in Allowed_Properties:

+ +
+ 
+( Fixed = { ...ChannelType: ...Text,
+            ...TargetHandleType: Room,
+          },
+  Allowed = [ ...TargetID,
+              ...TargetHandle,
+              ...RoomID
+            ]
+),
+
+( Fixed = { ...ChannelType: ...Text
+          },
+  Allowed = [ ...RoomID,
+            ]
+)
+ +

Requests may specify the RoomID in place of + TargetID or + TargetHandle + . Note how RoomID appears + in Allowed_Properties of a different RCC because + when TargetHandleType is omitted (or is None), both + TargetHandle and + TargetID must also be omitted. + RoomID is allowed in conjuction + with + TargetID or + TargetHandle + in some situations, as explained below in the Requesting room + channels section. +

+ +

If rooms may be on different servers, Server + should also be included in the allowed properties, but + CMs MUST use a reasonable default + Server if not explicitly + specified in a channel request. The CM's default server MAY + be configurable by a connection parameter specified on a + RequestConnection call, similarly to how the + fallback conference server is specified on jabber connections in + gabble.

+ +

If the protocol supports unnamed rooms, RoomID + should be fixed to the empty string, and + TargetHandleType + should be None:

+ +
+ 
+( Fixed = { ...ChannelType: ...Text,
+            ...TargetHandleType: None,
+            ...RoomID: "",
+          },
+  Allowed = [ ]
+)
+ +

Requesting room channels

+ +

When explicitly joining a room, the CM cannot know whether the room + ID is unique or not. As a result, if this is the case, adding an + empty string RoomID into the channel + request will ensure the CM knows. For example:

+ +
+ 
+{ ...ChannelType: ...Text,
+  ...TargetHandleType: Room,
+  ...TargetID: "qwerasdfzxcv@conference.jabber.org",
+  ...RoomID: ""
+}
+ +

If RoomID features in + Allowed_Properties then the only value allowed in conjunction + with TargetID + or TargetHandle + is the empty string. Requests with conflicting + TargetID + and RoomID properties + will fail with InvalidArgument.

+ +

To create a XEP-0045 §10.1.4 uniquely-named room channel + on the conference.jabber.org server, then the following channel + request should be made:

+ +
+ 
+{ ...ChannelType: ...Text,
+  ...RoomID: ""
+  ...Server: "conference.jabber.org"
+}
+
+ +

If everything is successful, then when the channel request is + satisfied, a new channel will appear with the following properties:

+ +
+ 
+{ ...ChannelType: ...Text,
+  ...TargetHandleType: Room,
+  ...TargetID: "kajsdhkajshdfjkshdfjkhs@conference.jabber.org",
+  ...RoomID: ""
+  ...Server: "conference.jabber.org"
+}
+
+ +

The CM will have received the unique room name (kajsdhkajshdfjkshdfjkhs) + and then created a room with such a name on the said server. The empty + RoomID property shows that the room name + is not human-readable.

+ + + + + +

The human-readable identifier of a chat room. Note that if + non-empty, this property (and perhaps also + Server) should be sufficient in + a channel request to join the room. XMPP MUCs have a room name + concept which is more like a topic, except more + persistent. This D-Bus property is not this + XMPP room name, but the bit before the @ in the room jid.

+ +

This property cannot change during the lifetime of the channel. It + should appear in the Allowed_Properties of a + Requestable_Channel_Class for the connection if + rooms on this connection have human-readable names, and can be joined + by name.

+ + + + + +

For protocols with a concept of chatrooms on multiple servers with + different DNS names (like XMPP), the DNS name of the server hosting + this channel (for example, "conference.jabber.org" or + "groupchat.google.com"). For other protocols, the empty + string.

+ +

This property cannot change during the lifetime of the channel. It + should appear in the Allowed_Properties of a + Requestable_Channel_Class for the connection if + and only if non-empty values are supported.

+ + + + + + A struct representing the subject of a room channel. + + + + A human-readable description of the current subject of + conversation in the channel, similar to /topic in IRC. + + + + + A normalized contact ID representing who last modified the + subject, or the empty string if it is not known. + + + + + A unix timestamp indicating when the subject was last modified. + + + + + + +

The subject on the room such as the topic in an IRC channel, + or the room name in XMPP MUCs. In protocols which do not support + subjects (like MSN), this property should be ("", "", 0).

+ + This property replaces the subject, subject-contact, and + subject-timestamp Telepathy properties of Text channels, as Telepathy + properties are soon to be deprecated completely. + +

This property may change during the lifetime of the channel and + MUST not be included in a channel request.

+ + + + + + diff --git a/spec/Channel_Type_Room_List.xml b/spec/Channel_Type_Room_List.xml index 6d6ce310b..98f745822 100644 --- a/spec/Channel_Type_Room_List.xml +++ b/spec/Channel_Type_Room_List.xml @@ -84,7 +84,10 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.A description of the room's overall purpose
subject (s)
-
The current subject of conversation in the room
+
The current subject of conversation in the room (as would + be returned by getting the string part of the Subject property)
members (u)
The number of members in the room
@@ -94,6 +97,18 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.invite-only (b)
True if you cannot join the room, but must be invited
+ +
room-id (s)
+
The human-readable identifier of a chat room (as would be + returned by getting the RoomID property)
+ +
server (s)
+
The DNS name of the server hosting these channels (as would be + returned by getting the Server property)
 diff --git a/spec/Channel_Type_Server_TLS_Connection.xml b/spec/Channel_Type_Server_TLS_Connection.xml new file mode 100644 index 000000000..1d705c552 --- /dev/null +++ b/spec/Channel_Type_Server_TLS_Connection.xml @@ -0,0 +1,60 @@ + + + Copyright © 2010 Collabora Limited + + 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. + + 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. + + 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. + + + + (draft 1) + + + + +

A channel type that carries a TLS certificate between a server + and a client connecting to it.

+

Channels of this kind always have Requested = False, + TargetHandleType + = None and TargetHandle + = 0, and cannot be requested with methods such as CreateChannel. + Also, they SHOULD be dispatched while the + Connection + owning them is in the CONNECTING state.

+

In this case, handlers SHOULD accept or reject the certificate, using + the relevant methods on the provided object, or MAY just Close the channel before doing so, to fall + back to a non-interactive verification process done inside the CM.

+

For example, channels of this kind can pop up while a client is + connecting to an XMPP server.

+ + + + +

A TLSCertificate.DRAFT + containing the certificate chain as sent by the server, + and other relevant information.

+

This property is immutable.

+ + + + + + diff --git a/spec/Channel_Type_Text.xml b/spec/Channel_Type_Text.xml index e3cd6b98a..9cbfea21a 100644 --- a/spec/Channel_Type_Text.xml +++ b/spec/Channel_Type_Text.xml @@ -454,18 +454,28 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. A human-readable description of the current subject of conversation in - the channel, similar to /topic in IRC. + the channel, similar to /topic in IRC. This is equivalent to the + Subject property in the Room interface which will replace + this Telepathy property. A contact handle representing who last modified the subject, or 0 - if it isn't known. + if it isn't known. This is equivalent to the + Subject property in the Room interface which will replace + this Telepathy property. A unix timestamp indicating when the subject was last modified. + This is equivalent to the + Subject property in the Room interface which will replace + this Telepathy property. diff --git a/spec/Connection.xml b/spec/Connection.xml index 3109670a9..6587bb2de 100644 --- a/spec/Connection.xml +++ b/spec/Connection.xml @@ -896,7 +896,7 @@ USA.

The server's SSL certificate is self-signed.

When disconnected for this reason, the equivalent D-Bus error is - org.freedesktop.Telepathy.Error.Cert.HostnameMismatch. + org.freedesktop.Telepathy.Error.Cert.SelfSigned.

@@ -911,6 +911,39 @@ USA.

+ + + +

The server's SSL certificate has been revoked.

+ +

When disconnected for this reason, the equivalent D-Bus error is + org.freedesktop.Telepathy.Error.Cert.Revoked. +

+ + + + + +

The server's SSL certificate uses an insecure algorithm, + or is cryptographically weak.

+ +

When disconnected for this reason, the equivalent D-Bus error is + org.freedesktop.Telepathy.Error.Cert.Insecure. +

+ + + + + +

The length in bytes of the server certificate, or the depth of the + sever certificate chain exceed the limits imposed by the crypto + library.

+ +

When disconnected for this reason, the equivalent D-Bus error is + org.freedesktop.Telepathy.Error.Cert.LimitExceeded +

+ + @@ -977,13 +1010,12 @@ USA.

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
+
expected-hostname (s), certificate-hostname (s)
+
The same details defined in TLSCertificate.DRAFT.RejectDetails +
- -

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.

- diff --git a/spec/Connection_Interface_Client_Types.xml b/spec/Connection_Interface_Client_Types.xml new file mode 100644 index 000000000..879095e7c --- /dev/null +++ b/spec/Connection_Interface_Client_Types.xml @@ -0,0 +1,203 @@ + + + Copyright (C) 2010 Collabora Ltd. + +

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.

+ +

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.

+ +

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.

+ + + (as draft) + + + +

An interface on connections to support protocols which allows users to + subscribe to the client types of their contacts.

+ +

One can connect to instant messaging networks on a huge variety of + devices, from PCs, to phones to consoles. It can be useful for users + to know what kind of device a contact is using so that he or she + can decide not to send that big file or start a video chat. This + interface exposes exactly this information for clients to display.

+ +

The client types are represented in strings, using the values + + documented by the XMPP registrar with some additional types + added for other protocols. A contact can set one or more client types + so this interface returns a list of strings to denote client types + for a contact. The well-known client types to be used are:

+ +
    +
  • bot
    • +
  • console (minimal non-GUI client used on dumb terminals or + text-only screens, not a games console)
    • +
  • handheld
    • +
  • pc
    • +
  • phone
    • +
  • web
    • +
  • sms (the client is not actually an instant messaging client + but all messages sent to this contact will be delivered as SMSs)
    • +
  • game (a gaming device)
    • +
+ +

If the empty list is given as the client types, this means that + details about the contact's client types are unknown. If there are + multiple resources of a contact online at one point in time, the + client types of the most available resource will be returned. In + other words, the client types are the types of the client whose + SimplePresence we see. For example, if a contact has two + resources:

+ +
    +
  • one his phone, with presence "available", and
    • +
  • one his pc, with presence "busy",
    • +
+ +

then the methods in this interface will return an array (with + one element: "phone") as the client types as that is the more + available resource. If some time later his phone's presence + moves to "away", then the + ClientTypesUpdated signal will + notify that his client type have changed from "phone" to "pc", + because "busy" is a more available presence than "away".

+ + + + + + A mapping from contact handle to client types. + + + + A contact. + + + + + The contact's client types as documented earlier in this interface. + + + + + + + Return the client types of the given contacts, if they are + already known. If any of the given contacts' client types are + not known, request their current client types, but return + immediately without waiting for a reply; if a reply with a + non-empty client type array is later received for those + contacts, the + ClientTypesUpdated signal will + be emitted for them. + + + This method is appropriate for "lazy" client type finding, for instance + displaying the client types (if available) of everyone in your contact + list. + + + + + + The contacts whose client types should be returned or signalled. + + + + + + The contacts' client types, if already known. Contacts whose client + types are not already known are omitted from the mapping; contacts known + to have no client type information appear in the mapping with an empty + list. + + + + + + + + + + + + Return the current client types of the given contact. If necessary, make + a request to the server for up-to-date information, and wait for a + reply. + + + This method is appropriate for use in a "Contact Information..." + dialog; it can be used to show progress information (while waiting + for the method to return), and can distinguish between various error + conditions. + + + + + + The contact whose client types should be returned. + + + + + + The contact's client types. It MAY be empty, indicating that no client + type information was found. + + + + + + + + + + The requested contact does not allow the local user to see their + client type information. + + + + + + + + Emitted when a contact's client types change or become known. + + + + + The contact. + + + + + The contact's client types, or an empty list to indicate that nothing + is known about the contact's client types. + + + + + + +

The same mapping that would be returned by + GetClientTypes for this contact. + Omitted from the result if the contact's client types are not + known.

+ + + + + + diff --git a/spec/Makefile.am b/spec/Makefile.am index fb767e089..4343e06b2 100644 --- a/spec/Makefile.am +++ b/spec/Makefile.am @@ -4,6 +4,7 @@ EXTRA_DIST = \ Account_Manager.xml \ Account.xml \ all.xml \ + Authentication_TLS_Certificate.xml \ Call_Content.xml \ Call_Content_Interface_Media.xml \ Call_Content_Interface_Mute.xml \ @@ -29,6 +30,7 @@ EXTRA_DIST = \ Channel_Interface_Mergeable_Conference.xml \ Channel_Interface_Messages.xml \ Channel_Interface_Password.xml \ + Channel_Interface_Room.xml \ Channel_Interface_Service_Point.xml \ Channel_Interface_Splittable.xml \ Channel_Interface_Transfer.xml \ @@ -40,6 +42,7 @@ EXTRA_DIST = \ Channel_Type_DBus_Tube.xml \ Channel_Type_File_Transfer.xml \ Channel_Type_Room_List.xml \ + Channel_Type_Server_TLS_Connection.xml \ Channel_Type_Stream_Tube.xml \ Channel_Type_Streamed_Media.xml \ Channel_Type_Text.xml \ @@ -58,6 +61,7 @@ EXTRA_DIST = \ Connection_Interface_Balance.xml \ Connection_Interface_Capabilities.xml \ Connection_Interface_Cellular.xml \ + Connection_Interface_Client_Types.xml \ Connection_Interface_Contact_Capabilities.xml \ Connection_Interface_Contact_Groups.xml \ Connection_Interface_Contact_Info.xml \ diff --git a/spec/Protocol.xml b/spec/Protocol.xml index 91c350f58..50562c9b6 100644 --- a/spec/Protocol.xml +++ b/spec/Protocol.xml @@ -45,6 +45,32 @@ /org/freedesktop/Telepathy/ConnectionManager/salut/local_xmpp, respectively.

+ +

If the ConnectionManager has a .manager file, each + Protocol's immutable properties must be represented in that file; + the representation is described as part of the documentation for + each property. For instance, a very simple ConnectionManager with one + Protocol might be represented like this:

+ +
+[ConnectionManager]
+Interfaces=
+
+[Protocol example]
+Interfaces=
+ConnectionInterfaces=org.freedesktop.Telepathy.Connection.Interface.Requests;
+param-account=s required
+param-password=s required secret
+RequestableChannelClasses=text;
+VCardField=x-example
+EnglishName=Example
+Icon=im-example
+
+[text]
+org.freedesktop.Telepathy.Channel.ChannelType s=org.freedesktop.Telepathy.Channel.Type.Text
+org.freedesktop.Telepathy.Channel.TargetHandleType u=1
+allowed=org.freedesktop.Telepathy.Channel.TargetHandle;org.freedesktop.Telepathy.Channel.TargetID;
+
.manager file which represents a channel class.

+

The names of the groups representing channel classes are not + significant, and MUST NOT be interpreted. When writing + .manager files, authors MAY choose mnemonic group names, + generate group names mechanically (e.g. with an incrementing + integer), or use some combination of these.

+

Each group representing a channel class has a key allowed which is a list of D-Bus property names representing allowed parameters. Any other keys that do not contain @@ -152,17 +184,23 @@ .manager files.

For instance, this .manager file could represent - a simple Text-only connection manager:

+ a connection manager that supports 1-1 Text messages and + StreamedMedia audio calls:

[Protocol jabber]
 param-account=s required
 param-password=s required
-RequestableChannelClasses=text
+RequestableChannelClasses=rcc0;rcc1;
 
-[text]
+[rcc0]
 org.freedesktop.Telepathy.Channel.ChannelType s=org.freedesktop.Telepathy.Channel.Type.Text
 org.freedesktop.Telepathy.Channel.TargetHandleType u=1
 allowed=org.freedesktop.Telepathy.Channel.TargetHandle;org.freedesktop.Telepathy.Channel.TargetID;
+
+[rcc1]
+org.freedesktop.Telepathy.Channel.ChannelType s=org.freedesktop.Telepathy.Channel.Type.StreamedMedia
+org.freedesktop.Telepathy.Channel.TargetHandleType u=1
+allowed=org.freedesktop.Telepathy.Channel.TargetHandle;org.freedesktop.Telepathy.Channel.TargetID;org.freedesktop.Telepathy.Channel.Type.StreamedMedia.InitialAudio;
@@ -196,6 +234,13 @@ allowed=org.freedesktop.Telepathy.Channel.TargetHandle;org.freedesktop.Telepathy arbitrary handles/identifiers as vCard fields is a topic for future work.

+ +

Connection managers with a .manager file + MUST cache this property in the protocol's section of the + .manager file if it is non-empty, using the key + VCardField. The corresponding value + is a string, following the syntax of the "localestring" type from + the Desktop Entry Specification.

 @@ -223,6 +268,13 @@ allowed=org.freedesktop.Telepathy.Channel.TargetHandle;org.freedesktop.Telepathy

If this property's value is empty, clients MAY fall back to using the Telepathy Protocol name, possibly with its capitalization adjusted.

+ +

Connection managers with a .manager file + MUST cache this property in the protocol's section of the + .manager file if it is non-empty, using the key + EnglishName. The corresponding value + is a string, following the syntax of the "localestring" type from + the Desktop Entry Specification.

@@ -243,6 +295,13 @@ allowed=org.freedesktop.Telepathy.Channel.TargetHandle;org.freedesktop.Telepathy

If this property's value is empty, clients MAY fall back to generating a name based on the Protocol name.

+ +

Connection managers with a .manager file + MUST cache this property in the protocol's section of the + .manager file if it is non-empty, using the key + Icon. The corresponding value + is a string, following the syntax of the "localestring" type from + the Desktop Entry Specification.

diff --git a/spec/all.xml b/spec/all.xml index 9140a1f30..af6863b4b 100644 --- a/spec/all.xml +++ b/spec/all.xml @@ -3,7 +3,7 @@ xmlns:xi="http://www.w3.org/2001/XInclude"> Telepathy D-Bus Interface Specification -0.19.10 +0.19.11 Copyright © 2005-2010 Collabora Limited Copyright © 2005-2010 Nokia Corporation @@ -50,6 +50,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. + @@ -95,6 +96,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. + @@ -121,12 +123,24 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. + + + +

+ A set of objects to be used for authentication purposes, such + as TLS certificates or handshakes for negotiating end-to-end + security. +

+ + + + diff --git a/spec/errors.xml b/spec/errors.xml index 60a93c95c..e14dacbe5 100644 --- a/spec/errors.xml +++ b/spec/errors.xml @@ -182,7 +182,8 @@ represent a self-signed certificate: see the Self Signed error for that. This corresponds to Cert_Untrusted in the - Connection_Status_Reason enum, with a clarification + Connection_Status_Reason enum and to Untrusted in the + TLS_Certificate_Reject_Reason enum, with a clarification to avoid ambiguity. @@ -193,7 +194,8 @@ Raised if the server provided an expired SSL/TLS certificate. This corresponds to Cert_Expired in the - Connection_Status_Reason enum. + Connection_Status_Reason enum and to Expired in + the TLS_Certificate_Reject_Reason enum. @@ -204,7 +206,8 @@ valid at some point in the future. This corresponds to Cert_Not_Activated in the - Connection_Status_Reason enum. + Connection_Status_Reason enum and to + Not_Activated in the TLS_Certificate_Reject_Reason enum. @@ -215,18 +218,23 @@ the expected fingerprint. This corresponds to Cert_Fingerprint_Mismatch in the - Connection_Status_Reason enum. + Connection_Status_Reason enum and to + Fingerprint_Mismatch in the TLS_Certificate_Reject_Reason enum. - - Raised if the server provided an SSL/TLS certificate that did not match - its hostname. + +

Raised if the server provided an SSL/TLS certificate that did not match + its hostname.

+

You MAY be able to get more details about the expected and certified + hostnames by looking up the 'expected-hostname' and 'certificate-hostname' + keys in the details map that came together with this error.

This corresponds to Cert_Hostname_Mismatch in the - Connection_Status_Reason enum. + Connection_Status_Reason enum and to Hostname_Mismatch + in the TLS_Certificate_Reject_Reason enum. @@ -236,19 +244,61 @@ Raised if the server provided an SSL/TLS certificate that is self-signed and untrusted. - This corresponds to Cert_Hostname_Mismatch in the - Connection_Status_Reason enum. + This corresponds to Cert_Self_Signed in the + Connection_Status_Reason enum and to Self_Signed + in the TLS_Certificate_Reject_Reason enum. + + + + + + + Raised if the server provided an SSL/TLS certificate that has been + revoked. + + This corresponds to Cert_Revoked in the + Connection_Status_Reason enum and to Revoked + in the TLS_Certificate_Reject_Reason enum. + + + + + + + + Raised if the server provided an SSL/TLS certificate that uses an + insecure cipher algorithm or is cryptographically weak. + + This corresponds to Cert_Insecure in the + Connection_Status_Reason enum and to Insecure + in the TLS_Certificate_Reject_Reason enum. + Raised if the server provided an SSL/TLS certificate that is unacceptable in some way that does not have a more specific error. This corresponds to Cert_Other_Error in the - Connection_Status_Reason enum. + Connection_Status_Reason enum and to Unknown + in the TLS_Certificate_Reject_Reason enum. + + + + + + + + Raised if the length in bytes of the server certificate, or the depth of the + sever certificate chain exceed the limits imposed by the crypto + library. + + This corresponds to Cert_Limit_Exceeded in the + Connection_Status_Reason enum and to Limit_Exceeded + in the TLS_Certificate_Reject_Reason enum. -- cgit v1.2.1