From a8c3868be6a7c69925927ff03be58ee6c4823e5a Mon Sep 17 00:00:00 2001 From: Simon McVittie Date: Thu, 25 Nov 2010 12:09:15 +0000 Subject: Update to spec 0.21.5 - adjust Call example: InitialTransport is now a uint32 - add Confused, ServiceConfused errors - add codegen for Hints and related things --- spec/Account_Interface_Addressing.xml | 76 +++ spec/Call_Content_Codec_Offer.xml | 17 +- spec/Call_Content_Interface_Media.xml | 137 ++++- spec/Call_Stream_Interface_Media.xml | 51 +- spec/Channel.xml | 8 +- spec/Channel_Dispatcher.xml | 220 +++++++- spec/Channel_Dispatcher_Future.xml | 377 ------------- spec/Channel_Interface_Messages.xml | 170 ++++-- spec/Channel_Interface_SASL_Authentication.xml | 704 +++++++++++++++++++++++++ spec/Channel_Interface_Securable.xml | 78 +++ spec/Channel_Request.xml | 86 +++ spec/Channel_Request_Future.xml | 98 ---- spec/Channel_Type_Call.xml | 7 +- spec/Channel_Type_Contact_Search.xml | 29 +- spec/Channel_Type_Server_Authentication.xml | 121 +++++ spec/Channel_Type_Text.xml | 193 ++++--- spec/Client_Handler.xml | 3 +- spec/Client_Interface_Requests.xml | 4 +- spec/Connection_Interface_Contact_Info.xml | 30 ++ spec/Connection_Interface_Contact_List.xml | 29 +- spec/Connection_Interface_Power_Saving.xml | 7 +- spec/Makefile.am | 6 +- spec/Protocol_Interface_Avatars.xml | 5 +- spec/all.xml | 92 +++- spec/errors.xml | 36 ++ 25 files changed, 1884 insertions(+), 700 deletions(-) create mode 100644 spec/Account_Interface_Addressing.xml delete mode 100644 spec/Channel_Dispatcher_Future.xml create mode 100644 spec/Channel_Interface_SASL_Authentication.xml create mode 100644 spec/Channel_Interface_Securable.xml delete mode 100644 spec/Channel_Request_Future.xml create mode 100644 spec/Channel_Type_Server_Authentication.xml (limited to 'spec') diff --git a/spec/Account_Interface_Addressing.xml b/spec/Account_Interface_Addressing.xml new file mode 100644 index 000000000..4b2846b68 --- /dev/null +++ b/spec/Account_Interface_Addressing.xml @@ -0,0 +1,76 @@ + + + Copyright © 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 stable API) + +

Some accounts can be used for multiple protocols; for instance, SIP + and Skype accounts can often be used to contact the PSTN, MSN and + Yahoo accounts can contact each other, and XMPP accounts can + potentially contact many protocols via a transport.

+

However, if the user does not intend to make use of this functionality, + user interfaces can improve clarity by not displaying it: for instance, + if a user prefers to call phone numbers via a particular SIP account, + when an address book displays a contact with a phone number, it is + desirable to display a "call with SIP" button for that account, but + avoid displaying similar buttons for any other configured SIP or + Skype accounts.

+

The purpose of this interface is to allow this "for use with" information + to be recorded and retrieved.

+ + + + +

A list of fields indicating the type of URI addressing scheme + the the account should be used for (eg 'tel') indicating the + account is intended for use by applications offering a telephony + UI, or 'sip' or 'xmpp' for those protocols

+

Note that these fields signify intent, not ability: It is + entirely possible that an account which can be used for a + given URI scheme is not wanted for it by the user, and + therefore not flagged as such in this field.

+ + + + + +

Associate (or disassociate) an account with a particular + URI addressing scheme, (such as 'tel' for telephony)

+ + + + +

URI scheme to associate/disassociate the account with/from

+ + + + + +

True to associate this account with a given addressing scheme

+

False if the account should not be associated with said scheme

+ + + + + + + + diff --git a/spec/Call_Content_Codec_Offer.xml b/spec/Call_Content_Codec_Offer.xml index e0a791f36..f88143f69 100644 --- a/spec/Call_Content_Codec_Offer.xml +++ b/spec/Call_Content_Codec_Offer.xml @@ -65,16 +65,23 @@ - - A map from remote contact to the list of codecs he or she - supports. + A list of codecs the remote contact supports. + + + The contact handle that this codec offer applies to. + + + + diff --git a/spec/Call_Content_Interface_Media.xml b/spec/Call_Content_Interface_Media.xml index 24811fd62..274d8b213 100644 --- a/spec/Call_Content_Interface_Media.xml +++ b/spec/Call_Content_Interface_Media.xml @@ -36,25 +36,82 @@ in a device specific hardware way and the CM does not need to concern itself with codecs.

-

On new Call.DRAFT channels, - handlers should wait for Codec negotiation + +

When a new Call.DRAFT channel + appears, whether it was requested or not, a CodecOffer.DRAFT - objects to appear (one will either already be present, or will - appear at some point in the channel's lifetime).

+ will either be waiting in the + CodecOffer property, or will + appear at some point via the + NewCodecOffer signal.

+ +

The RemoteContactCodecs + property on the codec offer lists the codecs which are + supported by the remote contact, and so will determine the + codecs that should be proposed by the local user's streaming + implementation. An empty list means all codecs can be proposed.

+ +

For incoming calls on protocols where codecs are proposed when + starting the call (for example, Jingle), + the RemoteContactCodecs + will contain information on the codecs that have already been + proposed by the remote contact, otherwise the codec map will + be the empty list.

-

If the Call is incoming, then the codec offer's RemoteContactCodecMap - will already be filled with the codec information of the - remote contacts. Depending on the protocol, an outgoing call's +

The streaming implementation should look at the remote codec + map and the codecs known by the local user and call RemoteContactCodecMap - will either be filled with remote contact codec information, or - it will be empty. If empty, then this SHOULD be interpreted to - mean that all codecs are supported. Once a compatible list of - codecs has been decided, CodecOffer.DRAFT.Accept - should be called with the details of these codecs.

+ on the intersection of these two codec lists.

+ +

This means that in practice, outgoing calls will have a codec + offer pop up with no information in the RemoteContactCodecs, + so the local user will call Accept + with the list of all codecs supported. If this codec offer is + accepted, then CodecsChanged + will fire with the details of the codecs passed into + Accept. If + the call is incoming, then the RemoteContactCodecs + will contain details of the remote contact's codecs and the + local user will call Accept + with the codecs that both sides understand. After the codec + set is accepted, CodecsChanged + will fire to signal this change.

+ +

Protocols without codec negotiation

+ +

For protocols where the codecs are not negotiable, instead of + popping up the initial content's CodecOffer.DRAFT + object with an empty RemoteContactCodecs, + the CM should set the supported codec values to known codec + values in the said object's codec map.

+ +

Changing codecs mid-call

+ +

To update the codec list used mid-call, the + UpdateCodecs method should be + called with details of the new codec list. If this is + accepted, then CodecsChanged + will be emitted with the new codec set.

+ +

If the other side decides to update his or her codec list + during a call, a new CodecOffer.DRAFT + object will appear through + NewCodecOffer which should be + acted on as documented above.

@@ -116,11 +173,16 @@ >CodecOffer.DRAFT - + + + The contact handle that this codec offer applies to. + + + The CodecOffer.DRAFT.RemoteContactCodecMap property + >CodecOffer.DRAFT.RemoteContactCodecs property of the codec offer. @@ -167,7 +229,14 @@ - Raised when not used during an existing call to update the codec mapping. + Raised when a CodecOffer.DRAFT + object exists and is referred to in the + CodecOffer property which + should be used instead of calling this method, or before + the content's initial CodecOffer.DRAFT + object has appeared. @@ -196,23 +265,28 @@

Emission of this signal indicates that the CodecOffer property has changed to - (Offer, Codecs).

+ (Contact, Offer, Codecs).

+ + + The contact the codec offer belongs to. + + The object path of the new codec offer. This replaces any previous codec offer. - +

The CodecOffer.DRAFT.RemoteContactCodecMap property + >CodecOffer.DRAFT.RemoteContactCodecs property of the codec offer.

Having the RemoteContactCodecMap + namespace="ofdT.Call.Content.CodecOffer.DRAFT">RemoteContactCodecs property here saves a D-Bus round-trip - it shouldn't be necessary to get the property from the CodecOffer object, in practice. @@ -222,21 +296,26 @@ + type="(oua(usuua{ss}))" tp:type="Codec_Offering" access="read">

The object path to the current CodecOffer.DRAFT object, and its + >CodecOffer.DRAFT object, its + CodecOffer.DRAFT.RemoteContact and CodecOffer.DRAFT.RemoteContactCodecMap property. + >CodecOffer.DRAFT.RemoteContactCodecs properties. If the object path is "/" then there isn't an outstanding codec offer, and the mapping MUST be empty.

Having the RemoteContactCodecMap - property here saves a D-Bus round-trip - it shouldn't be - necessary to get the property from the CodecOffer object, in + namespace="ofdT.Call.Content.CodecOffer.DRAFT" + >RemoteContact and + RemoteContactCodecs + properties here saves a D-Bus round-trip - it shouldn't be + necessary to get these properties from the CodecOffer object, in practice. diff --git a/spec/Call_Stream_Interface_Media.xml b/spec/Call_Stream_Interface_Media.xml index 3d4fb1337..9e62c8744 100644 --- a/spec/Call_Stream_Interface_Media.xml +++ b/spec/Call_Stream_Interface_Media.xml @@ -27,6 +27,26 @@ [FIXME] + +

ICE restarts

+ +

If the RemoteCredentialsSet + signal is fired during a call once it has been called before + whilst setting up the call for initial use, and the + credentials have changed, then there has been an ICE + restart. In such a case, the CM SHOULD also empty the remote + candidate list in the Endpoint.DRAFT.

+ +

If the CM does an ICE restart, then the + PleaseRestartICE signal is + emitted and the streaming implementation should then call + SetCredentials again.

+ +

For more information on ICE restarts see + RFC 5245 + section 9.1.1.1

 @@ -133,7 +153,13 @@ A transport that can be used for streaming. - + + + The stream transport type is unknown or not applicable + (for streams that do not have a configurable transport). + + + Raw UDP, with or without STUN. All streaming clients are assumed to support this transport, so there is no handler capability token for @@ -143,7 +169,7 @@ interface.] - + Interactive Connectivity Establishment, as defined by RFC 5245. Note that this value covers ICE-UDP only. @@ -151,7 +177,7 @@ Media.StreamHandler interface.] - + Google Talk peer-to-peer connectivity establishment, as implemented by libjingle 0.3. @@ -159,7 +185,7 @@ interface.] - + The transport used by Windows Live Messenger 2009 or later, which resembles ICE draft 19. @@ -167,13 +193,19 @@ interface.] - + Shared memory transport, as implemented by the GStreamer shmsrc and shmsink plugins. + + + + Multicast transport. + + EndpointsChanged signal.

 + + + + Emitted when the CM does an ICE restart to notify the + streaming implementation that it should call + SetCredentials again. + + diff --git a/spec/Channel.xml b/spec/Channel.xml index b1772d7d4..11d3e509c 100644 --- a/spec/Channel.xml +++ b/spec/Channel.xml @@ -87,10 +87,10 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.

This is fixed for the lifetime of the channel, so channels which - could potentially be used to communicate with multiple contacts - (such as streamed media calls defined by their members, or ad-hoc - chatrooms like MSN switchboards) must have TargetHandleType set - to Handle_Type_None and TargetHandle set to 0.

+ could potentially be used to communicate with multiple contacts, + and do not have an identity of their own (such as a Handle_Type_Room + handle), must have TargetHandleType set to Handle_Type_None and + TargetHandle set to 0.

Unlike in the telepathy-spec 0.16 API, there is no particular uniqueness guarantee - there can be many channels with the same diff --git a/spec/Channel_Dispatcher.xml b/spec/Channel_Dispatcher.xml index 474c809f2..2dd000b40 100644 --- a/spec/Channel_Dispatcher.xml +++ b/spec/Channel_Dispatcher.xml @@ -100,6 +100,165 @@ + +

Equivalent to calling + CreateChannelWithHints with an empty + Hints parameter.

+ + + + + The + Account + for which the new channel is to be created. + + + + + +

A dictionary containing desirable properties.

+ +

This parameter is used in the same way as the corresponding + parameter to + CreateChannelWithHints.

+ + + + + +

The time at which user action occurred, or 0 if this channel + request is for some reason not involving user action.

+ +

This parameter is used in the same way as the corresponding + parameter to + CreateChannelWithHints.

+ + + + + +

Either the well-known bus name (starting with + org.freedesktop.Telepathy.Client.) + of the preferred handler for this + channel, or an empty string to indicate that any handler would be + acceptable.

+ +

This parameter is used in the same way as the corresponding + parameter to + CreateChannelWithHints.

+ + + Previously, the spec didn't say that this should disregard the + handler's filter. This has been implemented since + telepathy-mission-control 5.3.2. + + + + + + A + ChannelRequest + object. + + + + + + + The Preferred_Handler is syntactically invalid or does + not start with org.freedesktop.Telepathy.Client., + the Account does not exist, or one of the Requested_Properties + is invalid + + + + + + + + +

Equivalent to calling + EnsureChannelWithHints with an empty + Hints parameter.

+ + + + + The + Account + for which the new channel is to be created. + + + + + +

A dictionary containing desirable properties.

+ +

This parameter is used in the same way as the corresponding + parameter to + CreateChannelWithHints.

+ + + + + +

The time at which user action occurred, or 0 if this channel + request is for some reason not involving user action.

+ +

This parameter is used in the same way as the corresponding + parameter to + CreateChannelWithHints.

+ + + + + +

Either the well-known bus name (starting with + org.freedesktop.Telepathy.Client.) + of the preferred handler for this + channel, or an empty string to indicate that any handler would be + acceptable. The behaviour and rationale are the same as for the + corresponding parameter to + EnsureChannelWithHints.

+ + + + + + A + ChannelRequest + object. + + + + + + + The Preferred_Handler is syntactically invalid or does + not start with org.freedesktop.Telepathy.Client., + the Account does not exist, or one of the Requested_Properties + is invalid + + + + + + + + + Support for this method is indicated by the + SupportsRequestHints property. + Clients MUST recover from this method being unsupported by falling back + to CreateChannel. +

Start a request to create a channel. This initially just creates a ChannelRequest @@ -235,6 +394,19 @@ + + +

Additional information about the channel request, which will be + used as the value for the resulting request's Hints + property.

+ + +

See the Hints property's documentation for rationale.

+ + + + A @@ -256,7 +428,15 @@ - + + + Support for this method is indicated by the + SupportsRequestHints property. + Clients MUST recover from this method being unsupported by falling back + to EnsureChannel. +

Start a request to ensure that a channel exists, creating it if necessary. This initially just creates a

The rationale is as for CreateChannel.

+ namespace='org.freedesktop.Telepathy.ChannelDispatcher'>CreateChannelWithHints.

 @@ -311,7 +491,8 @@ request is for some reason not involving user action.

This parameter is used in the same way as the corresponding - parameter to CreateChannel.

+ parameter to + CreateChannelWithHints.

 @@ -324,8 +505,8 @@ channel, or an empty string to indicate that any handler would be acceptable. The behaviour and rationale are the same as for the corresponding parameter to - CreateChannel, except as noted - here.

+ CreateChannelWithHints, except + as noted here.

If any new channels are created in response to this request, the channel dispatcher SHOULD dispatch as many as @@ -359,6 +540,14 @@ + + + Additional information about the channel request, which will be used + as the value for the resulting request's Hints + property. + + A @@ -380,6 +569,27 @@ + + + + If True, the channel dispatcher is new enough to support + CreateChannelWithHints and + EnsureChannelWithHints, in addition + to the older CreateChannel + and EnsureChannel + methods, and also new enough to emit SucceededWithChannel + before the older Succeeded signal. + If False or missing, only the metadata-less + variants are supported. + + + diff --git a/spec/Channel_Dispatcher_Future.xml b/spec/Channel_Dispatcher_Future.xml deleted file mode 100644 index 701b42470..000000000 --- a/spec/Channel_Dispatcher_Future.xml +++ /dev/null @@ -1,377 +0,0 @@ - - - - Copyright © 2008-2010 Collabora Ltd. - Copyright © 2008-2009 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.

- - - - - - - -

This interface contains functionality which we intend to incorporate - into the ChannelDispatcher - interface in future. It should be considered to - be conceptually part of the core ChannelDispatcher interface, but without - API or ABI guarantees.

- - - - - Support for this method is indicated by the - SupportsRequestHints property. - Clients MUST recover from this method being unsupported by falling back - to CreateChannel. - - -

Start a request to create a channel. This initially just creates a - ChannelRequest - object, which can be used to continue the request and track its - success or failure.

- - -

The request can take a long time - in the worst case, the - channel dispatcher has to ask the account manager to put the - account online, the account manager has to ask the operating - system to obtain an Internet connection, and the operating - system has to ask the user whether to activate an Internet - connection using an on-demand mechanism like dialup.

- -

This means that using a single D-Bus method call and response - to represent the whole request will tend to lead to that call - timing out, which is not the behaviour we want.

- - -

If this method is called for an Account that is disabled, invalid - or otherwise unusable, no error is signalled until - ChannelRequest.Proceed - is called, at which point - ChannelRequest.Failed - is emitted with an appropriate error.

- - -

This means there's only one code path for errors, apart from - InvalidArgument for "that request makes no sense".

- -

It also means that the request will proceed if the account is - enabled after calling CreateChannel, but before calling - Proceed.

- - - - - - The - Account - for which the new channel is to be created. - - - - - -

A dictionary containing desirable properties. This has the same - semantics as the corresponding parameter to - Connection.Interface.Requests.CreateChannel. -

- -

Certain properties will not necessarily make sense in this - dictionary: for instance, - TargetHandle - can only be given if the requester is able to interact with a - Connection - to the desired account.

- - - - - -

The time at which user action occurred, or 0 if this channel - request is for some reason not involving user action. - The UserActionTime - property will be set to this value, and it will eventually be - passed as the User_Action_Time parameter of HandleChannels.

- - - - - -

Either the well-known bus name (starting with - org.freedesktop.Telepathy.Client.) - of the preferred handler for this - channel, or an empty string to indicate that any handler would be - acceptable. The channel dispatcher SHOULD dispatch as many as - possible of the resulting channels (ideally, all of them) - to that handler—irrespective of whether that handler's HandlerChannelFilter - matches the channel—and SHOULD remember the preferred handler - so it can try to dispatch subsequent channels in the same bundle - to the same handler.

- - -

This must be the well-known bus name, not the unique name, - to ensure that all handlers do indeed have the Client API, - and the Client object on the handler can be located easily.

- -

This is partly so the channel dispatcher can call - HandleChannels - on it, and partly so the channel dispatcher - can recover state if it crashes and is restarted.

- -

The filter should be disregarded for ease of use of this - interface: clients will usually use this argument to request - channels be sent to themself, and this should trump the filter - not matching. This also allows a client to become the handler - for a channel produced by one of its own requests, while not - being a candidate to handle other channels of that type.

- - -

If this is a well-known bus name and the handler has the - Requests interface, the channel dispatcher SHOULD - call AddRequest - on that Handler after this method has returned.

- - -

This ordering allows a Handler which calls CreateChannel with - itself as the preferred handler to associate the call to - AddRequest with that call.

- - -

This is copied to the ChannelRequest that is returned, - as the PreferredHandler - property.

- - - - Previously, the spec didn't say that this should disregard the - handler's filter. This has been implemented since - telepathy-mission-control 5.3.2. - - - - - -

Additional information about the channel request, which will be - used as the value for the resulting request's Hints - property, but will not otherwise be interpreted by the Channel - Dispatcher.

- - -

See the Hints property's documentation for rationale.

- - - - - - - A - ChannelRequest - object. - - - - - - - The Preferred_Handler is syntactically invalid or does - not start with org.freedesktop.Telepathy.Client., - the Account does not exist, or one of the Requested_Properties - is invalid - - - - - - - - - Support for this method is indicated by the - SupportsRequestHints property. - Clients MUST recover from this method being unsupported by falling back - to EnsureChannel. - - -

Start a request to ensure that a channel exists, creating it if - necessary. This initially just creates a ChannelRequest - object, which can be used to continue the request and track its - success or failure.

- -

If this method is called for an Account that is disabled, invalid - or otherwise unusable, no error is signalled until - ChannelRequest.Proceed - is called, at which point - ChannelRequest.Failed - is emitted with an appropriate error.

- - -

The rationale is as for CreateChannel.

- - - - - - The - Account - for which the new channel is to be created. - - - - - -

A dictionary containing desirable properties. This has the same - semantics as the corresponding parameter to - Connection.Interface.Requests.EnsureChannel. -

- -

Certain properties will not necessarily make sense in this - dictionary: for instance, - TargetHandle - can only be given if the requester is able to interact with a - Connection - to the desired account.

- - - - - -

The time at which user action occurred, or 0 if this channel - request is for some reason not involving user action.

- -

This parameter is used in the same way as the corresponding - parameter to - CreateChannelWithHints.

- - - - - -

Either the well-known bus name (starting with - org.freedesktop.Telepathy.Client.) - of the preferred handler for this - channel, or an empty string to indicate that any handler would be - acceptable. The behaviour and rationale are the same as for the - corresponding parameter to - CreateChannelWithHints, except - as noted here.

- -

If any new channels are created in response to this - request, the channel dispatcher SHOULD dispatch as many as - possible of the resulting channels (ideally, all of them) - to that handler, and SHOULD remember the preferred handler - so it can try to dispatch subsequent channels in the same bundle - to the same handler. If the requested channel already exists (that - is, Connection.Interface.Requests.EnsureChannel - returns Yours=False) then the channel dispatcher - SHOULD re-dispatch the channel to its existing handler, and MUST - NOT dispatch it to this client (unless it is the existing handler); - the request is still deemed to have succeeded in this case.

- - -

An address book application, for example, might call EnsureChannel - to ensure that a text channel with a particular contact is - displayed to the user; it does not care whether a new channel was - made. An IM client might call EnsureChannel - in response to the user double-clicking an entry in the contact - list, with itself as the Preferred_Handler; if the - user already has a conversation with that contact in another - application, they would expect the existing window to be - presented, rather than their double-click leading to an error - message. So the request should succeed, even if its - Preferred_Handler is not used.

- - - - - - - - Additional information about the channel request, which will be used - as the value for the resulting request's Hints - property. - - - - - A - ChannelRequest - object. - - - - - - - The Preferred_Handler is syntactically invalid or does - not start with org.freedesktop.Telepathy.Client., - the Account does not exist, or one of the Requested_Properties - is invalid - - - - - - - - - - If True, the channel dispatcher is new enough to support - CreateChannelWithHints and - EnsureChannelWithHints, in addition - to the older CreateChannel - and EnsureChannel. - methods. If False or missing, only the metadata-less - variants are supported. - - - - - - diff --git a/spec/Channel_Interface_Messages.xml b/spec/Channel_Interface_Messages.xml index 0eeee39e2..d773411eb 100644 --- a/spec/Channel_Interface_Messages.xml +++ b/spec/Channel_Interface_Messages.xml @@ -104,6 +104,8 @@ USA.

This list MUST NOT be empty, since all Messages implementations MUST accept messages containing a single "text/plain" part.

+

Items in this list MUST be normalized to lower-case.

+

Some examples of how this property interacts with the MessagePartSupportFlags:

@@ -142,6 +144,20 @@ USA.

+ + + This supersedes GetMessageTypes; fall back to that method for + compatibility with older connection managers. + + +

A list of message types which may be sent on this channel.

+ + + image.

+

Connection managers, clients and extensions to this specification + SHOULD NOT include Handles as values in a + Message_Part, except for message-sender in the + header.

+ + +

Reference-counting handles in clients becomes problematic if + the channel proxy cannot know whether particular map values + are handles or not.

+ +

Example messages

A rich-text message, with an embedded image, might be represented @@ -491,6 +518,12 @@ USA.

+ + Removed protocol-token—which had never been implemented—and + respecified message-token not to have unimplementable + uniqueness guarantees. + +

Well-known keys for the first Message_Part of a message, which contains metadata about the message as a whole, along @@ -499,39 +532,37 @@ USA.

one or the other.

-
message-token (s)
-
-

An opaque, globally-unique identifier for the entire message. - This MAY be treated as if it were a MIME Message-ID, e.g. for - the mid: and cid: URI schemes. If omitted, there is no suitable - token; the protocol-token key SHOULD be provided if the protocol - identifies messages in some less unique way.

-
- -
protocol-token (s - Protocol_Message_Token)
+
message-token (s - + Protocol_Message_Token) +
-

An opaque token for the entire message, with whatever uniqueness - guarantee is provided by the underlying protocol. As described - for the Protocol_Message_Token type, this token is not - guaranteed to be unique between contacts, or even within the - scope of a Channel.

- - -

In practice, in most protocols there is no token with the - uniqueness guarantees demanded for message-token; the - definition of message-token was inappropriate, but must now - be preserved for the benefit of clients that rely on it, at - least until Telepathy breaks backwards compatibility.

- - -

The message-token and protocol-token SHOULD NOT both be present; - clients requiring an identifier with the semantics of the - protocol-token SHOULD look for the message-token first, falling - back to the protocol-token.

+

An opaque identifier for the message, as used by the + underlying protocol. For outgoing messages, this SHOULD be + globally unique; for incoming messages, this is not + guaranteed to uniquely identify a message, even within the + scope of a single channel or contact; the only guarantee + made is that two messages with different message-token + headers are different messages.

+ +

Clients wishing to determine whether a new message with the + scrollback header matches a previously-logged message + with the same message-token SHOULD compare the + message's sender, contents, message-sent or + message-received timestamp, etc. Note that, in XMPP, + the server only supplies a timestamp for scrollback messages, + not for messages received while you are in a room; thus, + non-scrollback messages will lack a message-sent + timestamp.

-

This is for compatibility with CMs older than the - protocol-token key.

+

In practice, most protocols do not provide globally-unique + identifiers for messages. Connection managers, being + stateless, do not have the necessary information — namely, IM + logs — to generate reliable unique tokens for messages.

+ +

For instance, some XMPP clients (including Gabble) stamp + messages they send with unique identifiers, but others number + outgoing messages in a conversation from 1 upwards.
@@ -549,6 +580,13 @@ USA.

The contact who sent the message. If 0 or omitted, the contact who sent the message could not be determined.
+
message-sender-id (s)
+
The identifier of the contact who sent the message, + i.e. the result of calling InspectHandles + on message-sender. If omitted, clients MUST + fall back to looking at message-sender.
+
sender-nickname (s)
The nickname chosen by the sender of the message, which can be different for each message in a conversation.
@@ -601,7 +639,8 @@ USA.

does not make sense on outgoing messages, and SHOULD NOT appear there.
- + + @@ -652,6 +691,12 @@ USA.

Clients MUST ignore parts without a 'content-type' key, which are reserved for future expansion.

+ +

When sending messages, clients SHOULD normalize the + content-type to lower case, but connection managers SHOULD NOT + rely on this. When signalling sent or received messages, + connection managers MUST normalize the content-type to lower + case.

lang (s)
@@ -703,16 +748,19 @@ USA.

needs-retrieval (b)
If false or omitted, the connection manager already holds this part in memory. If present and true, - this part will be retrieved on demand (like MIME's - message/external-body), so clients should expect retrieval to - take time; if this specification is later extended to provide a - streaming version of GetPendingMessageContent, clients should - use it for parts with this flag.
+ this part must be retrieved on demand (like MIME's + message/external-body) by a mechanism to be defined later. + + The mechanism was meant to be + GetPendingMessageContent, but + that didn't work out. It's worth leaving the header in in + preparation for a future mechanism. + +
truncated (b)
-
The content available via the 'content' key or - GetPendingMessageContent has been truncated by the server - or connection manager (equivalent to +
The content available via the 'content' key has been truncated + by the server or connection manager (equivalent to Channel_Text_Message_Flag_Truncated in the Text interface).
@@ -826,20 +874,6 @@ USA.

the sender. This is sometimes the only way to match it against the sent message, so we include it here. - -

Unlike in the Messages interface, content not visible - in the value for this key cannot be retrieved by another - means, so the connection manager SHOULD be more - aggressive about including (possibly truncated) message - content in the 'content' key.

- - - The Messages interface needs to allow all content to be - retrieved, but in this interface, the content we provide is - merely a hint; so some is better than none, and it doesn't - seem worth providing an API as complex as Messages' - GetPendingMessageContent for the echoed message. - @@ -848,6 +882,11 @@ USA.

+ + This type is only used by + GetPendingMessageContent, which is + unimplemented and deprecated. + The index of a message part within a message. @@ -856,6 +895,11 @@ USA.

+ + This structure is only used by + GetPendingMessageContent, which is + unimplemented and deprecated. + A mapping from message part indexes to their content, as returned by GetPendingMessageContent. @@ -888,7 +932,7 @@ USA.

is no particular identification for a message.

CM implementations SHOULD use an identifier expected to be unique, - such as a UUID, if possible.

+ such as a UUID, for outgoing messages (if possible).

Some protocols can only track a limited number of messages in a small message-ID space (SMS messages are identified by a single @@ -946,6 +990,16 @@ USA.

If this method fails, message submission to the server has failed and no signal on this interface (or the Text interface) is emitted.

+ +

If this method succeeds, message submission to the server has + succeeded, but the message has not necessarily reached its intended + recipient. If a delivery failure is detected later, this is + signalled by receiving a message whose message-type + header maps to + Channel_Text_Message_Type_Delivery_Report. + Similarly, if delivery is detected to have been successful + (which is not possible in all protocols), a successful delivery + report will be signalled.

 + + This method has never been implemented, and in any case would have been + impossible to use correctly when multiple clients (such as a logger and + the handler) are interested in a text channel. See freedesktop.org + bug #26417 for more details. + Retrieve the content of one or more parts of a pending message. Note that this function may take a considerable amount of time diff --git a/spec/Channel_Interface_SASL_Authentication.xml b/spec/Channel_Interface_SASL_Authentication.xml new file mode 100644 index 000000000..38568b1dd --- /dev/null +++ b/spec/Channel_Interface_SASL_Authentication.xml @@ -0,0 +1,704 @@ + + + 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.

+ + + (as stable API) + + +

A channel interface for SASL authentication, + as defined by + RFC 4422. + When this interface appears on a ServerAuthentication + channel, it represents authentication with the server. In future, + it could also be used to authenticate with secondary services, + or even to authenticate end-to-end connections with contacts. As a result, + this interface does not REQUIRE ServerAuthentication to allow for a potential future + Channel.Type.PeerAuthentication interface.

+ +

In any protocol that requires a password, the connection manager can + use this channel to let a user interface carry out a simple SASL-like + handshake with it, as a way to get the user's credentials + interactively. This can be used to connect to protocols that may + require a password, without requiring that the password is saved in + the Account.Parameters.

+ +

In some protocols, such as XMPP, authentication with the server + is also carried out using SASL. In these protocols, a channel with this + interface can provide a simple 1:1 mapping of the SASL negotiations + taking place in the protocol, allowing more advanced clients to + perform authentication via SASL mechanisms not known to the + connection manager.

+ + +

By providing SASL directly when the protocol supports it, we can + use mechanisms like Kerberos or Google's X-GOOGLE-TOKEN + without specific support in the connection manager.

+ + +

For channels managed by a + ChannelDispatcher, + only the channel's Handler may call the + methods on this interface. Other clients MAY observe the + authentication process by watching its signals and properties.

+ + +

There can only be one Handler, which is a good fit for SASL's + 1-1 conversation between a client and a server.

+ + + + + +

A SASL mechanism, as defined by + RFC 4422 + and registered in + the + IANA registry of SASL mechanisms, or an unregistered + SASL mechanism such as X-GOOGLE-TOKEN used in the + same contexts.

+ +

As a special case, pseudo-mechanisms starting with + X-TELEPATHY- are defined by this specification. + Use of these pseudo-mechanisms indicates that the user's credentials + are to be passed to the connection manager, which will then use + them for authentication with the service, either by implementing + the client side of some SASL mechanisms itself or by using a + non-SASL protocol. The only such pseudo-mechanism currently + defined is X-TELEPATHY-PASSWORD.

+ +

The X-TELEPATHY-PASSWORD mechanism is extremely + simple:

+ +
    +
  • The client MUST call + StartMechanismWithData, with + Initial_Data set to the password encoded in UTF-8. + For simplicity, calling StartMechanism + followed by calling Respond is not + allowed in this mechanism.
    • + +
  • The connection manager uses the password, together with + authentication details from the Connection parameters, to + authenticate itself to the server.
    • + +
  • When the connection manager finishes its attempt to authenticate + to the server, the channel's state changes to + either SASL_Status_Server_Succeeded or + SASL_Status_Server_Failed as appropriate.
    • +
+ + + + + +

The SASL mechanisms as offered by the server, plus any + pseudo-SASL mechanisms supported by the connection manager for + credentials transfer. For instance, in a protocol that + natively uses SASL (like XMPP), this might be + [ "X-TELEPATHY-PASSWORD", "PLAIN", "DIGEST-MD5", + "SCRAM-SHA-1" ].

+ +

To make it possible to implement a very simple password-querying + user interface without knowledge of any particular SASL mechanism, + implementations of this interface MUST implement the + pseudo-mechanism X-TELEPATHY-PASSWORD, unless none + of the available mechanisms use a password at all.

+ + + + + +

If true, StartMechanismWithData + can be expected to work for SASL mechanisms not starting with + X-TELEPATHY- (this is the case in most, but not all, + protocols). If false, StartMechanism + must be used instead.

+ +

This property does not affect the X-TELEPATHY- + pseudo-mechanisms such as X-TELEPATHY-PASSWORD, + which can use + StartMechanismWithData regardless + of the value of this property.

+ + + + + +

If true, StartMechanism and (if + supported) StartMechanismWithData + can be expected to work when in one of the Failed states. If + false, the only thing you can do after failure is to close the + channel.

+ + +

Retrying isn't required to work, although some protocols and + implementations allow it.

+ + + + + + + The current status of this channel. + Change notification is via the + SASLStatusChanged signal. + + + + + +

The reason for the SASLStatus, or + an empty string if the state is neither + Server_Failed nor Client_Failed.

+ +

In particular, an ordinary authentication failure (as would + be produced for an incorrect password) SHOULD be represented by + AuthenticationFailed, + cancellation by the user's request SHOULD be represented + by Cancelled, and + cancellation by a local process due to inconsistent or invalid + challenges from the server SHOULD be represented by + ServiceConfused.

+ +

If this interface appears on a ServerAuthentication + channel, and connection to the server fails with an authentication + failure, this error code SHOULD be copied into the + Connection.ConnectionError + signal.

+ + + + + +

If SASLError is non-empty, + any additional information about the last + disconnection; otherwise, the empty map. The keys and values are + the same as for the second argument of + Connection.ConnectionError.

+ +

If this interface appears on a ServerAuthentication + channel, and connection to the server fails with an authentication + failure, these details SHOULD be copied into the + Connection.ConnectionError + signal.

+ + + + + +

The identity for which authorization is being attempted, + typically the 'account' from the RequestConnection + parameters, normalized and formatted according to the + conventions used for SASL in this protocol.

+ + +

The normalization used for SASL might not be the same + normalization used elsewhere: for instance, in a protocol + with email-like identifiers such as XMPP or SIP, the user + "juliet@example.com" might have to authenticate to the + example.com server via SASL PLAIN as "juliet".

+ + +

This is usually achieved by using the authorization identity for + authentication, but an advanced Handler could offer the option + to authenticate under a different identity.

+ +

The terminology used here is that the authorization identity + is who you want to act as, and the authentication identity is + used to prove that you may do so. For instance, if Juliet is + authorized to access a role account, "sysadmin@example.com", + and act on its behalf, it might be possible to authenticate + as "juliet@example.com" with her own password, but request to + be authorized as "sysadmin@example.com" instead of her own + account. See + RFC + 4422 §3.4.1 for more details.

+ + +

In SASL the authorization identity is normally guessed from + the authentication identity, but the information available + to the connection manager is the identity for which + authorization is required, such as the desired JID in XMPP, + so that's what we signal to UIs; it's up to the UI to + choose whether to authenticate as the authorization identity + or some other identity.

+ +

As a concrete example, the "sysadmin" XMPP account mentioned + above would have { 'account': 'sysadmin@example.com' } + in its Parameters, and this property would also be + 'sysadmin@example.com'. A simple Handler would + merely prompt for sysadmin@example.com's password, + and use that JID as both the authorization and authentication + identity, which might result in SASL PLAIN authentication with the + initial response + '\000sysadmin@example.com\000root'.

+ +

A more advanced Handler might also ask for an authentication + identity, defaulting to 'sysadmin@example.com'; if Juliet + provided authentication identity 'juliet@example.com' and + password 'romeo', the Handler might perform SASL PLAIN + authentication using the initial response + 'sysadmin@example.com\000juliet@example.com\000romeo'.

+ + + + + + +

The default username for use with SASL mechanisms that deal + with a "simple username" (as defined in RFC 4422). If + such a SASL mechanism is in use, clients SHOULD default to + using the DefaultUsername; also, if the client uses + the DefaultUsername, it SHOULD assume that the authorization + identity AuthorizationIdentity + will be derived from it by the server.

+ + +

In XMPP, + servers typically expect "user@example.com" to + authenticate with username "user"; this was a SHOULD in RFC 3920.

+ +

3920bis + weakens that SHOULD to "in the absence of local information + provided by the server, an XMPP client SHOULD assume that + the authentication identity for such a SASL mechanism is the + combination of a user name and password, where the simple + user name is the localpart of the user's JID".

+ + +

For example, in the simple case, if the user connects with + RequestConnection({ + account: "user@example.com" }) and use PLAIN with + password "password", he or she should authenticate like so: + "\0user\0password" and the channel will look like + this:

+ +
{ "...DefaultUsername": "user",
+  "...AuthorizationIdentity": "user@example.com }
+
+ +

In the complex case, if the same user is using his or her + sysadmin powers to log in as the "announcements" role address, + he or she would connect with RequestConnection({ + account: "announcements@example.com" }) and the SASL + channel would look like this:

+ +
{ "...DefaultUsername": "announcements",
+  "...AuthorizationIdentity": "announcements@example.com }
+
+ +

A sufficiently elaborate UI could give the opportunity + to override the username from "announcements" to "user". + The user's simple username is still "user", and the password is + still "password", but this time he or she is trying to authorize + to act as announcements@example.com, so the UI would + have to perform SASL PLAIN with this string: + "announcements@example.com\0user\0password", where + "announcements@example.com" is the + AuthorizationIdentity.

+ + + + + +

The default realm (as defined in + RFC + 2831) to use for authentication, if the server does not + supply one.

+ + +

The server is not required to provide a realm; if it doesn't, + the client is expected to ask the user or provide a sensible + default, typically the requested DNS name of the server. + In some implementations of DIGEST-MD5, the + server does not specify a realm, but expects that the client + will choose a particular default, and authentication will + fail if the client's default is different. Connection + managers for protocols where this occurs are more easily able + to work around these implementations than a generic client + would be.

+ + + + + + + + The chosen mechanism. + + + +

Start an authentication try using Mechanism, without + sending initial data (an "initial response" as defined in RFC + 4422).

+ + +

This method is appropriate for mechanisms where the client + cannot send anything until it receives a challenge from the + server, such as + DIGEST-MD5 + in "initial authentication" mode.

+ + + + + + + The channel is not in a state where starting authentication makes + sense (i.e. SASL_Status_Not_Started, or (if + CanTryAgain is true) + SASL_Status_Server_Failed or + SASL_Status_Client_Failed). You should call + AbortSASL and wait for + SASL_Status_Client_Failed before starting another attempt. + + + + + + The server or connection manager doesn't implement the given + SASL mechanism. Choose a SASL mechanism from + AvailableMechanisms, or abort + authentication if none of them are suitable. + + + + + + + + + The chosen mechanism. + + + + + Initial data (an "initial response" in RFC 4422's terminology) to send + with the mechanism. + + + +

Start an authentication try using Mechanism, and send + Initial_Data as the "initial response" defined in + RFC 4422 + §3.3.

+ + +

This method is appropriate for mechanisms where the client may + send data first, such as PLAIN, or must send data + first, such as + DIGEST-MD5 + in "subsequent authentication" mode.

+ +

Having two methods allows any mechanism where it makes a difference + to distinguish between the absence of an initial response + (StartMechanism) and a zero-byte + initial response (StartMechanismWithData, with Initial_Data + empty).

+ + +

If the HasInitialData + property is false, this indicates that the underlying protocol + does not make it possible to send initial data. In such protocols, + this method may only be used for the X-TELEPATHY- + pseudo-mechanisms (such as X-TELEPATHY-PASSWORD), + and will fail if used with an ordinary SASL mechanism.

+ + +

For instance, the IRC SASL extension implemented in Charybdis and + Atheme does not support initial data - the first message in the + exchange only carries the mechanism. This is significant if using + DIGEST-MD5, + which cannot be used in the faster "subsequent authentication" + mode on a protocol not supporting initial data.

+ + + + + + + The channel is not in a state where starting authentication makes + sense (i.e. SASL_Status_Not_Started, or (if + CanTryAgain is true) + SASL_Status_Server_Failed or + SASL_Status_Client_Failed). You should call + AbortSASL and wait for + SASL_Status_Client_Failed before starting another attempt. + + + + + + The server or connection manager doesn't implement the given + SASL mechanism (choose one from + AvailableMechanisms, or abort + authentication if none of them are suitable), or doesn't allow + initial data to be sent (as indicated by + HasInitialData; call + StartMechanism instead). + + + + + + + + + The response data. + + + +

Send a response to the the last challenge received via + NewChallenge.

+ + + + + + Either the state is not In_Progress, or no challenge has been + received yet, or you have already responded to the last challenge. + + + + + + + + +

If the channel's status is SASL_Status_Server_Succeeded, + this method confirms successful authentication and advances + the status of the channel to SASL_Status_Succeeded.

+ +

If the channel's status is SASL_Status_In_Progress, calling this + method indicates that the last + NewChallenge signal was in fact + additional data sent after a successful SASL negotiation, and + declares that from the client's point of view, authentication + was successful. This advances the state of the channel to + SASL_Status_Client_Accepted.

+ +

In mechanisms where the server authenticates itself to the client, + calling this method indicates that the client considers this to have + been successful. In the case of ServerAuthentication + channels, this means that the connection manager MAY continue to + connect, and MAY advance the Connection.Status to Connected.

+ + + + + + Either the state is neither In_Progress nor Server_Succeeded, or no + challenge has been received yet, or you have already responded to + the last challenge. + + + + + + + + + + Reason for abort. + + + + + Debug message for abort. + + + +

Abort the current authentication try.

+ +

If the current status is SASL_Status_Server_Failed or + SASL_Status_Client_Failed, this method returns successfully, but has + no further effect. If the current status is SASL_Status_Succeeded + or SASL_Status_Client_Accepted then NotAvailable is raised. + Otherwise, it changes the channel's state to + SASL_Status_Client_Failed, with an appropriate error name and + reason code.

+ + + + + The current state is either Succeeded or Client_Accepted. + + + + + + + + Emitted when the status of the channel changes. + + + + The new value of SASLStatus. + + + + + The new value of SASLError. + + + + + The new value of SASLErrorDetails. + + + + + + +

Emitted when a new challenge is received from the server, or when + a message indicating successful authentication and containing + additional data is received from the server.

+ +

When the channel's handler is ready to proceed, it should respond + to the challenge by calling Respond, + or respond to the additional data by calling + AcceptSASL. Alternatively, it may call + AbortSASL to abort authentication.

+ + + + The challenge data or additional data from the server. + + + + + + +

A reason why SASL authentication was aborted by the client.

+ + + + + The server sent an invalid challenge or data. + + + + + The user aborted the authentication. + + + + + + + + The initial state. The Handler SHOULD either + call AbortSASL, or connect to the + NewChallenge signal then call + StartMechanism or + StartMechanismWithData. + + + + + The challenge/response exchange is in progress. The Handler SHOULD + call either Respond or + AcceptSASL exactly once per emission + of NewChallenge, or call + AbortSASL at any time. + + + + + The server has indicated successful authentication, and the + connection manager is waiting for confirmation from the Handler. + The Handler must call either AcceptSASL or + AbortSASL to indicate whether it + considers authentication to have been successful. + + + + + The Handler has indicated successful authentication, and the + connection manager is waiting for confirmation from the server. + The state will progress to either Succeeded or Server_Failed when + confirmation is received. + + + + + Everyone is happy (the server sent success, and the client has called + AcceptSASL). Connection to the server + will proceed as soon as this state is reached. The Handler SHOULD + call Close + to close the channel. + + + + + The server has indicated an authentication failure. + If CanTryAgain is true, + the client may try to authenticate again, by calling + StartMechanism or + StartMechanismWithData again. + Otherwise, it should give up completely, by calling Close + on the channel. + + + + + The client has indicated an authentication failure. The + possible actions are the same as for Server_Failed. + + + + + + + diff --git a/spec/Channel_Interface_Securable.xml b/spec/Channel_Interface_Securable.xml new file mode 100644 index 000000000..d9d971394 --- /dev/null +++ b/spec/Channel_Interface_Securable.xml @@ -0,0 +1,78 @@ + + + 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 stable API + + + +

This interface exists to expose security information about + Channels. The two + properties are sometimes immutable and can be used to make + decisions on how cautious to be about transferring sensitive + data. The special case of ServerAuthentication + channels is one example of where the two properties are + immutable.

+ +

For example, clients MAY use these properties to decide + whether the PLAIN mechanism is acceptable for a + SASLAuthentication + channel.

+ + + + +

True if this channel occurs over an encrypted + connection. This does not imply that steps + have been taken to avoid man-in-the-middle attacks.

+ + +

For future support for RFC 5056 Channel + Binding it is desirable to be able to use some SASL + mechanisms over an encrypted connection to an unverified peer, + which can prove that it is the desired destination during + the SASL negotiation.

+ + + + + + +

True if this channel occurs over a connection that is + protected against tampering, and has been verified to be with + the desired destination: for instance, one where TLS was + previously negotiated, and the TLS certificate has been + verified against a configured certificate authority or + accepted by the user.

+ + + + + + diff --git a/spec/Channel_Request.xml b/spec/Channel_Request.xml index 1d59eb874..1a9c397ef 100644 --- a/spec/Channel_Request.xml +++ b/spec/Channel_Request.xml @@ -209,6 +209,92 @@ + + + +

A dictionary of metadata provided by the channel + requester, which the handler and other clients MAY choose to + interpret. Currently no standard keys are defined; clients MAY + choose to use platform-specific keys for their own purposes, but MUST + ignore unknown keys and MUST cope with expected keys being + missing. Clients SHOULD namespace hint names by having them + start with a reversed domain name, in the same way as D-Bus + interface names.

+ + This property might be used to pass a contact ID for a + telephone number shared between two contacts from the address book to + the call UI, so that if you try to call “Mum”, the call UI knows this + rather than having to guess or show “Calling Mum or Dad”. The format + of these contact IDs would be platform-specific, so we leave the + definition of the dictionary entry up to the platform in question. + But third-party channel requesters might not include the contact ID, + so the call UI has to be able to deal with it not being + there. + +

The channel dispatcher does not currently interpret any of these + hints: they are solely for communication between cooperating + clients. If hints that do affect the channel dispatcher are added in + future, their names will start with an appropriate reversed domain + name (e.g. org.freedesktop.Telepathy for hints defined + by this specification, or an appropriate vendor name for third-party + plugins).

+ +

This property may be set when the channel request is created, and + can never change. Since it is immutable, it SHOULD be included in the + dictionary of properties passed to AddRequest + by the ChannelDispatcher.

+ + + + + + +

Variant of the Succeeded signal + allowing to get the channel which has been created.

+ +

This signal MUST be emitted if the + ChannelDispatcher's + SupportsRequestHints + property is true. If supported, it MUST be emitted before + the Succeeded signal.

+ + + + +

The Connection owning the channel.

+ + + + + +

A subset of the Connection's properties, currently unused. + This parameter may be used in future.

+ + + + + +

The channel which has been created.

+ + + + + +

The same immutable properties of the Channel that would appear + in a NewChannels signal.

+ + + + + diff --git a/spec/Channel_Request_Future.xml b/spec/Channel_Request_Future.xml deleted file mode 100644 index d75c7e0ce..000000000 --- a/spec/Channel_Request_Future.xml +++ /dev/null @@ -1,98 +0,0 @@ - - - Copyright © 2008-2010 Collabora Ltd. - Copyright © 2008-2009 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.

- - - - - - -

This interface contains functionality which we intend to incorporate - into the ChannelRequest - interface in future. It should be considered to - be conceptually part of the core ChannelRequest interface, but without - API or ABI guarantees.

- - - - (as draft) - -

A dictionary of metadata provided by the channel - requester, which the handler and other clients MAY choose to - interpret. Currently no standard keys are defined; clients MAY - choose to use platform-specific keys for their own purposes, but MUST - ignore unknown keys and MUST cope with expected keys being - missing.

- - This property might be used to pass a contact ID for a - telephone number shared between two contacts from the address book to - the call UI, so that if you try to call “Mum”, the call UI knows this - rather than having to guess or show “Calling Mum or Dad”. The format - of these contact IDs would be platform-specific, so we leave the - definition of the dictionary entry up to the platform in question. - But third-party channel requesters might not include the contact ID, - so the call UI has to be able to deal with it not being - there. - -

The channel dispatcher will not interpret these hints: they are - solely for communication between cooperating clients.

- - -

Any extra parameters that do affect the channel dispatcher should - be designed separately.

- - -

This property may be set when the channel request is created, and - can never change. Since it is immutable, it SHOULD be included in the - dictionary of properties passed to AddRequest - by the ChannelDispatcher.

- - - - - (as draft) - -

Variant of the Succeeded signal - allowing to get the channel which has been created.

- - - - -

The Connection owning the channel.

- - - - - -

The channel which has been created.

- - - - - - - - diff --git a/spec/Channel_Type_Call.xml b/spec/Channel_Type_Call.xml index a45d95622..039c1f982 100644 --- a/spec/Channel_Type_Call.xml +++ b/spec/Channel_Type_Call.xml @@ -1163,12 +1163,13 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. + type="u" tp:type="Stream_Transport_Type" access="read" + tp:requestable="yes" tp:immutable="yes">

If set on a requested channel, this indicates the transport that should be used for this call. Where not applicable, this property - is defined to be the empty string, in particular, on CMs with - hardware streaming.

+ is defined to be Stream_Transport_Type_Unknown, + in particular, on CMs with hardware streaming.

When implementing a voip gateway one wants the outgoing leg of the diff --git a/spec/Channel_Type_Contact_Search.xml b/spec/Channel_Type_Contact_Search.xml index 335c71fba..fefa77a26 100644 --- a/spec/Channel_Type_Contact_Search.xml +++ b/spec/Channel_Type_Contact_Search.xml @@ -31,7 +31,15 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.A channel type for searching server-stored user directories. A new channel should be requested by a client for each search attempt, and closed when the search is completed or the required result has been - found.

+ found. Channels of this type should have TargetHandleType + None (and hence TargetHandle 0 and + TargetID + ""). Requests for channels of this type need only + optionally specify the Server property + (if it is an allowed property in the connection's RequestableChannelClasses).

Before searching, the AvailableSearchKeys property should be @@ -240,8 +248,8 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. - +

If supported by the protocol, the maximum number of results that should be returned, where 0 represents no limit. If the @@ -254,23 +262,20 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.2, the search service SHOULD only return Antonius and Bridget.

-

This property cannot change during the lifetime of the channel. - This property SHOULD be in the Allowed_Properties of a - Requestable_Channel_Class if and only if the - protocol supports specifying a limit; implementations SHOULD use +

This property SHOULD be requestable if and only if the protocol + supports specifying a limit; implementations SHOULD use 0 as the default if possible, or a protocol-specific sensible default otherwise.

 + tp:name-for-bindings="Available_Search_Keys" tp:immutable='yes'> The set of search keys supported by this channel. Example values include [""] (for protocols where several address fields are implicitly searched) or ["x-n-given", "x-n-family", "nickname", "email"] (for XMPP XEP-0055, without extensibility via Data Forms). - This property cannot change during the lifetime of a channel. It can be in the + type="s" access="read" tp:requestable='sometimes' tp:immutable='yes'>

For protocols which support searching for contacts on multiple servers with different DNS names (like XMPP), the DNS name of the @@ -439,9 +444,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. -

This property cannot change during the lifetime of the channel. - This property SHOULD be in the Allowed_Properties of a - Requestable_Channel_Class if and only if the +

This property SHOULD be requestable if and only if the protocol supports querying multiple different servers; implementations SHOULD use a sensible default if possible if this property is not specified in a channel request.

diff --git a/spec/Channel_Type_Server_Authentication.xml b/spec/Channel_Type_Server_Authentication.xml new file mode 100644 index 000000000..76599aa35 --- /dev/null +++ b/spec/Channel_Type_Server_Authentication.xml @@ -0,0 +1,121 @@ + + + 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.

+ + + (as stable API) + + + +

The type for a channel representing an authentication step with the + server. The actual authentication functionality is implemented by + the additional interface named in + AuthenticationMethod, + such as Channel.Interface.SASLAuthentication.

+ +

Future authentication steps also supported by this channel type might + include solving a captcha and/or agreeing to an EULA or terms-of-use + document; each of these would be represented by a channel with this + type, but a different + AuthenticationMethod.

+ +

Channels of this type will normally be be signalled and dispatched + while the Connection + owning them is in the CONNECTING state. They MAY also appear on a + Connection in the CONNECTED state, for instance if periodic + re-authentication is required.

+ +

Normally, only one channel of this type will + exist on a given Connection; if there is more than one, the handler + must complete authentication with each of them in turn.

+ +

Channels of this type cannot be requested with methods such as + CreateChannel. + They always have Requested = False, + TargetHandleType = None + and TargetHandle + = 0.

+ +

While it is CONNECTING, the Connection MUST NOT proceed with + connection, or signal + StatusChanged + to the CONNECTED state, until each channel of this type has either + been accepted as having a positive result (for instance, on SASL + channels this is done with the AcceptSASL method), or closed with the Close method.

+ + +

ServerAuthentication channels normally represent the client + authenticating itself to the server, but can also be used for the + server to authenticate itself to the client (i.e. prove that it is + in fact the desired server and not an imposter). Until the + authentication handler has confirmed this, connection should not + continue.

+ + +

If a channel of this type is closed with the Close method before + authentication has succeeded, this indicates that the Handler has + given up its attempts to authenticate or that no Handler is + available.

+ +

If this occurs, the connection manager MAY attempt to continue + connection (for instance, performing SASL authentication by using any + credentials passed to RequestConnection, + for instance from the Account.Parameters). If this fails + or has already been tried, the Connection will + disconnect.

+ + +

In particular, the ChannelDispatcher will close the + channel if it cannot find a handler.

+ + +

When the connection is done with the channel and it is no + longer needed, it is left open until either the connection state + turns to DISCONNECTED or the handler closes the channel. The + channel SHOULD NOT close itself once finished with.

+ + + + +

This property defines the method used for the authentication step + represented by this channel, which MUST be one of this channel's + Interfaces.

+ +

The initially-defined interface that can be used here is + Channel.Interface.SASLAuthentication.

+ + + + + + diff --git a/spec/Channel_Type_Text.xml b/spec/Channel_Type_Text.xml index 9cbfea21a..0cd4d5bb2 100644 --- a/spec/Channel_Type_Text.xml +++ b/spec/Channel_Type_Text.xml @@ -20,6 +20,10 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. + + The Messages interface is now + mandatory @@ -31,6 +35,8 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. + New APIs should use + an array of Message_Part instead. A struct (message ID, timestamp in seconds since 1970-01-01 00:00 UTC, sender's handle, message type, flags, text) representing a pending text message, as returned by @@ -67,6 +73,10 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. + Consulting + MessageTypes is preferred. + @@ -81,6 +91,10 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. + Consulting + PendingMessages is preferred. + If true, behave as if @@ -114,6 +128,8 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. + In practice, this signal + was not emitted, and does not have useful semantics. This signal is emitted to indicate that an incoming message was not able to be stored and forwarded by the connection manager @@ -122,6 +138,10 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. + The + MessageReceived signal is more informative. + A numeric identifier for acknowledging the message @@ -162,6 +182,10 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. + The + SendMessage method is more flexible. + An integer indicating the type of the message @@ -231,6 +255,10 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. + Delivery reporting is now + provided by the Messages interface. + The error that occurred @@ -266,6 +294,10 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. + The + MessageSent signal is more informative. + Unix timestamp indicating when the message was sent @@ -335,6 +367,11 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. + The + Messages interface has an extensible data structure + including separate booleans for most of these flags. + The incoming message was truncated to a shorter length by the @@ -480,77 +517,98 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. -

A channel type for sending and receiving messages in plain text, - with no formatting. In future specifications, channels for sending - and receiving messages that can be reduced to plain text (i.e. - formatted text) should also have this type.

+

A channel type for sending and receiving messages. This channel type + is primarily used for textual messages, but can also be used for + formatted text, text with "attachments", or binary messages on some + protocols.

+ +

Most of the methods and signals on this interface are deprecated, + since they only support plain-text messages with limited metadata. + See the mandatory Messages + interface for the modern equivalents.

When a message is received, an identifier is assigned and a - Received signal emitted, and the message - placed in a pending queue which can be inspected with - ListPendingMessages. A client which has - handled the message by showing it to the user (or equivalent) should - acknowledge the receipt using the - AcknowledgePendingMessages method, - and the message will then be removed from the pending queue. Numeric - identifiers for received messages may be reused over the lifetime of - the channel.

- -

Each message has an associated 'type' value, which should be one - of the values allowed by - Channel_Text_Message_Type.

- -

Each message also has a flags value, which is a bitwise OR of the - flags given in Channel_Text_Message_Flags.

+ MessageReceived signal emitted, and the message + is placed in a pending queue represented by the + PendingMessages property. + When the Handler + for a channel has handled the message by showing it to the user + (or equivalent), it should acknowledge the receipt of that message + using the AcknowledgePendingMessages + method, and the message will then be removed from the pending queue. + Numeric identifiers for received messages may be reused over the + lifetime of the channel.

Sending messages can be requested using the - Send method, which will return - successfully and emit the Sent signal - when the message has been delivered to the server, or return an error - with no signal emission if there is a failure. If a message is sent but - delivery of the message later fails, this is indicated with the - SendError signal.

- -

On protocols where additional contacts cannot be invited into - a one-to-one chat, or where a one-to-one chat is just a series of - individual personal messages rather than being represented by some - object on the server (i.e. most protocols), one-to-one chats should be - represented by a Text channel with Handle_Type - CONTACT.

+ SendMessage method, which will return + successfully when the message has been submitted for sending, or + return an error with no signal emission if there is an immediate + failure. If a message is submitted for sending but delivery of the + message later fails, this is indicated by a delivery report, which + is received in the same way as an incoming message.

+ +

Simple one-to-one chats (such as streams of private messages in + XMPP or IRC) should be represented by a Text channel whose + TargetHandleType + is Handle_Type_Contact. The expected way to + request such a channel is to set the ChannelType, TargetHandleType, + and either TargetHandle or TargetID in a call to EnsureChannel.

Named chat rooms whose identity can be saved and used again later (IRC channels, Jabber MUCs) are expected to be represented by Text - channels with Handle_Type ROOM and the Group - interface; they should usually also have the Properties interface.

- -

Unnamed, transient chat rooms defined only by their members (e.g. on - MSN) are expected to be represented by Text channels with handle type - 0, handle 0, the Group - interface, and optionally the Properties interface.

- -

On protocols where a conversation with a user is actually just - a nameless chat room starting with exactly two members, to which - more members can be invited, calling - RequestChannel - with type Text - and handle type CONTACT should continue to succeed, but may return - a channel with handle type 0, handle 0, the group interface, - and the local and remote contacts in its members.

+ channels with Handle_Type_Room and the Group + interface. In protocols where a chatroom can be used as a continuation + of one or more one-to-one chats, these channels should also have the + Conference + interface.

+ +

Unnamed, transient chat rooms which cannot be rejoined by their + unique identifier (e.g. a conversation on MSN which has, or once had, + three or more participants) are expected to be represented by Text + channels with Handle_Type_None (and hence TargetHandle 0), the + Group + interface, and optionally the + Conference + interface.

+ +

On protocols like MSN where a conversation with a user is actually + just a nameless chat room starting with exactly two members, to which + more members can be invited, the initial one-to-one conversation + SHOULD be represented with Handle_Type_Contact. If a third participant + joins or is invited, this SHOULD be represented by signalling + a new Conference channel + with the one-to-one channel in its InitialChannels, migrating the underlying protocol + object from the one-to-one channel to the Conference channel, + and creating a new protocol-level conversation if the one-to-one + channel is re-used. See the Conference interface for more details.

+ + +

This keeps the presentation of all one-to-one conversations + uniform, and makes it easier to hand over a conversation from a + 1-1-specific UI to a more elaborate multi-user UI; while it does + require UIs to understand Conference to follow the + upgrade, UIs that will deal with XMPP need to understand Conference + anyway.

+

If a channel of type Text is closed while it has pending messages, - the connection manager MUST allow this, but SHOULD open a new, - identical channel to deliver those messages, signalling it as a new - channel with the - NewChannel - signal (with the suppress_handler parameter set to FALSE).

- -

If messages were sent on the old channel but the - Sentsignal has not yet been emitted - for those messages, the new channel SHOULD emit Sent for those - messages when appropriate - it behaves like a continuation of the - old channel.

+ the connection manager MUST allow this, but SHOULD open a new channel + to deliver those messages, signalling it as a new channel with the + NewChannels + signal. The new channel should resemble the old channel, but have + Requested = FALSE regardless of its previous value; the InitiatorHandle + and InitiatorID should correspond to the sender of one of the pending + messages.

In effect, this turns this situation, in which a client @@ -573,16 +631,21 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.UI calls Close on text channel

  • text channel emits Closed and closes
  • message arrives
    • -
  • new text channel is created, connection emits NewChannel
    • +
  • new text channel is created, connection emits NewChannels
  • (the same or a different) UI handles it
    • -

    suppress_handler must be set to FALSE so the replacement channel +

    Requested must be set to FALSE so the replacement channel will be handled by something.

    + +

    In practice, connection managers usually implement this by keeping + the same internal object that represented the old channel, adjusting + its properties, signalling that it was closed, then immediately + re-signalling it as a new channel.

    As a result, Text channels SHOULD implement Channel.Interface.Destroyable.

    + namespace="ofdT">Channel.Interface.Destroyable    .

    This "respawning" behaviour becomes problematic if there is no diff --git a/spec/Client_Handler.xml b/spec/Client_Handler.xml index 2cceed170..3a922e8cc 100644 --- a/spec/Client_Handler.xml +++ b/spec/Client_Handler.xml @@ -103,8 +103,7 @@ /org/freedesktop/Telepathy/Client/Empathy/_1/_42/Bundle1 with BypassApproval = TRUE, whose HandlerChannelFilter - matches closely related Text channels by their Bundle property. - (This is use-case dis5)

    + matches closely related Text channels by their Bundle property.

    For service-activatable handlers, this property should be specified diff --git a/spec/Client_Interface_Requests.xml b/spec/Client_Interface_Requests.xml index cfab58de7..3cecfce49 100644 --- a/spec/Client_Interface_Requests.xml +++ b/spec/Client_Interface_Requests.xml @@ -125,8 +125,8 @@ and Account MUST be included, and Hints - SHOULD be included if implemented.

    + namespace="ofdT.ChannelRequest">Hints + MUST be included if implemented.

         diff --git a/spec/Connection_Interface_Contact_Info.xml b/spec/Connection_Interface_Contact_Info.xml index ce77a56af..527d32522 100644 --- a/spec/Connection_Interface_Contact_Info.xml +++ b/spec/Connection_Interface_Contact_Info.xml @@ -470,6 +470,36 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. + + + +

    Indicates that this field will be overwritten when the user's alias + is changed with SetAliases + or when the Account's Nickname + is updated. Clients that allow the editing of the Alias and the + ContactInfo in the same location should hide fields with this flag.

    + +

    If a client allowed the user to edit both the nickname and the + ContactInfo field at the same time, the user could set them to two + different values even though they map to the same property. This + would result in surprising behavior where the second value would + win over the first.

    +     +

    In addition to hiding this field when editing ContactInfo together + with the user's nickname, it is recommended that clients call + SetContactInfo before setting the + user's nickname.

    + +

    This ensures that if the user changes the nickname, the correct + value will get set even if the stale nickname is mistakenly sent + along with SetContactInfo.

    +     +

    If used, this flag typically appears on either the 'nickname' or + 'fn' field.

    +     +     diff --git a/spec/Connection_Interface_Contact_List.xml b/spec/Connection_Interface_Contact_List.xml index d602c19f1..2342379c8 100644 --- a/spec/Connection_Interface_Contact_List.xml +++ b/spec/Connection_Interface_Contact_List.xml @@ -652,15 +652,27 @@ subscribe to their presence, i.e. that their subscribe attribute becomes Yes.

    +

    Connection managers SHOULD NOT attempt to enforce a + mutual-subscription policy (i.e. when this method is called, they + should not automatically allow the contacts to see the local user's + presence). User interfaces that require mutual subscription + MAY call AuthorizePublication + at the same time as this method.

    + + +

    Whether to enforce mutual subscription is a matter of policy, + so it is left to the user interface and/or the server.

    +     +

    Before calling this method on a connection where GetAliasFlags returns the User_Set flag, user interfaces SHOULD obtain, from the user, an alias to identify the contact in future, and store it using SetAliases. + >SetAliases.

    - The user MAY be +

    The user MAY be prompted using the contact's current self-assigned nickname, or something derived from the contact's (presumably self-assigned) identifier, as a default, but these names chosen by the contact @@ -793,6 +805,19 @@ presence is sent to that contact, i.e. that their publish attribute becomes Yes.

    +

    Connection managers SHOULD NOT attempt to enforce a + mutual-subscription policy (i.e. when this method is called, they + should not automatically request that the contacts allow the user to + subscribe to their presence). User interfaces that require mutual + subscription MAY call + RequestSubscription at the same time + as this method.

    + + +

    Whether to enforce mutual subscription is a matter of policy, + so it is left to the user interface and/or the server.

    +     +

    For contacts with publish=Yes, this method has no effect; it MUST return successfully if all contacts given have this state.

    diff --git a/spec/Connection_Interface_Power_Saving.xml b/spec/Connection_Interface_Power_Saving.xml index ae82d2fa2..571bf6d51 100644 --- a/spec/Connection_Interface_Power_Saving.xml +++ b/spec/Connection_Interface_Power_Saving.xml @@ -2,7 +2,7 @@ - Copyright (C) 2007 Collabora Limited + Copyright © 2007-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 @@ -19,9 +19,8 @@ License along with this library; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.

     - + name="org.freedesktop.Telepathy.Connection.Interface.PowerSaving"> + (as stable API)

    Some protocols support mechanisms for reducing bandwidth usage—and hence power usage, on mobile devices—when the user is not directly diff --git a/spec/Makefile.am b/spec/Makefile.am index f41b3faf0..8b006e8dd 100644 --- a/spec/Makefile.am +++ b/spec/Makefile.am @@ -1,5 +1,6 @@ EXTRA_DIST = \ Account_Interface_Avatar.xml \ + Account_Interface_Addressing.xml \ Account_Interface_Minimum_Presence.xml \ Account_Interface_Storage.xml \ Account_Manager.xml \ @@ -15,7 +16,6 @@ EXTRA_DIST = \ Call_Stream_Endpoint.xml \ Channel_Dispatch_Operation.xml \ Channel_Dispatcher.xml \ - Channel_Dispatcher_Future.xml \ Channel_Dispatcher_Interface_Operation_List.xml \ Channel_Future.xml \ Channel_Handler.xml \ @@ -34,19 +34,21 @@ EXTRA_DIST = \ Channel_Interface_Messages.xml \ Channel_Interface_Password.xml \ Channel_Interface_Room.xml \ + Channel_Interface_SASL_Authentication.xml \ + Channel_Interface_Securable.xml \ Channel_Interface_Service_Point.xml \ Channel_Interface_SMS.xml \ Channel_Interface_Splittable.xml \ Channel_Interface_Transfer.xml \ Channel_Interface_Tube.xml \ Channel_Request.xml \ - Channel_Request_Future.xml \ Channel_Type_Call.xml \ Channel_Type_Contact_List.xml \ Channel_Type_Contact_Search.xml \ Channel_Type_DBus_Tube.xml \ Channel_Type_File_Transfer.xml \ Channel_Type_Room_List.xml \ + Channel_Type_Server_Authentication.xml \ Channel_Type_Server_TLS_Connection.xml \ Channel_Type_Stream_Tube.xml \ Channel_Type_Streamed_Media.xml \ diff --git a/spec/Protocol_Interface_Avatars.xml b/spec/Protocol_Interface_Avatars.xml index 262741e1a..cd913510d 100644 --- a/spec/Protocol_Interface_Avatars.xml +++ b/spec/Protocol_Interface_Avatars.xml @@ -20,9 +20,8 @@ 02110-1301, USA.

    - - (draft 1) + + (as stable API) diff --git a/spec/all.xml b/spec/all.xml index afb48dfc6..8585057a6 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.21.4 +0.21.5 Copyright © 2005-2010 Collabora Limited Copyright © 2005-2010 Nokia Corporation @@ -40,36 +40,72 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.

    - Connections represent active protocol sessions. + Connections represent active protocol sessions. There are a number of core + interfaces which all connections should implement, and a number of optional + interfaces which provide various functionality related to contacts and to + the connection itself.

    - - - - - - - - - - - - - - - - - - - - - - - + + + +

    + 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). +

    +     + + + +     + + + +

    + These optional Connection interfaces expose metadata about contacts on + this connection—from their current presence through to the type of client + they're connected with—and allow the local user to publish such metadata + back to their contacts. +

    +     + + + + + + + + + + + + +     + + + +

    + These optional Connection interfaces expose protocol-specific features, + and allow configuring the running connection. +

    +     + + + + + + + + + + + +     @@ -102,6 +138,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. + @@ -131,7 +168,9 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. + + @@ -180,6 +219,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. + @@ -194,11 +234,9 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.     - - diff --git a/spec/errors.xml b/spec/errors.xml index 268087b88..eccbd0953 100644 --- a/spec/errors.xml +++ b/spec/errors.xml @@ -508,6 +508,42 @@     + + + + Raised when a server or other piece of infrastructure indicates an + internal error, or when a message that makes no sense is received from + a server or other piece of infrastructure. + + + For instance, this is appropriate for XMPP's + internal-server-error, and is also appropriate if + you receive sufficiently inconsistent information from a server that + you cannot continue. + + + + + + + + Raised if a server rejects protocol messages from a connection manager + claiming that they do not make sense, two local processes fail to + understand each other, or an apparently impossible situation is + reached. + + + For instance, this would be an appropriate mapping for XMPP's + errors bad-format, invalid-xml, etc., which can't happen unless + the local (or remote) XMPP implementation is faulty. This is + also analogous to + Media_Stream_Error_Invalid_CM_Behavior, + TP_DBUS_ERROR_INCONSISTENT in telepathy-glib, and + TELEPATHY_QT4_ERROR_INCONSISTENT in telepathy-qt4. + + + + Copyright © 2005-2010 Collabora Limited Copyright © 2005-2009 Nokia Corporation -- cgit v1.2.1