From 8e725c8713cac8aa7abe26e98299b3220eab9c0d Mon Sep 17 00:00:00 2001 From: Louis-Francis Ratté-Boulianne Date: Thu, 21 Oct 2010 17:44:39 -0400 Subject: Update to spec 0.21.4 --- spec/Account.xml | 31 +- spec/Account_Interface_Minimum_Presence.xml | 108 +++ spec/Authentication_TLS_Certificate.xml | 305 ++++++++ spec/Call_Content.xml | 256 +++++-- spec/Call_Content_Codec_Offer.xml | 37 +- spec/Call_Content_Interface_Media.xml | 145 ++-- spec/Call_Content_Interface_Mute.xml | 26 +- spec/Call_Stream.xml | 174 +++-- spec/Call_Stream_Endpoint.xml | 127 +++- spec/Call_Stream_Interface_Media.xml | 218 +++--- spec/Channel.xml | 11 +- spec/Channel_Dispatcher_Future.xml | 377 ++++++++++ ...Channel_Dispatcher_Interface_Operation_List.xml | 4 +- spec/Channel_Interface_Addressing.xml | 107 +++ spec/Channel_Interface_Call_State.xml | 14 + spec/Channel_Interface_Conference.xml | 508 +++++++++---- spec/Channel_Interface_DTMF.xml | 102 ++- spec/Channel_Interface_Hold.xml | 5 +- spec/Channel_Interface_Mergeable_Conference.xml | 12 +- spec/Channel_Interface_Messages.xml | 31 +- spec/Channel_Interface_Room.xml | 373 ++++++++++ spec/Channel_Interface_SMS.xml | 93 +++ spec/Channel_Interface_Splittable.xml | 13 +- spec/Channel_Request_Future.xml | 98 +++ spec/Channel_Type_Call.xml | 788 +++++++++++++++++---- spec/Channel_Type_Contact_Search.xml | 2 +- spec/Channel_Type_Room_List.xml | 17 +- spec/Channel_Type_Server_TLS_Connection.xml | 69 ++ spec/Channel_Type_Streamed_Media.xml | 6 +- spec/Channel_Type_Text.xml | 14 +- spec/Client_Handler.xml | 20 +- spec/Client_Handler_Future.xml | 27 +- spec/Client_Interface_Requests.xml | 4 +- spec/Client_Observer.xml | 11 +- spec/Connection.xml | 165 ++++- spec/Connection_Interface_Addressing.xml | 258 +++++++ spec/Connection_Interface_Anonymity.xml | 40 +- spec/Connection_Interface_Cellular.xml | 101 +-- spec/Connection_Interface_Client_Types.xml | 218 ++++++ spec/Connection_Interface_Communication_Policy.xml | 163 +++++ spec/Connection_Interface_Contact_Groups.xml | 164 ++++- spec/Connection_Interface_Contact_List.xml | 492 ++++++++----- spec/Connection_Interface_Keepalive.xml | 73 ++ spec/Connection_Interface_Location.xml | 50 +- spec/Connection_Interface_Mail_Notification.xml | 75 +- spec/Connection_Interface_Power_Saving.xml | 110 +++ spec/Connection_Interface_Resources.xml | 212 ++++++ spec/Connection_Interface_Simple_Presence.xml | 131 +++- spec/Connection_Manager.xml | 142 ++-- spec/Media_Stream_Handler.xml | 89 ++- spec/Protocol.xml | 89 ++- spec/Protocol_Interface_Addressing.xml | 300 ++++++++ spec/Protocol_Interface_Presence.xml | 5 +- spec/all.xml | 27 +- spec/errors.xml | 97 ++- spec/generic-types.xml | 17 + spec/template.xml | 2 +- 57 files changed, 6000 insertions(+), 1153 deletions(-) create mode 100644 spec/Account_Interface_Minimum_Presence.xml create mode 100644 spec/Authentication_TLS_Certificate.xml create mode 100644 spec/Channel_Dispatcher_Future.xml create mode 100644 spec/Channel_Interface_Addressing.xml create mode 100644 spec/Channel_Interface_Room.xml create mode 100644 spec/Channel_Interface_SMS.xml create mode 100644 spec/Channel_Request_Future.xml create mode 100644 spec/Channel_Type_Server_TLS_Connection.xml create mode 100644 spec/Connection_Interface_Addressing.xml create mode 100644 spec/Connection_Interface_Client_Types.xml create mode 100644 spec/Connection_Interface_Communication_Policy.xml create mode 100644 spec/Connection_Interface_Keepalive.xml create mode 100644 spec/Connection_Interface_Power_Saving.xml create mode 100644 spec/Connection_Interface_Resources.xml create mode 100644 spec/Protocol_Interface_Addressing.xml diff --git a/spec/Account.xml b/spec/Account.xml index 5917c6f..acd8c30 100644 --- a/spec/Account.xml +++ b/spec/Account.xml @@ -407,16 +407,23 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.

The presence status that this account should have if it is brought online.

+ + In ITOS2007 and ITOS2008 this is a global preference, not visible + on D-Bus (the "default presence"). "Automatic presence" better + describes when it is used. + +

Setting this property MUST NOT actually change the account's status until the next time it is (re)connected for some reason.

-

The Connection_Presence_Type in the structure - SHOULD NOT be Offline or Unset.

+

The value of this property MUST be one that would be acceptable + for RequestedPresence, + with the additional restriction that the + Connection_Presence_Type MUST NOT be Offline.

- In ITOS2007 and ITOS2008 this is a global preference, not visible - on D-Bus (the "default presence"). "Automatic presence" better - describes when it is used. +

Otherwise, it would not be possible to use this presence to bring + the account online for a channel request.

 @@ -553,11 +560,12 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. - The actual presence. If the connection is not online, this should be - (Connection_Presence_Type_Offline, "", ""). + The actual presence. If the connection is not online, the + Connection_Presence_Type SHOULD be + Connection_Presence_Type_Offline. If the connection is online but does not support the SimplePresence - interface, this should be (Connection_Presence_Type_Unset, "", ""). + interface, the type SHOULD be Connection_Presence_Type_Unset. The account manager is expected to set this by observing signals from the Connection. @@ -585,6 +593,13 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. This corresponds to e.g. GetPresence and GetPresenceMessage in NMC 4.x. + +

The Connection_Presence_Type in this property + MUST NOT be Unset, Unknown or Error.

+ + +

Requesting those presence types doesn't make sense.

+ diff --git a/spec/Account_Interface_Minimum_Presence.xml b/spec/Account_Interface_Minimum_Presence.xml new file mode 100644 index 0000000..eb829b8 --- /dev/null +++ b/spec/Account_Interface_Minimum_Presence.xml @@ -0,0 +1,108 @@ + + + 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 2) + + +

This interface extends the core Account interface to provide a way + for applications to request minimum presence on the account.

+ + +

Some applications, for example mail notifiers or address book + synchronisation, can make use of account's connection even while + the user is nominally offline.

+ + +

Each client's unique name may set a minimum desired presence on the + account. The combined presence is the most available presence + of the minimum presences set and of RequestedPresence + set by the user. The account manager should attempt to manipulate + the connection to set the combined presence.

+ + + + + Active requests for minimum presence status, a map of client unique + name to the (non-offline) minimum presence they set. + + + + + +

Set a minimum presence needed by the client for this account. Setting + (Offline, "offline", "") removes the minimum presence requirement for + the client's unique name.

+ + + + + Requested presence status. + + + + + + + Emitted when the + MinimumPresenceRequests property + changes. + + + + + A new value of MinimumPresenceRequests property. + + + + + + +

A map of active minimum presence requests.

+ + + +

Client unique name.

+ + + + +

Requested minimum presence.

+ + +

Some applications may want to monitor the currently active + minimum presences required. An example is an tool allowing + the user to inspect applications maintaining open connections and + close those applications.

+ + + + + + + diff --git a/spec/Authentication_TLS_Certificate.xml b/spec/Authentication_TLS_Certificate.xml new file mode 100644 index 0000000..db1d76f --- /dev/null +++ b/spec/Authentication_TLS_Certificate.xml @@ -0,0 +1,305 @@ + + + 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) + + + 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.

+ + + + + +

Struct representing one reason why a TLS certificate was rejected.

+

Since there can be multiple things wrong with a TLS certificate, + arrays of this type are used to represent lists of reasons for + rejection. In that case, the most important reason SHOULD be placed + first in the list.

+ + + + +

The value of the TLS_Certificate_Reject_Reason enumeration for + this certificate rejection. + + Clients that do not understand the Error member, + which may be implementation-specific, can use this property to + classify rejection reasons into common categories. + +

+ + + + + +

The DBus error name for this certificate rejection.

+

This MAY correspond to the value of the Reason member, + or MAY be a more specific D-Bus error name, perhaps implementation-specific.

+ + + + + +

Additional information about why the certificate was rejected. + This 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
+
+

+ + + + + + + The possible states for a TLSCertificate + 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, + an array of TLS_Certificate_Rejection + structures containing the reason why the certificate is rejected.

+

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

+

The first rejection in the list MAY be assumed to be + the most important; if the array contains more than one + element, the CM MAY either use the values after the first, + or ignore them.

+ + + + + + 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 the Rejections property. + + + + + + + Accepts this certificate, i.e. marks it as verified. + + + + + + Rejects this certificate. + + + +

The new value of the Rejections property.

+

This MUST NOT be an empty array.

+ + + + + + Raised when the method is called on an object whose State + is not Pending, or when the provided rejection list is empty. + + + + + + + + diff --git a/spec/Call_Content.xml b/spec/Call_Content.xml index 3e585b4..17ed710 100644 --- a/spec/Call_Content.xml +++ b/spec/Call_Content.xml @@ -1,8 +1,8 @@ - Copyright © 2009 Collabora Ltd. - Copyright © 2009 Nokia Corporation + Copyright © 2009-2010 Collabora Ltd. + Copyright © 2009-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 @@ -25,52 +25,147 @@ (draft 1) - This object represents one Content inside a Call. For example in an - audio/video call there would be one audio and one video content. Each - content has one or more Stream.DRAFT - objects which represent the actual transport to one or more contacts. - + This object represents one Content inside a Call.DRAFT. For + example, in an audio/video call there would be one audio content + and one video content. Each content has one or more Stream.DRAFT objects which + represent the actual transport to one or more remote contacts. + + + + A representation of the reason for a content to be removed, + which may be used by simple clients, or used as a fallback + when the DBus_Reason is not understood. This enum will be + extended with future reasons as and when appropriate, so + clients SHOULD keep up to date with its values, but also be + happy to fallback to the Unknown value when an unknown value + is encountered. + + + + + We just don't know. Unknown values of this enum SHOULD also be + treated like this. + + + + + +

The local user requests that this content is removed + from the call.

+ + + + + +

There is an error with the content which means that it + has to be removed from the call.

+ + + + + +

Some aspect of the content is unsupported so has to be + removed from the call.

+ + + + - Remove the content from the call. + previously there were no + arguments + + Remove the content from the call. + + + + + A generic hangup reason. + + + + + + A more specific reason for the content removal, if one is + available, or an empty string. + + + + + + A human-readable message for the reason of removing the + content, such as "Fatal streaming failure" or "no codec + intersection". This property can be left empty if no reason + is to be given. + + - - + - Raised when a Call doesn't support removing contents (e.g. a Google Talk video call) + Raised when a Call doesn't support removing contents + (e.g. a Google Talk video call). - + -

The name of the content. - [FIXME: rationale?]

+

Emitted when the content is removed from the call. This + is the same as the Call.DRAFT.ContentRemoved + signal.

+ + + + + + +

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 media type of this content

+

The name of the content.

+ + + The content name property should be meaningful, so should be + given a name which is significant to the user. The name + could be the "audio" or "video" string localized, or perhaps + include some string identifying the source, such as a webcam + identifier. + - + -

The creator of this content

+

The media type of this content.

 - [FIXME] + The disposition of this content, which defines whether to + automatically start sending data on the streams when + Call.DRAFT is + called on the channel. @@ -79,52 +174,57 @@ - - - [FIXME: what does this mean?] - - - - + -

The content was initially part of the call. When Accept is called on the channel, all streams of - this content where the self-handle's sending state in Senders is Sending_State_Pending_Send - will be moved to Sending_State_Sending as if SetSending(TRUE) had been called.

+

The content was initially part of the call. When + Accept + is called on the channel, all streams of this content with + LocalSendingState + set to Sending_State_Pending_Send will be + moved to Sending_State_Sending as if + SetSending + (True) had been called.

 + type="u" tp:type="Call_Content_Disposition" access="read" + tp:immutable="yes"> - The disposition of this content. This property cannot change. + The disposition of this content. - + + plural version, renamed from + StreamAdded -

Emitted when a stream is added to a call

+

Emitted when streams are added to a call.

 - + - The stream which was added + The Stream.DRAFTs which were + added. - + + plural version, renamed from + StreamRemoved -

Emitted when a stream is added to a call

+

Emitted when streams are removed from a call

 - + - The stream which was removed + The Stream.DRAFTs which were + removed. @@ -132,22 +232,58 @@ -

The list of - Stream.DRAFT - objects that exist in this content.

+

The list of Stream.DRAFT objects that exist in this + content.

-

In a conference call multiple parties can share one media content - (say, audio), but the streaming of that media can either be shared - or separate. For example, in a multicast conference all contacts - would share one stream, while in a Muji conference there would be - a stream for each participant.

+ In a conference call multiple parties can share one media + content (say, audio), but the streaming of that media can + either be shared or separate. For example, in a multicast + conference all contacts would share one stream, while in a + Muji conference there would be a stream for each + participant. -

Change notification is via - StreamAdded and - StreamRemoved.

+

Change notification is through the + StreamsAdded and + StreamsRemoved signals.

+ + + + + + + A packetization method that can be used for a content. + + + + + Real-time Transport Protocol, as documented by RFC 3550. + + + + + + Raw media. + + + + + + MSN webcam. This is the video-only one-way type which was + used in earlier versions of WLM. Although no longer used, + modern WLM clients still support the MSN webcam protocol. + + + + + + + +

The packetization method in use for this content.

 diff --git a/spec/Call_Content_Codec_Offer.xml b/spec/Call_Content_Codec_Offer.xml index 31ff0b3..e0a791f 100644 --- a/spec/Call_Content_Codec_Offer.xml +++ b/spec/Call_Content_Codec_Offer.xml @@ -1,8 +1,8 @@ - Copyright © 2009 Collabora Ltd. - Copyright © 2009 Nokia Corporation + Copyright © 2009-2010 Collabora Ltd. + Copyright © 2009-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 @@ -26,15 +26,27 @@ This object represents an offer of a Codec payload mapping. - FIXME add Accept and Reject signals ? + type="a(usuua{ss})" tp:type="Codec[]"> + + The local codec mapping to send to the remote contacts and + to use in the Content.DRAFT. + + - Accept the updated Codec mapping and update the local mapping + Accept the updated Codec mapping and update the local mapping. + + + + The codecs given as the argument are invalid in some way. + + + @@ -44,11 +56,22 @@ + + +

Extra interfaces provided by this codec offer. This SHOULD + NOT include the CodecOffer interface itself, and cannot change + once the content has been created.

+ + + + type="a{ua(usuua{ss})}" tp:type="Contact_Codec_Map" access="read" + tp:immutable="yes"> - A map from remote contacts to the lists of codecs they support. + A map from remote contact to the list of codecs he or she + supports. diff --git a/spec/Call_Content_Interface_Media.xml b/spec/Call_Content_Interface_Media.xml index 8b9a17c..24811fd 100644 --- a/spec/Call_Content_Interface_Media.xml +++ b/spec/Call_Content_Interface_Media.xml @@ -1,8 +1,8 @@ - Copyright © 2009 Collabora Ltd. - Copyright © 2009 Nokia Corporation + Copyright © 2009-2010 Collabora Ltd. + Copyright © 2009-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 @@ -23,65 +23,85 @@ (draft 1) - + - Interface to use by a software implementation of media streaming. +

Interface to use by a software implementation of media + streaming. The reason behind splitting the members of this + interface out from the main Content.DRAFT interface is + that the software is not necessarily what controls the + media. An example of this is in GSM phones, where the CM just + tells the phone to dial a number and it does the audio routing + 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 CodecOffer.DRAFT + objects to appear (one will either already be present, or will + appear at some point in the channel's lifetime).

+ +

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

- FIXME: How should the streaming implementation know when it is its turn - to set the codecs. A description of a codec. - Numeric identifier for the codec. This will be used as the PT in the SDP or content description. - The name of the codec. - - The clockrate of the codec + The clockrate of the codec. - Number of channels of the codec if applicable, otherwise 0 + Number of channels of the codec if applicable, otherwise 0. - - Extra parameters for this codec + Extra parameters for this codec. - A map from contacts to the lists of codecs they support. + A map from contact to the list of codecs he or she supports. - - A contact + A contact handle. - - The codecs that the contact supports + The codecs that the contact supports. @@ -90,20 +110,17 @@ A codec offer and its corresponding remote contact codec map. - - The object path to the - CodecOffer.DRAFT + The object path to the CodecOffer.DRAFT - - The CodecOffer.DRAFT.RemoteContactCodecMap property + The CodecOffer.DRAFT.RemoteContactCodecMap property of the codec offer. @@ -118,16 +135,15 @@ signal implies that the CodecOffer property has changed to ('/', {}).

- - A map from contacts to their codecs. Each pair in this map is added - to the ContactCodecMap property, + A map from contact to his or her codecs. Each pair in this + map is added to the + ContactCodecMap property, replacing any previous pair with that key. - A list of keys which were removed from the @@ -137,17 +153,24 @@ - + - Set or update the local codec mapping. + Update the local codec mapping. This method should only be + used during an existing call to update the codec mapping. - The codecs now supported by the local user. + + + + Raised when not used during an existing call to update the codec mapping. + + + A map from contact handles (including the local user's own handle) to the codecs supported by that contact.

-

Change notification is via - CodecsChanged.

+

Change notification is via the + CodecsChanged signal.

 -

Emitted when a new CodecOffer.DRAFT appears. The streaming +

Emitted when a new CodecOffer.DRAFT appears. The streaming implementation MUST respond by calling the Accept or Reject method on the codec offer object.

+ namespace="ofdT.Call.Content.CodecOffer.DRAFT" + >Accept or Reject method on the codec offer object.

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

 - The object path of the new codec offer. This replaces any previous codec offer. - -

The CodecOffer.DRAFT.RemoteContactCodecMap property +

The CodecOffer.DRAFT.RemoteContactCodecMap property of the codec offer.

- -

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 practice.

- + + 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 + practice. + @@ -203,25 +225,26 @@ type="(oa{ua(usuua{ss})})" tp:type="Codec_Offering" access="read">

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

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

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

Change notification is via +

Change notification is via the NewCodecOffer (which replaces the value of this property with a new codec offer), and CodecsChanged (which implies that - there is no longer any active codec offer).

+ there is no longer any active codec offer) signals.

 diff --git a/spec/Call_Content_Interface_Mute.xml b/spec/Call_Content_Interface_Mute.xml index eea724f..f926e03 100644 --- a/spec/Call_Content_Interface_Mute.xml +++ b/spec/Call_Content_Interface_Mute.xml @@ -20,6 +20,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. (draft version, not API-stable) +

Interface for calls which may be muted. This only makes sense @@ -31,22 +32,22 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.

Although it's client's responsibility to actually mute the microphone or turn off the camera, using this interface the client can also inform the CM and other clients of that fact.

- -

For some protocols, the fact that the content is muted needs to be - transmitted to the peer; for others, the notification to the peer is - only informational (eg. XMPP), and some protocols may have no notion - of muting at all.

- + + + For some protocols, the fact that the content is muted needs + to be transmitted to the peer; for others, the notification + to the peer is only informational (eg. XMPP), and some + protocols may have no notion of muting at all. + - + Emitted to indicate that the mute state has changed for this call content. This may occur as a consequence of the client calling - Muted, or as an indication that another + SetMuted, or as an indication that another client has (un)muted the content. - True if the content is now muted. @@ -61,16 +62,17 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. - + + renamed from SetMuted to Mute + renamed back from Mute to SetMuted True if the client has muted the content. -

Inform the CM that the call content has been muted or unmuted by - che client.

+ the client.

It is the client's responsibility to actually mute or unmute the microphone or camera used for the content. However, the client diff --git a/spec/Call_Stream.xml b/spec/Call_Stream.xml index dc7d784..1d7b281 100644 --- a/spec/Call_Stream.xml +++ b/spec/Call_Stream.xml @@ -1,8 +1,8 @@ - Copyright © 2009 Collabora Ltd. - Copyright © 2009 Nokia Corporation + Copyright © 2009-2010 Collabora Ltd. + Copyright © 2009-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 @@ -25,38 +25,43 @@ (draft 1) - One stream inside a content - FIXME, direction should be a mapping of contact -> (bool)sending ? + One stream inside a Content.DRAFT. Set the stream to start or stop sending media from the local - user to other contacts. + user to other contacts. -

If true, the local user's sending state should change - to Sending, if it isn't already.

+

If True, the + LocalSendingState should + change to Sending_State_Sending, if it isn't + already.

-

If false, the local user's sending state should change to None, - if it isn't already.

+

If False, the + LocalSendingState should + change to Sending_State_None, if it isn't + already.

 - - - [FIXME: when?] - - + - Request that a remote contact stops or starts sending on this stream. +

Request that a remote contact stops or starts sending on + this stream.

+ +

The CanRequestReceiving + property defines whether the protocol allows the local user to + request the other side start sending on this stream.

 @@ -73,44 +78,69 @@ + + + + The request contact is valid but is not involved in this + stream. + + - [FIXME: when?] + The protocol does not allow the local user to request the + other side starts sending on this stream. - + + renamed from SendersChanged to MembersChanged + renamed from MembersChanged to RemoteMembersChanged - Emitted when Senders changes. + Emitted when RemoteMembers changes. A mapping from channel-specific handles to their updated sending - state, whose keys include at least the senders who were added, - and the senders whose states changed. + state, whose keys include at least the members who were added, + and the members whose states changed. - The channel-specific handles that were removed from - the keys of the Senders property, as a result of the - contact leaving this stream + The channel-specific handles that were removed from the keys + of the RemoteMembers + property, as a result of the contact leaving this stream + + + + + + + Emitted when LocalSendingState changes. + + + + + The new value of + LocalSendingState. - Tristate indicating whether a contact is sending media. + Enum indicating whether a contact is sending media. - The contact is not sending media and has not been asked to do so. + The contact is not sending media and has not been asked to + do so. @@ -125,35 +155,51 @@ The contact is sending media. + + + + The contact has been asked to stop sending media. + + - A map from contacts to their sending state. + A map from a contact to his or her sending state. + + The contact handle. + + The sending state of the contact. - + + +

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.

+ + + + + renamed from Senders -

A map from contacts to their sending state.

- -

The local user's handle in this map (the Group.SelfHandle if the channel implements - Group, or the Connection.SelfHandle otherwise) indicates - whether the local user is sending media. Media sent on this stream - should be assumed to be received, directly or indirectly, by every - other contact in the Senders mapping. Sending_State_Pending_Send - indicates that another contact has asked the local user to send +

A map from remote contacts to their sending state. The + local user's sending state is shown in + LocalSendingState.

+ +

Sending_State_Pending_Send indicates + that another contact has asked the local user to send media.

Other contacts' handles in this map indicate whether they are @@ -162,6 +208,54 @@ have been asked to do so.

 + + + +

The local user's sending state. Media sent on this stream + should be assumed to be received, directly or indirectly, by + every other contact in the + RemoteMembers mapping. Change + notification is given via the + LocalSendingStateChanged + signal.

+ + + Implementations of the first Call draft had the self handle + in the RemoteMembers (then + called Members) map and this showed that it's annoying + having to keep track of the self handle so that it can be + special-cased. + + +

A value of Sending_State_Pending_Send for + this property indicates that the other side requested the + local user start sending media, which can be done by calling + SetSending. When a call is + accepted, all initial contents with streams that have a + local sending state of + Sending_State_Pending_Send are + automatically set to sending. For example, on an incoming + call it means you need to Accept + to start the actual call, on an outgoing call it might mean + you need to call Accept + before actually starting the call.

+ + + + + + +

If true, the user can request that a remote contact starts + sending on this stream.

+ + Not all protocols allow the user to ask the + other side to start sending media. + + diff --git a/spec/Call_Stream_Endpoint.xml b/spec/Call_Stream_Endpoint.xml index fbab2cf..4818168 100644 --- a/spec/Call_Stream_Endpoint.xml +++ b/spec/Call_Stream_Endpoint.xml @@ -1,8 +1,8 @@ - Copyright © 2009 Collabora Ltd. - Copyright © 2009 Nokia Corporation + Copyright © 2009-2010 Collabora Ltd. + Copyright © 2009-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 @@ -21,73 +21,160 @@ + tp:causes-havoc="experimental"> (draft 1) - This object represents a set of candidates of one end-point. +

This object represents an endpoint for a stream. In a one-to-one + call, there will be one (bidirectional) stream per content and + one endpoint per stream (as there is only one remote + contact). In a multi-user call there is a stream for each remote + contact and each stream has one endpoint as it refers to the one + physical machine on the other end of the stream.

+ +

The multiple endpoint use case appears when SIP call forking + is used. Unlike jingle call forking (which is just making + multiple jingle calls to different resources appear as one + call), SIP call forking is actually done at the server so you + have one stream to the remote contact and then and endpoint for + each SIP client to be called.

+ + The ICE credentials used for all candidates. If each candidate + has different credentials, then this property SHOULD be ("", + ""). Per-candidate credentials are set in the + Candidate's + Candidate_Info a{sv}. + - - + tp:name-for-bindings="Remote_Credentials_Set"> + + + The username set. + + + + + The password set. + + + + Emitted when the remote ICE credentials for the endpoint are + set. If each candidate has different credentials, then this + signal will never be fired. + + + A list of candidates for this endpoint. + + tp:name-for-bindings="Remote_Candidates_Added"> + + Emitted when remote candidates are added to the + RemoteCandidates property. + + type="a(usqa{sv})" tp:type="Candidate[]"> + + The candidates that were added. + + + tp:name-for-bindings="Candidate_Selected"> + + Emitted when a candidate is selected for use in the stream. + + type="(usqa{sv})" tp:type="Candidate"> + + The candidate that has been selected. + + + + The candidate that has been selected for use to stream packets + to the remote contact. Change notification is given via the + the CandidateSelected signal. + + tp:name-for-bindings="Set_Selected_Candidate"> + + Set the value of + CandidateSelected. + + The candidate that has been selected. + + + + + The stream state of the endpoint. + - + tp:name-for-bindings="Stream_State_Changed"> + + Emitted when the StreamState + property changes. + + + + The new StreamState value. + + - + tp:name-for-bindings="Set_Stream_State"> + + Change the StreamState of the + endpoint. + + + + The requested stream state. + + + + + + + type="u" tp:type="Stream_Transport_Type" access="read"> + + The transport type for the stream endpoint. + diff --git a/spec/Call_Stream_Interface_Media.xml b/spec/Call_Stream_Interface_Media.xml index b1b9e19..3d4fb13 100644 --- a/spec/Call_Stream_Interface_Media.xml +++ b/spec/Call_Stream_Interface_Media.xml @@ -1,8 +1,8 @@ - Copyright © 2009 Collabora Ltd. - Copyright © 2009 Nokia Corporation + Copyright © 2009-2010 Collabora Ltd. + Copyright © 2009-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 @@ -23,30 +23,35 @@ (draft 1) - + [FIXME] - - - Used to set the username fragment and password for streams that have - global credentials. - - - [FIXME: rationale?] - + + +

Used to set the username fragment and password for streams that have + global credentials.

- - - + + + The username to use when authenticating on the stream. + + + + + The password to use when authenticating on the stream. + + + - Extra information about the candidate. Allowed and mandatory keys - depend on the transport protocol used. The following keys are commenly - used: +

Extra information about the candidate. Allowed and mandatory keys + depend on the transport protocol used. The following keys are commenly + used:

+
Type (u)
type of candidate (host, srflx, prflx, relay)
@@ -78,41 +83,39 @@ One of the well-known keys documented here, or an - implementation-specific key + implementation-specific key. - The value corresponding to that key + The value corresponding to that key. - A Stream Candidate - + A Stream Candidate. - The component number + The component number. - The IP address to use + The IP address to use. - The port number to use + The port number to use. - Additional information about the candidate + Additional information about the candidate. - Add candidates to LocalCandidates - and signal them to the remote contact(s). + Add candidates to the + LocalCandidates property and + signal them to the remote contact(s). - - - Candidates to be appended to - LocalCandidates + The candidates to be added. @@ -120,43 +123,34 @@ - This indicates to the CM that the initial batch of candidates has been - added. - - - [FIXME: rationale] - + This indicates to the CM that the initial batch of candidates + has been added. + WLM_8_5 was removed A transport that can be used for streaming. - Raw UDP, with or without STUN. All streaming clients are assumed to support this transport, so there is no handler capability token for - it in the Call.DRAFT interface. + it in the Call.DRAFT interface. [This corresponds to "none" or "stun" in the old Media.StreamHandler interface.] - - Interactive Connectivity Establishment, as defined by the IETF MMUSIC - working group. - [FIXME: do we want this to cover both ICE-UDP and ICE-TCP, or split - them?] - [This corresponds to "ice-udp" in the old Media.StreamHandler - interface.] + Interactive Connectivity Establishment, as defined by RFC + 5245. Note that this value covers ICE-UDP only. + [This corresponds to "ice-udp" in the old + Media.StreamHandler interface.] - Google Talk peer-to-peer connectivity establishment, as implemented @@ -165,17 +159,7 @@ interface.] - - - - The transport used by Windows Live Messenger 8.5 or later, which - resembles ICE draft 6. - [This corresponds to "wlm-8.5" in the old Media.StreamHandler - interface.] - - - - + The transport used by Windows Live Messenger 2009 or later, which resembles ICE draft 19. @@ -183,79 +167,100 @@ interface.] + + + + Shared memory transport, as implemented by the GStreamer + shmsrc and shmsink plugins. + + + type="u" tp:type="Stream_Transport_Type" access="read" tp:immutable="yes"> - The transport for this stream. This property is immutable. + The transport for this stream. - [FIXME]. Change notification is via - LocalCandidatesAdded. + [FIXME]. Change notification is via the + LocalCandidatesAdded signal. - Emitted when local candidates are added to - LocalCandidates. + Emitted when local candidates are added to the + LocalCandidates property. - - + - Candidates that have been appended to - LocalCandidates + Candidates that have been added. - A username/password pair. + A username and password pair. - The username + The username. - The password + The password. - [FIXME]. Change notification is via - LocalCredentialsSet. + [FIXME]. Change notification is via the + LocalCredentialsChanged signal. - - + + renamed from LocalCredentailsSet Emitted when the value of LocalCredentials changes. - + + + Emitted when the value of + RelayInfo changes. + + + + + + + Emitted when the value of + STUNServers changes. + + + + - - The IP addresses of possible STUN servers to use for NAT traversal, as - dotted-quad IPv4 address literals or RFC2373 IPv6 address literals. - This property cannot change once the stream has been created, so there - is no change notification. The IP addresses MUST NOT be given as DNS - hostnames. + +

The IP addresses of possible STUN servers to use for NAT + traversal, as dotted-quad IPv4 address literals or RFC2373 + IPv6 address literals. Change notification is via the + STUNServersChanged + signal. The IP addresses MUST NOT be given as DNS hostnames.

High-quality connection managers already need an asynchronous @@ -334,7 +339,11 @@ if Transport is GTalk_P2P, this is a Google relay server; otherwise, the meaning of RelayInfo is undefined.

-

If relaying is not possible for this stream, the list is empty.

+

If relaying is not possible for this stream, the list is + empty.

+ +

Change notification is given via the + RelayInfoChanged signal.

 @@ -343,40 +352,38 @@

Signals that the initial information about STUN and Relay servers has been retrieved, i.e. the - RetrievedServerInfo property is now - true.

+ HasServerInfo property is + now true.

 - + -

True if the initial information about STUN servers and Relay servers - has been retrieved. Change notification is via the +

True if all the initial information about STUN servers and Relay + servers has been retrieved. Change notification is via the ServerInfoRetrieved signal.

-

Streaming implementations that can't cope with STUN and relay - servers being added later SHOULD wait for this property - to become true before proceeding.

+ Streaming implementations that can't cope with STUN and + relay servers being added later SHOULD wait for this + property to become true before proceeding. + tp:name-for-bindings="Endpoints_Changed"> Emitted when the Endpoints property changes. - - + Endpoints that were added. - - + Endpoints that no longer exist. @@ -386,12 +393,9 @@ -

The list of endpoints - Endpoint.DRAFT - that exist for this stream. -

+

The list of Endpoint.DRAFT objects that exist for this + stream.

Change notification is via the EndpointsChanged signal.

diff --git a/spec/Channel.xml b/spec/Channel.xml index 897b683..b1772d7 100644 --- a/spec/Channel.xml +++ b/spec/Channel.xml @@ -101,7 +101,9 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.TargetHandleType MUST be present and not Handle_Type_None, and TargetID MUST NOT be - present.

+ present. Properties from + Addressing.DRAFT + MUST NOT be present.

The channel that satisfies the request MUST either:

@@ -147,8 +149,11 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.TargetHandleType MUST be present and not Handle_Type_None, and TargetHandle MUST NOT be - present. The request MUST fail with error InvalidHandle, without - side-effects, if the requested TargetID would not be accepted by + present. Properties from + Addressing.DRAFT + MUST NOT be present.The request MUST fail with error InvalidHandle, + without side-effects, if the requested TargetID would not be + accepted by RequestHandles.

The returned channel must be related to the handle corresponding diff --git a/spec/Channel_Dispatcher_Future.xml b/spec/Channel_Dispatcher_Future.xml new file mode 100644 index 0000000..701b424 --- /dev/null +++ b/spec/Channel_Dispatcher_Future.xml @@ -0,0 +1,377 @@ + + + + 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_Dispatcher_Interface_Operation_List.xml b/spec/Channel_Dispatcher_Interface_Operation_List.xml index d61123f..be06f5c 100644 --- a/spec/Channel_Dispatcher_Interface_Operation_List.xml +++ b/spec/Channel_Dispatcher_Interface_Operation_List.xml @@ -66,7 +66,7 @@

The rationale is the same as for - Channel_Details.

+ Channel_Details.

Each dictionary MUST contain at least the following keys:

@@ -108,7 +108,7 @@ type="a{sv}" tp:type="Qualified_Property_Value_Map"> The same properties that would appear in the Properties member of - Dispatch_Operation_Details. + Dispatch_Operation_Details. diff --git a/spec/Channel_Interface_Addressing.xml b/spec/Channel_Interface_Addressing.xml new file mode 100644 index 0000000..494fd7b --- /dev/null +++ b/spec/Channel_Interface_Addressing.xml @@ -0,0 +1,107 @@ + + + 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 draft) + +

This interface provides properties that can be used for + requesting channels through different contact addressing + schemes like vCard addresses or URIs. +

+ + + + +

The vCard field, normalized to lower case, + TargetVCardAddress refers to.

+ +

The url vCard field MUST NOT appear here; see + TargetURI instead.

+ + +

In practice, protocols have a limited set of URI + schemes that make sense to resolve as a contact.

+ + +

If this is omitted from a request, + TargetVCardAddress MUST be + omitted as well.

+ + + + + +

The URI scheme used in TargetURI

+ + +

While this seems redundant, since the scheme is included in + TargetURI, it exists for constructing + RequestableChannelClasses + that support a limited set of URI schemes.

+ + +

If this is omitted from a request, + TargetURI MUST be + omitted as well.

+ + + + + +

The vCard address of the Channel's target.

+ +

If this is present in a channel request, + TargetVCardField + MUST be present, and + TargetHandle, + TargetID, + and TargetURI MUST NOT be present. + TargetHandleType + must either not be present or set to Handle_Type_Contact. + The request MUST fail with error InvalidHandle, without + side-effects, if the requested vCard address cannot be found.

+ + + + + +

The URI of the Channel's target. The URI's scheme (i.e. the + part before the first colon) MUST be identical to + TargetURIScheme.

+ +

If this is present in a channel request, + TargetVCardField + MUST be present, and + TargetHandle, + TargetID, + and TargetVCardAddress MUST NOT be + present. + TargetHandleType + must either not be present or set to Handle_Type_Contact. + The request MUST fail with error InvalidHandle, without + side-effects, if the requested vCard address cannot be found.

+ + + + + diff --git a/spec/Channel_Interface_Call_State.xml b/spec/Channel_Interface_Call_State.xml index b569a7f..b0aea59 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_Conference.xml b/spec/Channel_Interface_Conference.xml index 92d962d..abda59e 100644 --- a/spec/Channel_Interface_Conference.xml +++ b/spec/Channel_Interface_Conference.xml @@ -20,16 +20,18 @@ 02110-1301, USA.

- (draft 1) + name="org.freedesktop.Telepathy.Channel.Interface.Conference"> + (as stable API)

An interface for multi-user conference channels that can "continue - from" one or more individual channels.

+ from" one or more individual channels. This could be used to invite + other contacts to an existing 1-1 text conversation, combine two phone + calls into one conference call, and so on, with roughly the same API in + each case.

This interface addresses freedesktop.org (GSM-compatible conference calls) and bug #24939 (upgrading calls and chats to multi-user). - See those bugs for rationale and use cases.

- -

Examples of usage:

- -

Active and held GSM calls C1, C2 can be merged into a single - channel Cn with the Conference interface, by calling - CreateChannel({...ChannelType: ...Call, - ...InitialChannels: [C1, C2]}) - which returns Cn.

- -

An XMPP 1-1 conversation C1 can be continued in a newly created - multi-user chatroom Cn by calling - CreateChannel({...ChannelType: ...Text, - ...InitialChannels: [C1]}) - which returns Cn.

- -

An XMPP 1-1 conversation C1 can be continued in a specified - multi-user chatroom by calling - CreateChannel({...ChannelType: ...Text, ...HandleType: ROOM, - ...TargetID: 'telepathy@conf.example.com', - ...InitialChannels: [C1]}) - which returns a Conference channel.

- -

Either of the XMPP cases could work for Call channels, to - upgrade from 1-1 Jingle to multi-user Jingle. Any of the XMPP cases - could in principle work for link-local XMPP (XEP-0174).

- -

The underlying switchboard representing an MSN 1-1 conversation C1 - with a contact X can be moved to a representation as a nameless - chatroom, Cn, to which more contacts can be invited, by calling - CreateChannel({...ChannelType: ...Text, - ...InitialChannels: [C1]}) - which returns Cn. C1 SHOULD remain open, with no underlying - switchboard attached. If X establishes a new switchboard with the - local user, C1 SHOULD pick up that switchboard rather than letting - it create a new channel. - [FIXME: should it?] - Similarly, if the local user sends a message in C1, then - a new switchboard to X should be created and associated with C1.

- -

XMPP and MSN do not natively have a concept of merging two or more - channels C1, C2... into one channel, Cn. However, the GSM-style - merging API can be supported on XMPP and MSN, as an API short-cut - for upgrading C1 into a conference Cn (which invites the - TargetHandle of C1 into Cn), then immediately inviting the - TargetHandle of C2, the TargetHandle of C3, etc. into Cn as well.

- -

With a suitable change of terminology, Skype has behaviour similar - to MSN.

+ See those bugs for more rationale and use cases.

 +

Existing channels are upgraded by requesting a new channel of the same + ChannelType, + listing the channels to be merged into the new conference in the + InitialChannels property of the request. + If InitialInviteeHandles and + InitialInviteeIDs are + Allowed_Properties in RequestableChannelClasses, + ad-hoc conferences to a set of contacts may be created by requesting a + channel, specifying + InitialInviteeHandles and/or + InitialInviteeIDs to be the contacts in + question. A request may specify these alongside + InitialChannels, to simultaneously + upgrade a channel to a conference and invite others to join it.

+ +

Channels with this interface MAY also implement MergeableConference.DRAFT + to support merging more 1-1 channels into an ongoing conference. + Similarly, 1-1 channels MAY implement Splittable.DRAFT to + support being broken out of a Conference channel.

+

The Group MAY have channel-specific handles for participants; - clients SHOULD support both Conferences that have channel-specific handles, - and those that do not.

+ >Group interface on Conference channels MAY use + channel-specific handles for participants; clients SHOULD support + both Conferences that have channel-specific handles, and those that + do not.

In the GSM case, the Conference's Group interface MAY have - channel-specific handles, to reflect the fact that the identities of - the participants might not be known - it can be possible to know that - there is another participant in the Conference, but not know who - they are. - [FIXME: fact check from GSM gurus needed] -

+ channel-specific handles, to represent the fact that the same + phone number may be in a conference twice (for instance, it could be + the number of a corporate switchboard).

In the XMPP case, the Conference's Group interface SHOULD have channel-specific handles, to reflect the fact that the participants @@ -132,6 +108,164 @@ be misleading.

 +

Examples of usage

+ +

A pair of 1-1 GSM calls C1 and C2 can be merged + into a single conference call by calling:

+ +
+ CreateChannel({ + ...ChannelType: ...Call, + ...InitialChannels: [C1, C2] + }) +
+ +

which returns a new channel Cn implementing the conference + interface. (As a quirk of GSM, both 1-1 will cease to function normally + until they are Split + from the conference, or the conference ends.)

+ +

An XMPP 1-1 conversation C3 (with + chris@example.com, say) can be continued in a newly created + multi-user chatroom by calling:

+ +
+ CreateChannel({ + ...ChannelType: ...Text, + ...InitialChannels: [C3] + }) +
+ +

Or, to invite emily@example.net to join the newly-created MUC + at the same time:

+ +
+ CreateChannel({ + ...ChannelType: ...Text, + ...InitialChannels: [C3], + ...InitialInviteeIDs: ['emily@example.net'] + }) +
+ +

To continue C3 in a particular multi-user + chatroom (rather than the implementation inventing a unique name for + the room), call:

+ +
+ EnsureChannel({ + ...ChannelType: ...Text, + ...TargetHandleType: ...Room, + ...TargetID: 'telepathy@conf.example.com', + ...InitialChannels: [C3] + }) +
+ +

Note the use of EnsureChannel — if a channel for + telepathy@conf.example.com is already open, this SHOULD be + equivalent to inviting chris@example.com to the existing + channel.

+ +

In the above cases, the text channel C3 SHOULD remain open + and fully functional (until explicitly closed by a client); new + incoming 1-1 messages from chris@example.com SHOULD appear in + C3, and messages sent using C3 MUST be relayed + only to chris@example.com.

+ + +

If there is an open 1-1 text channel with a contact, in every + other situation new messages will appear in that channel. Given + that the old channel remains open — which is the least surprising + behaviour, and eases us towards a beautiful world where channels + never close themselves — it stands to reason that it should be + where new messages from Chris should appear. On MSN, creating a + conference from C3 should migrate the underlying + switchboard from C3 to the new channel; this is an + implementation detail, and should not affect the representation on + D-Bus. With a suitable change of terminology, Skype has the same + behaviour.

+ +

If the current handler of that channel doesn't want this to happen + (maybe it transformed the existing tab into the group chat window, + and so there'd be no UI element still around to show new messages), + then it should just Close the + old 1-1 channel; it'll respawn if necessary.

+ + +

Either of the XMPP cases could work for Call channels, to + upgrade from 1-1 Jingle to multi-user Jingle. Any of the XMPP cases + could in principle work for link-local XMPP (XEP-0174).

+ +

XMPP and MSN do not natively have a concept of merging two or more + channels C1, C2... into one channel, Cn. However, the GSM-style + merging API can be supported on XMPP and MSN, as an API short-cut + for upgrading C1 into a conference Cn (which invites the + TargetHandle of C1 into Cn), then immediately inviting the + TargetHandle of C2, the TargetHandle of C3, etc. into Cn as well.

+ +

Sample RequestableChannelClasses

+ +

A GSM connection might advertise the following channel class for + conference calls:

+ +
+ +( Fixed = {
+    ...ChannelType: + ...StreamedMedia
+  },
+  Allowed = [ InitialChannels, + InitialAudio + ]
+) + +
+ +

This indicates support for starting audio-only conference calls by + merging two or more existing channels (since + InitialInviteeHandles and + InitialInviteeIDs are not allowed).

+ +

An XMPP connection might advertise the following classes for ad-hoc + multi-user text chats:

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

The first class indicates support for starting ad-hoc (nameless) chat + rooms, upgraded from existing 1-1 channels and/or inviting new + contacts, along with a message to be sent along with the invitations. + The second indicates support for upgrading to a particular named chat + room.

 TargetHandleType = CONTACT.

-

This property MUST NOT be requestable. - [FIXME: or would it be better for this one, and not IC, to be - requestable?] -

+

This property MUST NOT be requestable; instead, the + InitialChannels property may be + specified when requesting a channel.

+ + +

This is consistent with requesting + InitialInviteeHandles and + InitialInviteeIDs, rather than + requesting Group.Members + and some hypothetical ID version of that property.

+

Change notification is via the ChannelMerged and @@ -166,6 +308,22 @@ The channel that was added to Channels. + + + A new channel-specific handle for the TargetHandle of + Channel, as will appear in + OriginalChannels, or 0 if a + global handle is used for + Channel's TargetHandle on the Group interface + of this channel. + + + + Channel's immutable properties. + @@ -176,35 +334,50 @@ namespace="org.freedesktop.Telepathy.Channel.Interface" >Splittable.DRAFT.Split method.

-

[FIXME: relative ordering of this vs. Closed? Do we - care?]

+

If a channel is removed because it was closed, Closed should be emitted + before this signal.

The channel that was removed from Channels. + + + + Additional information about the removal, which may include + the same well-known keys as the Details argument of + MembersChangedDetailed, with the same semantics. + + + access="read" type="ao" tp:immutable="yes" tp:requestable="yes">

The initial value of Channels.

This property SHOULD be requestable. Omitting it from a request is equivalent to providing it with an empty list as value. Requests - where its value has at least two elements SHOULD be expected to - succeed on any implementation of this interface.

- -

Whether a request with 0 or 1 elements in the list will succeed is - indicated by SupportsNonMerges.

+ where its value has at least two channel paths SHOULD be expected to + succeed on any implementation of this interface. If + InitialInviteeHandles and + InitialInviteeIDs are + Allowed_Properties in RequestableChannelClasses, then requests with zero + or one channel paths SHOULD also succeed; otherwise, clients SHOULD + NOT make requests with zero or one paths for this property.

-

In GSM, a pair of calls can be merged into a conference. In XMPP - and MSN, you can create a new chatroom, or upgrade one 1-1 channel - into a chatroom; however, on these protocols, it is also possible - to fake GSM-style merging by upgrading the first channel, then - inviting the targets of all the other channels into it.

+

In GSM, a pair of calls can be merged into a conference, but you + can't start a conference call from zero or one existing calls. In + XMPP and MSN, you can create a new chatroom, or upgrade one 1-1 + channel into a chatroom; however, on these protocols, it is also + possible to fake GSM-style merging by upgrading the first channel, + then inviting the targets of all the other channels into it.

If possible, the Channels' states SHOULD @@ -213,9 +386,7 @@ them in this property's value or by calling MergeableConference.DRAFT.Merge on them. - [FIXME: there's nothing in RequestableChannelClasses yet - to say what will happen, see #24906 comment 6]

+ >MergeableConference.DRAFT.Merge on them.

In Jingle, nothing special will happen to merged calls. UIs MAY @@ -223,10 +394,6 @@ the desired behaviour; this SHOULD always work. Not doing an implicit hold/unhold seems to preserve least-astonishment.

-

[FIXME: check whether ring supports faking Hold on both - channels, as it probably should: see #24906 comment 6] -

-

In GSM, the calls that are merged go into a state similar to Hold, but they cannot be unheld, only split from the conference call using - -

This property is immutable.

 + access="read" type="au" tp:type="Contact_Handle[]" tp:immutable="yes" + tp:requestable="yes">

A list of additional contacts invited to this conference when it was created.

-

This property SHOULD be requestable, and appear in the allowed +

If it is possible to invite new contacts when creating a conference + (as opposed to merging several channels into one new conference + channel), this property SHOULD be requestable, and appear in the allowed properties in RequestableChannelClasses, in all connection - managers that can implement its semantics (in practice, this is - likely to mean exactly those connection managers where - SupportsNonMerges will be true).

+ >RequestableChannelClasses. Otherwise, this property + SHOULD NOT be requestable, and its value SHOULD always be the empty + list.

+ + +

On GSM you have to place a 1-1 call before you can merge it into a + conference; on the other hand, you can invite new contacts to XMPP + Muji calls and XMPP/MSN/Skype ad-hoc chat rooms without starting a + 1-1 channel with them first.

+

If included in a request, the given contacts are automatically invited into the new channel, as if they had been added with @@ -285,8 +459,6 @@ property, together with any other contacts invited at the same time (if that information is known).

-

This property is immutable.

-

InitialInviteeHandles, InitialInviteeIDs and InitialChannels MAY be combined in a single request.

@@ -321,13 +493,13 @@ + access="read" type="as" tp:immutable="yes" tp:requestable="yes">

A list of additional contacts invited to this conference when it was created.

-

This property SHOULD be requestable as an alternative to, or - combined with, InitialInviteeHandles. +

This property SHOULD be requestable if and only if + InitialInviteeHandles is requestable. Its semantics are the same, except that it takes a list of the string representations of contact handles; invitations are sent to any contact present in either or both of these properties.

@@ -337,13 +509,11 @@ means that the value of InitialInviteeIDs will include the TargetID of each channel in InitialChannels, and the ID corresponding to each handle in InitialInviteeHandles.

- -

This property is immutable.

 + access="read" type="s" tp:immutable="yes" tp:requestable="yes">

The message that was sent to the InitialInviteeHandles when they were @@ -364,65 +534,95 @@

If the local user was not the initiator of this channel, the message with which they were invited (if any) SHOULD appear in the value of this property.

- -

This property is immutable.

 - + -

[FIXME: needs a better name; or perhaps it could be implied - by InitialInviteeHandles being requestable in XMPP/MSN but not in - GSM?]

- -

If true, requests with InitialChannels - omitted, empty, or one element long should be expected to succeed.

- -

This property SHOULD appear in RequestableChannelClasses for - conference channels if and only if its value on those channels will - be true.

+

On GSM conference calls, it is possible to have the same phone + number in a conference twice; for instance, it could be the number of + a corporate switchboard. This is represented using channel-specific + handles; whether or not a channel uses channel-specific handles is + reported in Group.GroupFlags. + The Group.HandleOwners + property specifies the mapping from opaque channel-specific handles + to actual numbers; this property specifies the original 1-1 channel + corresponding to each channel-specific handle in the conference.

+ +

In protocols where this situation cannot arise, such as XMPP, + this property MAY remain empty.

+ +

For example, consider this situation:

+ +
    +
  1. Place a call (with path /call/to/simon) to the contact + +441234567890 (which is assigned the handle h, + say), and ask to be put through to Simon McVittie;
    2. +
  2. Put that call on hold;
    3. +
  3. Place another call (with path /call/to/jonny) to + +441234567890, and ask to be put + through to Jonny Lamb;
    4. +
  4. Request a new channel with + InitialChannels: + ['/call/to/simon', '/call/to/jonny'].
    5. +
+ +

The new channel will have the following properties, for some handles + s and j:

+ +
+ {
+ ...Group.GroupFlags: + Channel_Specific_Handles | (other flags),
+ ...Group.Members: + [self_handle, s, j],
+ ...Group.HandleOwners: + { s: h, j: h },
+ ...InitialChannels: + ['/call/to/simon', '/call/to/jonny'],
+ ...Channels: + ['/call/to/simon', '/call/to/jonny'],
+ ...OriginalChannels: + { s: '/call/to/simon', j: '/call/to/jonny' },
+ # ...standard properties like ChannelType: Group elided...
+ } +
- -

Putting this in RequestableChannelClasses means clients can find - out whether their request will succeed early enough to do - something about it.

- -

In XMPP, you can request a channel of type ROOM without - incorporating any 1-1 chats at all - indeed, this is the normal - way to do it - or as a continuation of a single 1-1 chat, and then - invite other people in later.

- -

The sense of this property is a bit awkward, but it avoids making it - an anti-capability. If the sense were inverted, then its presence in - RequestableChannelClasses would imply that the protocol lacks - a feature; as it stands, it is additive. (Contrast with - ImmutableStreams, which is the wrong way around for - backwards-compatibility reasons.)

- - -

If false, InitialChannels SHOULD be - supplied in all requests for this channel class, and contain at least - two channels. Requests where this requirement is not met SHOULD fail - with NotImplemented. -

- - -

In GSM, you can only make a conference call by merging at least - two channels. - [FIXME: the CM could conceivably fake it, but that would be - rather nasty] -

- +

Change notification is via the + ChannelMerged and + ChannelRemoved signals: if + Channel_Specific_Handle in the former is non-zero, this + property SHOULD be updated to map that handle to the merged channel's + path.

 + + + + A channel-specific handle for a participant in this conference. + + + + + The object path of Channels + representing the original 1-1 channel with + Channel_Specific_Handle. + + + + + A mapping from members of a conference to the original 1-1 channel with + that contact, if any. See + OriginalChannels for details. + + diff --git a/spec/Channel_Interface_DTMF.xml b/spec/Channel_Interface_DTMF.xml index bd20f6e..d74ea6f 100644 --- a/spec/Channel_Interface_DTMF.xml +++ b/spec/Channel_Interface_DTMF.xml @@ -19,7 +19,15 @@ License along with this library; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.

- + + + + + The Stream_IDs in this + interface should now be ignored by CMs. This is primarily to allow this + interface to be used with Call.DRAFT + channels. An interface that gives a Channel the ability to send DTMF events over @@ -30,6 +38,8 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. + The Stream_ID parameter became + vestigial. A stream ID as defined in the StreamedMedia channel type. This argument is included for backwards compatibility and MUST @@ -78,6 +88,8 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. + The Stream_ID parameter became + vestigial. A stream ID as defined in the StreamedMedia channel type. This argument is included for backwards compatibility and MUST @@ -117,22 +129,47 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. + The characters [pPxXwW,] must + also be supported. - A string representation of one or more DTMF - events. + +

A string representation of one or more DTMF + events. Implementations of this method MUST support all of the + following characters in this string:

+ +
    +
  • the digits 0-9, letters A-D and a-d, and symbols '*' and '#' + correspond to the members of DTMF_Event
    • + +
  • any of 'p', 'P', 'x', 'X' or ',' (comma) results in an + implementation-defined pause, typically for 3 seconds
    • + +
  • 'w' or 'W' waits for the user to continue, by stopping + interpretation of the string, and if there is more to be played, + emitting the TonesDeferred signal + with the rest of the string as its argument: see that signal + for details
    • +
+

Send multiple DTMF events to all eligible streams in the channel. - Each character in the Tones string must be a valid DTMF event - (as defined by - RFC4733). - Each tone will be played for a pre-defined number of milliseconds, - followed by a pause before the next tone is played. The - duration/pause is defined by the protocol or connection manager.

+ Each tone will be played for an implementation-defined number of + milliseconds (typically 250ms), followed by a gap before the next tone + is played (typically 100ms). The + duration and gap are defined by the protocol or connection manager.

+ - In cases where the client knows in advance the tone sequence it wants - to send, it's easier to use this method than manually start and stop - each tone in the sequence. +

In cases where the client knows in advance the tone sequence it + wants to send, it's easier to use this method than manually start + and stop each tone in the sequence.

+ +

The tone and gap lengths may need to vary for interoperability, + according to the protocol and other implementations' ability to + recognise tones. At the time of writing, GStreamer uses a + minimum of 250ms tones and 100ms gaps when playing in-band DTMF + in the normal audio stream, or 70ms tones and 50ms gaps when + encoding DTMF as audio/telephone-event.

Tone overlaping or queueing is not supported, so this method can only @@ -182,6 +219,47 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. + + + +

The tones waiting for the user to continue, if any.

+ +

When this property is set to a non-empty value, + TonesDeferred is emitted. + When any tones are played (i.e. whenever + SendingTones is emitted), + this property is reset to the empty string.

+ + + + + + + The new non-empty value of + DeferredTones. + + +

Emitted when 'w' or 'W', indicating "wait for the user to continue", + is encountered while playing a DTMF string queued by + MultipleTones or + InitialTones. Any queued DTMF events + after the 'w', which have not yet been played, are placed in the + DeferredTones property and copied + into this signal's argument.

+ +

When the channel handler is ready to continue, it MAY pass the + value of DeferredTones to + MultipleTones, to resume sending. + Alternatively, it MAY ignore the deferred tones, or even play + different tones instead. Any deferred tones are discarded the next + time a tone is played.

+ +

This signal SHOULD NOT be emitted if there is nothing left to play, + i.e. if the 'w' was the last character in the DTMF string.

+ + + diff --git a/spec/Channel_Interface_Hold.xml b/spec/Channel_Interface_Hold.xml index 1e3a832..ef5a08f 100644 --- a/spec/Channel_Interface_Hold.xml +++ b/spec/Channel_Interface_Hold.xml @@ -20,7 +20,10 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. - + + + + first API-stable version diff --git a/spec/Channel_Interface_Mergeable_Conference.xml b/spec/Channel_Interface_Mergeable_Conference.xml index 989ffac..cd606c1 100644 --- a/spec/Channel_Interface_Mergeable_Conference.xml +++ b/spec/Channel_Interface_Mergeable_Conference.xml @@ -23,7 +23,7 @@ name="org.freedesktop.Telepathy.Channel.Interface.MergeableConference.DRAFT" tp:causes-havoc="experimental"> (draft 1) - +

An interface for multi-user conference channels that can have @@ -50,11 +50,11 @@

The given channel SHOULD be added to Conference.DRAFT.Channels if and only if the + >Conference.Channels if and only if the underlying protocol signals the merge in some way. It MUST NOT be added to Conference.DRAFT.InitialChannels (to preserve + >Conference.InitialChannels (to preserve immutability).

@@ -82,19 +82,19 @@ - + The given channel isn't suitable for merging into this one: for instance, it might have the wrong channel type or handle type. - + It will never be possible to merge channels into this particular conference. - + The given channel is theoretically suitable for merging into this one, but that's not currently possible for some reason (for diff --git a/spec/Channel_Interface_Messages.xml b/spec/Channel_Interface_Messages.xml index d4fde0d..0eeee39 100644 --- a/spec/Channel_Interface_Messages.xml +++ b/spec/Channel_Interface_Messages.xml @@ -95,7 +95,8 @@ USA.

 + tp:name-for-bindings="Supported_Content_Types" + tp:immutable="yes">

A list of MIME types supported by this channel, with more preferred MIME types appearing earlier in the list. The list MAY include "*/*" @@ -143,7 +144,8 @@ USA.

+ tp:name-for-bindings="Message_Part_Support_Flags" + tp:immutable="yes"> Flags indicating the level of support for message parts on this channel. @@ -1087,15 +1089,19 @@ USA.

- - A list of incoming messages that have neither been acknowledged nor - rejected. This list is a more detailed version of the one returned - by Text.ListPendingMessages, - and contains the same messages, uniquely identified by the same - pending message IDs. Its items can be removed using - Text.AcknowledgePendingMessages. + +

A list of incoming messages that have neither been acknowledged nor + rejected. This list is a more detailed version of the one returned + by Text.ListPendingMessages, + and contains the same messages, uniquely identified by the same + pending message IDs. Its items can be removed using + Text.AcknowledgePendingMessages.

+ +

Change notification is via + MessageReceived and + PendingMessagesRemoved.

 @@ -1340,7 +1346,8 @@ USA.

+ tp:name-for-bindings="Delivery_Reporting_Support" + tp:immutable="yes"> A bitfield indicating features supported by this channel. diff --git a/spec/Channel_Interface_Room.xml b/spec/Channel_Interface_Room.xml new file mode 100644 index 0000000..ffdf4a9 --- /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_Interface_SMS.xml b/spec/Channel_Interface_SMS.xml new file mode 100644 index 0000000..b0dce66 --- /dev/null +++ b/spec/Channel_Interface_SMS.xml @@ -0,0 +1,93 @@ + + + Copyright © 2008–2010 Nokia Corporation + 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 +Library 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. + + + + + Imported from + rtcom-telepathy-glib, with the unused properties removed and the + documentation tidied up. + + +

This interface contains SMS-specific properties for text channels. + This currently only includes whether the SMSes received on the channel + should be displayed immediately to the user, without prompting.

+ +

Handler filters

+ +

A handler for class 0 SMSes should advertise the following filter:

+ +
+{ ...ChannelType: + ...Text,
+  ...TargetHandleType: + Handle_Type_Contact,
+  ...SMS.Flash: + True,
+}
+ +

It should also set its BypassApproval property + to True, so that it is invoked immediately for new + channels.

+ + + + +

If True, then this channel is exclusively for + receiving class 0 SMSes (and no SMSes can be sent using SendMessage + on this channel). If False, no incoming class 0 SMSes + will appear on this channel.

+ +

This property is immutable (cannot change), and therefore SHOULD + appear wherever immutable properties are reported, e.g. NewChannels signals.

+ + +

Class 0 SMSes should be displayed immediately to the user, and + need not be saved to the device memory unless the user explicitly + chooses to do so. This is unlike “normal”, class 1 SMSes, which + must be stored, but need not be shown immediately in their entirity + to the user.

+ +

Separating class 0 SMSes into their own channel with this + immutable property allows them to be dispatched to a different + Handler—which + would include this property in its HandlerChannelFilter—avoiding the normal Text + channel handler having to decide for each message whether it should + be displayed to the user immediately or handled normally.

+ +

Currently, no mechanism is defined for sending class 0 + SMSes. It seems reasonable to support specifying the class of an + outgoing SMS in its header Message_Part, rather + than requiring the UI to request a special channel for such SMSes; + hence, we define here that channels with Flash set to + True are read-only.

+ + + + + diff --git a/spec/Channel_Interface_Splittable.xml b/spec/Channel_Interface_Splittable.xml index 063565e..760c134 100644 --- a/spec/Channel_Interface_Splittable.xml +++ b/spec/Channel_Interface_Splittable.xml @@ -28,7 +28,7 @@

An interface for channels that can be made conceptually part of a Conference.DRAFT, and can then be detached from that + >Conference, and can then be detached from that conference.

@@ -45,23 +45,20 @@

Request that this channel is removed from any Conference.DRAFT of which it is a part.

+ >Conference of which it is a part.

This implies that the media streams within the conference are put on hold and the media streams within the member channel leaving the - conference are unheld. - [FIXME: or, maybe it'd be less surprising if it didn't do - this?] -

+ conference are unheld.

 - + This channel isn't in a conference. - + This channel is in a conference but can't currently be split away from it. diff --git a/spec/Channel_Request_Future.xml b/spec/Channel_Request_Future.xml new file mode 100644 index 0000000..d75c7e0 --- /dev/null +++ b/spec/Channel_Request_Future.xml @@ -0,0 +1,98 @@ + + + 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 f1d0f0e..a45d956 100644 --- a/spec/Channel_Type_Call.xml +++ b/spec/Channel_Type_Call.xml @@ -1,7 +1,7 @@ - Copyright © 2009 Collabora Limited - Copyright © 2009 Nokia Corporation + Copyright © 2009-2010 Collabora Limited + Copyright © 2009-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 @@ -23,29 +23,406 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. -

A channel type for making audio and video calls.

+

A channel type for making audio and video calls. Call + channels supersede the old StreamedMedia + channel type. Call channels are much more flexible than its + predecessor and allow more than two participants.

+ +

Handlers are advised against executing all the media + signalling, codec and candidate negotiation themselves but + instead use a helper library such as telepathy-farsight + which when given a new Call channel will set up the + transports and codecs and create GStreamer pads which + can be added to the handler UI. This is useful as it means + the handler does not have to worry how exactly the + connection between the call participants is being made.

+ +

The TargetHandle and + TargetID + properties in a Call channel refer to the contact that the + user initially called, or which contact initially called the + user. Even in a conference call, where there are multiple + contacts in the call, these properties refer to the + initial contact, who might have left the conference since + then. As a result, handlers should not rely on these + properties.

+ +

Contents

+ +

Content.DRAFT + objects represent the actual media that forms the Call (for + example an audio content and a video content). Calls always + have one or more Content objects associated with them. As a + result, a new Call channel request MUST have either + InitialAudio=True, or + InitialVideo=True, or both, + as the Requestable Channel Classes will document.

+ +

Content.DRAFT objects have + one or more stream associated with them. More information on + these streams and how to maniuplate them can be found on the + Content.DRAFT + interface page.

+ +

Outgoing calls

+ +

To make an audio-only call to a contact foo@example.com + handlers should call:

+ +
+ 
+CreateChannel({
+  ...ChannelType: ...Call.DRAFT,
+  ...TargetHandleType: Contact,
+  ...TargetID: 'foo@example.com',
+  ...InitialAudio: True,
+})
+ +

As always, TargetHandle may be used + in place of + TargetID + if the contact's handle is already known. To make an audio + and video call, the handler should also specify + InitialVideo The + connection manager SHOULD return a channel whose immutable + properties contain the local user as the InitiatorHandle, the + remote contact as the TargetHandle, + Requested = + True (indicating the call is outgoing).

+ +

After a new Call channel is requested, the + CallState property will be + Call_State_Pending_Initiator. As the local + user is the initiator, the call must be accepted by the handler + by calling the Accept method. + At this point, CallState changes + to Call_State_Pending_Receiver which signifies + that the call is ringing, waiting for the remote contact to + accept the call. All changes to + CallState property are signalled + using the CallStateChanged + signal.

+ +

When the call is accepted by the remote contact, the + CallStateChanged signal fires + again to show that CallState = + Call_State_Accepted.

+ +

At this point telepathy-farsight + will signal that a pad is available for the handler to show + in the user interface.

+ +
Missed calls
+ +

If the remote contact does not accept the call in time, then + the call can be terminated by the server. Note that this only + happens in some protocols. Most XMPP clients, for example, do + not do this and rely on the call initiator terminating the call. + A missed call is shown in a Call channel by the + CallState property changing to + Call_State_Ended, and the + CallStateReason property changing + to (remote contact, + Call_State_Change_Reason_No_Answer, "").

+ +
Rejected calls
+ +

If the remote contact decides he or she does not feel like + talking to the local user, he or she can reject his or her + incoming call. This will be shown in the Call channel by + CallState changing to + Call_State_Ended and the + CallStateReason property + changing to (remote contact, + Call_State_Change_Reason_User_Requested, + "org.freedesktop.Telepathy.Error.Rejected").

+ +

Incoming calls

+ +

When an incoming call occurs, something like the following + NewChannels + signal will occur:

+ +
+ 
+NewChannels([
+  /org/freedesktop/Telepathy/Connection/foo/bar/foo_40bar_2ecom/CallChannel,
+  {
+    ...ChannelType: ...Call.DRAFT,
+    ...TargetHandleType: Contact,
+    ...TargetID: 'foo@example.com',
+    ...TargetHandle: 42,
+    ...Requested: False,
+    ...InitialAudio: True,
+    ...InitialVideo: True,
+    ...InitialAudioName: "audio",
+    ...InitialVideoName: "video",
+    ...MutableContents: True,
+  }])
+ +

The InitialAudio and + InitialVideo properties show that + the call has been started with two contents: one for audio + streaming and one for video streaming. The + InitialAudioName and + InitialVideoName properties also + show that the aforementioned audio and video contents have names + "audio" and "video".

+ +

Once the handler has notified the local user that there is an + incoming call waiting for acceptance, the handler should call + SetRinging to let the CM know. + The new channel should also be given to telepathy-farsight to + work out how the two participants will connect together. + telepathy-farsight will call the appropriate methods on the call's + Content.DRAFTs + to negotiate codecs and transports.

+ +

To pick up the call, the handler should call + Accept. The + CallState property changes to + Call_State_Accepted and once media is + being transferred, telepathy-farsight will notify the + handler of a new pad to be shown to the local user in the + UI

+ +

To reject the call, the handler should call the + Hangup method. The + CallState property will change to + Call_State_Ended and the + CallStateReason property will + change to (self handle, + Call_State_Change_Reason_User_Requested, + "org.freedesktop.Telepathy.Error.Rejected").

+ +

Ongoing calls

+ +
Adding and removing contents
+ +

When a call is open, new contents can be added as long as the + CM supports it. The + MutableContents property will let + the handler know whether further contents can be added or + existing contents removed. An example of this is starting a + voice call between a contact and then adding a video content. + To do this, the should call + AddContent like this:

+ +
+ 
AddContent("video",
+           Media_Stream_Type_Video)
+
+ +

Assuming no errors, the new video content will be added to + the call. telepathy-farsight will pick up the new content and + perform the transport and codec negotiation automatically. + telpathy-farsight will signal when the video is ready to + show in the handler's user interface.

+ +

A similar method is used for removing contents from a call, + except that the Remove method + is on the Content.DRAFT object.

+ +
Ending the call
+ +

To end the call, the handler should call the + Hangup method. The + CallState property will change to + Call_State_Ended and + CallStateReason will change + to (self handle, + Call_State_Change_Reason_User_Requested, + "org.freedesktop.Telepathy.Error.Cancelled").

+ +

If the other participant hangs up first then the + CallState property will change to + Call_State_Ended and + CallStateReason will change + to (remote contact, + Call_State_Change_Reason_User_Requested, + "org.freedesktop.Telepathy.Error.Terminated").

+ +

Multi-party calls

+ + [TODO] + +

Call states

+ +

There are many combinations of the + CallState and + CallStateReason properties which + mean different things. Here is a table to try to make these + meanings clearer:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
RequestedCallStateCallStateReasonMeaning
ActorReasonDBus_Reason
TrueCall_State_Pending_InitiatorSelf handleCall_State_Change_Reason_User_Requested""The outgoing call channel is waiting for the local user to call Accept.
TrueCall_State_Pending_ReceiverSelf handleCall_State_Change_Reason_User_Requested""The outgoing call is waiting for the remote contact to pick up the call.
FalseCall_State_Pending_Receiver0Call_State_Change_Reason_Unknown""The incoming call is waiting for the local user to call Accept on the call.
TrueCall_State_AcceptedRemote contact handleCall_State_Change_Reason_User_Requested""The remote contact accepted the outgoing call.
FalseCall_State_AcceptedSelf handleCall_State_Change_Reason_User_Requested""The local user accepted the incoming call.
True or FalseCall_State_EndedSelf handleCall_State_Change_Reason_User_RequestedCancelledThe local user hung up the incoming or outgoing call.
True or FalseCall_State_EndedRemote contact handleCall_State_Change_Reason_User_RequestedTerminatedThe remote contact hung up the incoming or outgoing call.
TrueCall_State_EndedRemote contact handleCall_State_Change_Reason_No_Answer""The outgoing call was not picked up and the call ended.
FalseCall_State_EndedRemote contact handleCall_State_Change_Reason_User_RequestedPickedUpElsewhereThe incoming call was ended because it was picked up elsewhere.
+ +

Requestable channel classes

+ +

The RequestableChannelClasses + for Call.DRAFT channels + can be:

+ +
+ 
+[( Fixed = { ...ChannelType: ...Call.DRAFT,
+            ...TargetHandleType: Contact,
+            ...InitialVideo: True
+          },
+  Allowed = [ ...InitialVideoName,
+              ...InitialAudio,
+              ...InitialAudioName
+            ]
+),
+( Fixed = { ...ChannelType: ...Call.DRAFT,
+            ...TargetHandleType: Contact,
+            ...InitialAudio: True
+          },
+  Allowed = [ ...InitialAudioName,
+              ...InitialVideo,
+              ...InitialVideoName
+            ]
+)]
+ +

Clients aren't allowed to make outgoing calls that have + neither initial audio nor initial video. Clearly, CMs + which don't support video should leave out the first class and + omit InitialVideo from the second + class, and vice versa for CMs without audio support.

+ +

Handlers should not close Call.DRAFT channels + without first calling Hangup on + the channel. If a Call handler crashes, the ChannelDispatcher will call + Close on the + channel which SHOULD also imply a call to + Hangup(Call_State_Change_Reason_User_Requested, + "org.freedesktop.Telepathy.Error.Terminated", "") before + actually closing the channel.

-

A Call channel can have one or more Content.DRAFT - objects, which represent the actual Media that forms the Call (e.g. an - audio content and a video content).

 - + + renamed from Ringing

Indicate that the local user has been alerted about the incoming call.

-

This method is only useful if the channel's - Requested property is false, and the - CallState is - Call_State_Pending_Receiver. While this is the case, - this method SHOULD change the +

This method is only useful if the + channel's Requested + property is False, and + the CallState is + Call_State_Pending_Receiver (an incoming + call waiting on the local user to pick up). While this is + the case, this method SHOULD change the CallFlags to include - Call_Flag_Ringing, and notify the remote contact that the local - user has been alerted (if the protocol implements this); repeated - calls to this method SHOULD succeed, but have no further effect.

+ Call_Flags_Locally_Ringing, and notify the + remote contact that the local user has been alerted (if the + protocol implements this); repeated calls to this method + SHOULD succeed, but have no further effect.

In all other states, this method SHOULD fail with the error NotAvailable.

@@ -54,14 +431,14 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. - The call was Requested, so ringing does not make sense. + The call was Requested, so ringing does not make sense. - The call is no longer in state Call_State_Pending_Receiver. + The call is no longer in state + Call_State_Pending_Receiver. @@ -69,14 +446,17 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. -

For incoming calls in state Call_State_Pending_Receiver, accept the +

For incoming calls in state + Call_State_Pending_Receiver, accept the incoming call; this changes the - CallState to Call_State_Accepted.

+ CallState to + Call_State_Accepted.

-

For outgoing calls in state Call_State_Pending_Initiator, actually +

For outgoing calls in state + Call_State_Pending_Initiator, actually call the remote contact; this changes the CallState to - Call_State_Pending_Receiver.

+ Call_State_Pending_Receiver.

Otherwise, this method SHOULD fail with the error NotAvailable.

@@ -84,16 +464,16 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. client (user interface) is handling the channel.

When this method is called, for each Content.DRAFT whose Disposition is Call_Content_Disposition_Initial, - any streams where the self-handle's sending state in Senders is Sending_State_Pending_Send - will be moved to Sending_State_Sending as if SetSending(TRUE) had been called.

+ namespace="ofdT.Call" >Content.DRAFT whose + Disposition is + Call_Content_Disposition_Initial, any + streams where the LocalSendingState + is Sending_State_Pending_Send will be + moved to Sending_State_Sending as if + SetSending(True) had been called.

 @@ -107,11 +487,14 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. - Request that the call is ended. + Request that the call is ended. All contents will be removed + from the Call so that the + Contents property will be the + empty list. + type="u" tp:type="Call_State_Change_Reason"> A generic hangup reason. @@ -147,21 +530,39 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. - [FIXME] + Request that a new Content.DRAFT of type + Content_Type is added to the Call. Handlers should check the + value of the MutableContents + property before trying to add another content as it might not + be allowed. - The suggested name of the content to add +

The suggested name of the content to add.

- [FIXME: rationale] + The content name property should be meaningful, so should + be given a name which is significant to the user. The name + could be a localized "audio", "video" or perhaps include + some string identifying the source, such as a webcam + identifier. + +

If there is already a content with the same name as this + property then a sensible suffix should be added. For example, + if this argument is "audio" but a content of the same name + already exists, a sensible suffix such as " (1)" is appended + to name the new content "audio (1)". A further content with the + name "audio" would then be named "audio (2)".

+ - The media type of the content to add + The media stream type of the content to be added to the + call. @@ -175,12 +576,22 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. - [FIXME: when?] + The media stream type given is invalid. - [FIXME: when?] + The media stream type requested is not implemented by the + CM. + + + + + The content type requested cannot be added to this + call. Examples of why this might be the case include + because a second video stream cannot be added, or a + content cannot be added when the content set isn't + mutable. @@ -189,46 +600,37 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. -

Emitted when a new Content.DRAFT is added to the call.

+

Emitted when a new Content.DRAFT is added to the call.

 - Path to the newly-created Content.DRAFT object. + Path to the newly-created Content.DRAFT object. - - - The media type of the content which was added - - -

Emitted when a Content.DRAFT is removed from the call.

+

Emitted when a Content.DRAFT is removed from the call.

 - The Content.DRAFT which was removed. + The Content.DRAFT which was removed. + tp:name-for-bindings="Contents"> -

The list of - Content.DRAFT - objects that are part of this call. Change notification - is via the ContentAdded and +

The list of Content.DRAFT objects that + are part of this call. Change notification is via the + ContentAdded and ContentRemoved signals.

@@ -306,9 +708,9 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. The local contact has been alerted about the call but has not responded; if possible, the remote contact(s) have been informed of this fact. This flag only makes sense on incoming calls in - state Call_State_Pending_Receiver. It SHOULD be set when - Ringing is called successfully, and - unset when the state changes. + state Call_State_Pending_Receiver. It SHOULD + be set when SetRinging is + called successfully, and unset when the state changes. @@ -317,19 +719,21 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. The contact is temporarily unavailable, and the call has been placed in a queue (e.g. 182 Queued in SIP, or call-waiting in telephony). This flag only makes sense on outgoing 1-1 calls in - state Call_State_Pending_Receiver. It SHOULD be set or unset - according to informational messages from other contacts. + state Call_State_Pending_Receiver. It SHOULD be + set or unset according to informational messages from other + contacts. - The call has been put on hold by the local user, e.g. using the - Hold interface. This flag SHOULD only be set if - there is at least one Content, and all Contents are locally held; - it makes sense on calls in state Call_State_Pending_Receiver or - Call_State_Accepted. + The call has been put on hold by the local user, e.g. using + the Hold interface. This flag SHOULD only be set + if there is at least one Content, and all Contents are + locally held; it makes sense on calls in state + Call_State_Pending_Receiver + or Call_State_Accepted. Otherwise, in transient situations where some but not all contents @@ -346,8 +750,9 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. The initiator of the call originally called a contact other than the current recipient of the call, but the call was then forwarded or diverted. This flag only makes sense on outgoing calls, in state - Call_State_Pending_Receiver or Call_State_Accepted. It SHOULD be - set or unset according to informational messages from other contacts. + Call_State_Pending_Receiver or + Call_State_Accepted. It SHOULD be set or unset + according to informational messages from other contacts. @@ -359,9 +764,9 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. status code 183 Session Progress, and could be used when the outgoing call has reached a gateway, for instance. This flag only makes sense on outgoing calls in state - Call_State_Pending_Receiver, and SHOULD be set or unset according to - informational messages from servers, gateways and other - infrastructure. + Call_State_Pending_Receiver, and SHOULD be set + or unset according to informational messages from servers, gateways + and other infrastructure. @@ -385,11 +790,12 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. The call has been muted by the local user, e.g. using the - Mute.DRAFT interface. This flag SHOULD only be set if - there is at least one Content, and all Contents are locally muted; - it makes sense on calls in state Call_State_Pending_Receiver or - Call_State_Accepted. + Mute.DRAFT interface. This flag SHOULD only + be set if there is at least one Content, and all Contents + are locally muted; it makes sense on calls in state + Call_State_Pending_Receiver or + Call_State_Accepted. @@ -409,7 +815,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
An optional human-readable message sent when the call was ended, corresponding to the Message argument to the Hangup method. This is only - applicable when the call state is Call_State_Ended. + applicable when the call state is Call_State_Ended. XMPP Jingle can send such messages. @@ -418,7 +824,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
queue-message - s
An optional human-readable message sent when the local contact is being held in a queue. This is only applicable when - Call_Flag_Queued is in the call flags. + Call_Flags_Queued is in the call flags. SIP 182 notifications can have human-readable messages attached. @@ -428,7 +834,8 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
A message giving further details of any error indicated by the CallStateReason. This will not normally be localized or suitable for display to users, and is only - applicable when the call state is Call_State_Ended.
+ applicable when the call state is + Call_State_Ended.
@@ -442,6 +849,12 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. and CallStateDetails explain the reason for the current values for those properties.

+

Note that when in a conference call, this property is + purely to show your state in joining the call. The receiver + (or remote contact) in this context is the conference server + itself. The property does not change when other call members' + states change.

+

Clients MAY consider unknown values in this property to be an error.

@@ -456,6 +869,9 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.

Clients are expected to ignore unknown flags in this property, without error.

+ +

When an ongoing call is active and not on hold or has any + other problems, this property will be 0.

@@ -496,6 +912,18 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. of a Call_State_Reason struct.

+ + + + +

The CallState changed from + Call_State_Pending_Receiver to + Call_State_Ended because the initiator + ended the call before the receiver accepted it. With an + incoming call this state change reason signifies a missed + call.

+ + @@ -515,7 +943,10 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. The reason, chosen from a limited set of possibilities defined by - the Telepathy specification. + the Telepathy specification. If + Call_State_Change_Reason_User_Requested then + the Actor member will dictate whether it was the local user or + a remote contact responsible. @@ -592,9 +1023,9 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. + type="b" access="read" tp:immutable="yes"> -

If this property is TRUE, all of the media streaming is done by some +

If this property is True, all of the media streaming is done by some mechanism outside the scope of Telepathy.

@@ -604,11 +1035,10 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. audio streaming for the call).

 -

If this is FALSE, the handler is responsible for doing the actual +

If this is False, the handler is responsible for doing the actual media streaming for at least some contents itself. Those contents - will have the Media.DRAFT interface, to communicate the necessary + will have the Media.DRAFT interface, to communicate the necessary information to a streaming implementation. Connection managers SHOULD operate like this, if possible.

@@ -663,6 +1093,19 @@ 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. + + @@ -700,38 +1143,50 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. - A mapping from the remote contacts that are part of this call to flags - discribing their status. This mapping never has the local user's handle - as a key. +

A mapping from the remote contacts that are part of this call to flags + describing their status. This mapping never has the local user's handle + as a key.

+ +

When the call ends, this property should be an empty list, + and notified with + CallMembersChanged

+ +

If the Call implements + Group and the Group members are + channel-specific handles, then this call SHOULD also use + channel-specific handles.

+ +

Anonymous members are exposed as channel-specific handles + with no owner.

 + type="s" 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. - - When implementing a voip gateway one wants the outgoing leg of the - gatewayed to have the same transport as the incoming leg. This - property allows the gateway to request a Call with the right - transport from the CM. - -

+

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.

+ + + When implementing a voip gateway one wants the outgoing leg of the + gatewayed to have the same transport as the incoming leg. This + property allows the gateway to request a Call with the right + transport from the CM. + + type="b" access="read" tp:immutable="yes" tp:requestable="yes"> -

If set to true in a channel request that will create a new channel, +

If set to True in a channel request that will create a new channel, the connection manager should immediately attempt to establish an audio stream to the remote contact, making it unnecessary for the - client to call - AddContent. -

+ client to call AddContent.

If this property, or InitialVideo, is passed to EnsureChannel (as opposed to CreateChannel), the connection manager SHOULD ignore @@ -739,25 +1194,21 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. channel as suitable; these properties only become significant when the connection manager has decided to create a new channel.

-

If true on a requested channel, this indicates that the audio +

If True on a requested channel, this indicates that the audio stream has already been requested and the client does not need to call RequestStreams, although it MAY still do so.

-

If true on an unrequested (incoming) channel, this indicates that +

If True on an unrequested (incoming) channel, this indicates that the remote contact initially requested an audio stream; this does not imply that that audio stream is still active (as indicated by - Contents).

- -

This property is immutable (cannot change), and therefore SHOULD - appear wherever immutable properties are reported, e.g. NewChannels - signals.

+ Contents).

-

This reduces D-Bus round trips.

 +

The name of this new content can be decided by using the + InitialAudioName property.

Connection managers that support the ContactCapabilities + namespace="ofdT.Connection.Interface">ContactCapabilities interface SHOULD represent the capabilities of receiving audio and/or video calls by including a channel class in a contact's capabilities with ChannelType = Call @@ -775,19 +1226,19 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.

Clients that are willing to receive audio and/or video calls SHOULD include the following among their channel classes if calling UpdateCapabilities + namespace="ofdT.Connection.Interface.ContactCapabilities">UpdateCapabilities (clients of a ChannelDispatcher + namespace="org.freedesktop.Telepathy">ChannelDispatcher SHOULD instead arrange for the ChannelDispatcher to do this, by including the filters in their HandlerChannelFilter + namespace="ofdT.Client.Handler">HandlerChannelFilter properties):

  • { ChannelType = Call }
    • -
  • { ChannelType = Call, InitialAudio = true } +
  • { ChannelType = Call, InitialAudio = True } if receiving calls with audio is supported
    • -
  • { ChannelType = Call, InitialVideo = true } +
  • { ChannelType = Call, InitialVideo = True } if receiving calls with video is supported
@@ -800,12 +1251,12 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. + type="b" access="read" tp:immutable="yes" tp:requestable="yes">

The same as InitialAudio, but for a video stream. This property is immutable (cannot change).

-

In particular, note that if this property is false, this does not +

In particular, note that if this property is False, this does not imply that an active video stream has not been added, only that no video stream was active at the time the channel appeared.

@@ -815,13 +1266,49 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. + + + +

If InitialAudio is set to + True, then this property will name the intial audio content + with the value of this property.

+ + +

Content names are meant to be significant, but if no name + can be given to initial audio content, then its name cannot + be meaningful or even localized.

+ + +

If this property is empty or missing from the channel + request and InitialAudio is True, then the CM must come up + with a sensible for the content, such as "audio".

+ +

If the protocol has no concept of stream names then this + property will not show up in the allowed properties list of + the Requestable Channel Classes for call channels.

+ + + + + + +

The same as + InitialAudioName, but for a + video stream created by setting + InitialVideo to True. This + property is immutable and so cannot change.

+ + + + type="b" access="read" tp:immutable="yes"> -

If True, a stream of a different content type can be added +

If True, a stream of a different content type can be added after the Channel has been requested

-

If this property is missing, clients SHOULD assume that it is false, +

If this property is missing, clients SHOULD assume that it is False, and thus that the channel's streams cannot be changed once the call has started.

@@ -839,11 +1326,6 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. video once the call has started for contacts without this flag.

- -

This property is immutable, and therefore SHOULD be announced - in NewChannels, - etc.

 @@ -862,32 +1344,32 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.

The client can implement streaming for streams whose Transport - property is Stream_Transport_Type_GTalk_P2P.

+ namespace="ofdT.Call.Stream.Interface.Media.DRAFT">Transport + property is Stream_Transport_Type_GTalk_P2P.

The client can implement streaming for streams whose Transport - property is Stream_Transport_Type_ICE.

+ namespace="ofdT.Call.Stream.Interface.Media.DRAFT">Transport + property is Stream_Transport_Type_ICE.

 - +

The client can implement streaming for streams whose Transport - property is Stream_Transport_Type_WLM_8_5.

+ namespace="ofdT.Call.Stream.Interface.Media.DRAFT">Transport + property is Stream_Transport_Type_WLM_2009.

 - +

The client can implement streaming for streams whose Transport - property is Stream_Transport_Type_WLM_2009.

+ namespace="ofdT.Call.Stream.Interface.Media.DRAFT">Transport + property is Stream_Transport_Type_SHM.

 @@ -918,7 +1400,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.

For example, a client could advertise support for audio and video calls using Speex, Theora and H264 by having five handler capability tokens in its Capabilities + namespace="ofdT.Client.Handler">Capabilities property:

    diff --git a/spec/Channel_Type_Contact_Search.xml b/spec/Channel_Type_Contact_Search.xml index de58bfc..335c71f 100644 --- a/spec/Channel_Type_Contact_Search.xml +++ b/spec/Channel_Type_Contact_Search.xml @@ -352,7 +352,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.SearchStateChanged will be emitted, with the state Failed and the error - org.freedesktop.Telepathy.Errors.Cancelled.

    + org.freedesktop.Telepathy.Error.Cancelled.

    Calling this method on a search in state Completed or Failed succeeds, but has no effect.

    diff --git a/spec/Channel_Type_Room_List.xml b/spec/Channel_Type_Room_List.xml index 6d6ce31..98f7458 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 0000000..1f3348e --- /dev/null +++ b/spec/Channel_Type_Server_TLS_Connection.xml @@ -0,0 +1,69 @@ + + + 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 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 + containing the certificate chain as sent by the server, + and other relevant information.

    +

    This property is immutable.

    +     +     + + + + + The hostname of the server we expect ServerCertificate + to certify; clients SHOULD verify ServerCertificate against + this hostname when checking its validity. + + + +     +     + diff --git a/spec/Channel_Type_Streamed_Media.xml b/spec/Channel_Type_Streamed_Media.xml index 5445659..aa2b903 100644 --- a/spec/Channel_Type_Streamed_Media.xml +++ b/spec/Channel_Type_Streamed_Media.xml @@ -771,14 +771,14 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.HandlerChannelFilter: 
    -{ '...Channel.Type': '...Channel.Type.StreamedMedia' ,
+{ '...Channel.ChannelType': '...Channel.Type.StreamedMedia' ,
   '...Channel.TargetHandleType': Contact,
 }
    To advertise support for audio calls, also include the following filter:
    -{ '...Channel.Type': '...Channel.Type.StreamedMedia' ,
+{ '...Channel.ChannelType': '...Channel.Type.StreamedMedia' ,
   '...Channel.TargetHandleType': Contact,
   '...Channel.Type.StreamedMedia.InitialAudio': True,
 }
    @@ -786,7 +786,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.To advertise support for video calls, also include the following filter: 
    -{ '...Channel.Type': '...Channel.Type.StreamedMedia' ,
+{ '...Channel.ChannelType': '...Channel.Type.StreamedMedia' ,
   '...Channel.TargetHandleType': Contact,
   '...Channel.Type.StreamedMedia.InitialVideo': True,
 }
    diff --git a/spec/Channel_Type_Text.xml b/spec/Channel_Type_Text.xml index e3cd6b9..9cbfea2 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/Client_Handler.xml b/spec/Client_Handler.xml index 10a16bd..2cceed1 100644 --- a/spec/Client_Handler.xml +++ b/spec/Client_Handler.xml @@ -279,11 +279,21 @@ org.freedesktop.Telepathy.Channel.Interface.MediaSignalling/video/h264=true -

    Additional information about these channels. No keys are - currently defined.

    - -

    If keys are defined for this dictionary, all will be optional; - handlers MAY safely ignore any entry in this dictionary.

    +

    Additional information about these channels. Currently defined + keys are:

    + +
    +
    request-properties - a{oa{sv}}
    +
    A map from ChannelRequest + paths listed in Requests_Satisfied to + Qualified_Property_Value_Maps containing + namespaced immutable properties of each request.
    +
    + +

    When more keys are defined for this dictionary, all will be + optional; handlers MAY safely ignore any entry in this + dictionary.

         diff --git a/spec/Client_Handler_Future.xml b/spec/Client_Handler_Future.xml index 776fa4f..4c1a8b7 100644 --- a/spec/Client_Handler_Future.xml +++ b/spec/Client_Handler_Future.xml @@ -33,15 +33,38 @@ API or ABI guarantees.

    + + + +

    If true, channels destined for this handler are not passed to + observers for observing.

    + + +

    This is useful in use-cases where the handler doesn't want anyone + observing the channel - for example, because channels it handles + shouldn't be logged.

    +     + +

    For service-activatable handlers, this property should be specified + in the handler's .client file as follows:

    + +
    +[org.freedesktop.Telepathy.Client.Handler]
+BypassObservers=true
+
    +     +     +

    If true, channels destined for this handler that have the Conference.DRAFT interface, with a channel that + >Conference interface, with a channel that was previously handled by the same client process in their - InitialChannels property, should bypass the approval stage. In effect, this is a weaker form of UserActionTime and Account - MUST be included.

    + MUST be included, and Hints + SHOULD be included if implemented.

     diff --git a/spec/Client_Observer.xml b/spec/Client_Observer.xml index 912edaf..01fee8b 100644 --- a/spec/Client_Observer.xml +++ b/spec/Client_Observer.xml @@ -326,7 +326,9 @@ Recover=true - The requests satisfied by these channels. + The ChannelRequests + satisfied by these channels. If the same process is an Observer and a Handler, it can be useful @@ -356,6 +358,13 @@ Recover=true the same observer crashed). + +
    request-properties - a{oa{sv}}
    +
    A map from ChannelRequest + paths listed in Requests_Satisfied to + Qualified_Property_Value_Maps containing + namespaced immutable properties of each request.

    All defined keys for this dictionary are optional; diff --git a/spec/Connection.xml b/spec/Connection.xml index 3109670..a694e24 100644 --- a/spec/Connection.xml +++ b/spec/Connection.xml @@ -722,7 +722,7 @@ USA.

    reasons SHOULD be treated like this reason.

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

    + org.freedesktop.Telepathy.Error.Disconnected.

     @@ -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 +

    +     +     @@ -952,7 +985,7 @@ USA.

    Connection_Status_Reason, or may be a more specific Telepathy error (such as - org.freedesktop.Telepathy.Errors.ConnectionRefused + org.freedesktop.Telepathy.Error.ConnectionRefused for Connection_Status_Reason_Network_Error) or a protocol-specific or connection-manager-specific error in a suitable namespace. @@ -977,13 +1010,10 @@ 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
    +
    user-requested (b), expected-hostname (s), certificate-hostname (s)
    +
    The same details defined in TLS_Certificate_Rejection.
    - -

    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.

    -     @@ -1020,6 +1050,125 @@ USA.

    + + + +

    Register a client's interest in notifications related to one or + more interfaces.

    + +

    Groups of notifications are identified by a token which is either + a D-Bus interface name, or a string that starts with a D-Bus + interface name. The meaning of each token is given by that D-Bus + interface, which MUST define it in its documentation.

    + + +

    Initially, all interests are in entire interface, but allowing + other strings allows subscription to part of an interface; for + instance, an interest in ...MailNotification/count could track + the number of messages without caring about their detailed + content.

    +     + +

    For each token with which this method interacts, the + Connection tracks an "interest count" (like a reference count) for + each unique bus name that has called this method. When a client + calls this method, for each token, the interest count for its + unique bus name is incremented; when + RemoveClientInterest is called, + all interest counts for that unique bus name are decremented. + If the unique bus name leaves the bus (for instance, if the + client crashes or exits), all interest counts for that unique bus + name are set to zero.

    + +

    The Connection can then use these reference counts to + avoid subscribing to protocol-level notifications unless at least + one client has a non-zero interest count for the relevant + token.

    + + +

    This method exists to reduce memory and network overhead when + there is no active subscription.

    + +

    One situation where this is useful is Location: on XMPP, location updates are received + over PEP. If the Connection advertises the + geoloc+notify capability, it will be sent location + updates for all contacts. To avoid consuming resources for this, + the connection should avoid advertising that capability until + a client has expressed an interest in contacts' locations.

    + +

    Another example of a protocol that benefits from this method is + the Google XMPP Mail Notification extension, which can be used + to implement MailNotification. In this protocol, the CM + receives a notification that something has changed, but to get + more information, the CM must request this information. Knowing + that nobody is currently interested in this information, the CM + can avoid generating useless network traffic. Similarly, the CM + may free the list of unread messages to reduce memory overhead.

    +     + +

    If this method is called for an interface that might require + protocol-level subscription, but the connection cannot set up + that subscription yet (for instance because the + Status is not Connected yet), the + Connection MUST remember the client's interest, and attempt to + subscribe to the appropriate protocol feature when this becomes + possible.

    + +

    Clients MAY ignore any errors raised by this method; it is intended + to be called with the reply ignored.

    + + +

    The only reason it could fail is if it's unimplemented, in which + case the only thing the client can usefully do is to proceed as if + it had succeeded.

    +     +     + + + +

    Interfaces or parts of interfaces in which to register an + interest, represented by either a + DBus_Interface, or a string prefixed with a + DBus_Interface.

    + +

    If the Connection does not support one of these tokens, this + is not considered to be an error; the unsupported token is + simply ignored.

    +     +     +     + + + + +

    Release an interest registered using + AddClientInterest. See that + method's documentation for details.

    + +

    Clients MAY ignore any errors raised by this method; it is intended + to be called with the reply ignored.

    + + +

    The only reasons it could fail are if it's unimplemented, or if + the client's reference-counting is wrong and it has tried to + remove a client interest that it did not add. In both cases, + there's nothing the client could do about it.

    +     +     + + + +

    Interfaces or parts of interfaces that were previously passed to + AddClientInterest.

    +     +     +     +

    This models a connection to a single user account on a communication service. Its basic capability is to provide the facility to request and diff --git a/spec/Connection_Interface_Addressing.xml b/spec/Connection_Interface_Addressing.xml new file mode 100644 index 0000000..497c6d0 --- /dev/null +++ b/spec/Connection_Interface_Addressing.xml @@ -0,0 +1,258 @@ + + + Copyright (C) 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 draft) + +

    This interface deals with the multiple address types that can + refer to the same contact, such as vCard fields and URIs.

    + +

    It can be used to retrieve contacts with a specific addresses + through GetContactsByVCardField and + GetContactsByURI, as well as + defining the various addressing methods for a given contact + through this interface's contact attributes.

    +     + + + + +

    The vCard field of the addresses we are requesting. The + field name SHOULD be in lower case. Supported + fields can be found in + AddressableVCardFields.

    + +

    The url vCard field MUST NOT appear here; see + GetContactsByURI instead.

    + + +

    In practice, protocols have a limited set of URI + schemes that make sense to resolve as a contact.

    +     + +     +     + + + The addresses to get contact handles for. The address types + should match the given vCard field. + + + + +

    A list of strings indicating which D-Bus interfaces the calling + process is interested in. All supported attributes from these + interfaces, whose values can be obtained without additional network + activity, will be in the reply.

    + +

    Attributes from this interface and from + org.freedesktop.Telepathy.Connection + are always returned, and need not be requested + explicitly.

    + +

    The behavior of this parameter is similar to the same + parameter in + Contacts.GetContactAttributes.

    +     +     + + + +

    A dictionary mapping the contact handles to contact attributes. + If any of the requested addresses are in fact invalid, they are + simply omitted from this mapping. If contact attributes are not + immediately known, the behaviour is defined by the interface; + the attribute should either be omitted from the result or + replaced with a default value.

    + +

    Requested addresses that cannot be satisfied MUST be ommitted + from the mapping.

    + +

    Each contact's attributes will always include at least the + identifier that would be obtained by inspecting the handle + (org.freedesktop.Telepathy.Connection/contact-id), + and the vCard field used for requesting the contact in + org.freedesktop.Telepathy.Connection.Interface.ContactInfo/info. +

    +     +     + + +

    Request contacts and retrieve their attributes using a given field + in their vCards.

    + +

    The connection manager should record that these handles are in + use by the client who invokes this method, and must not + deallocate the handles until the client disconnects from the + bus or calls the + Connection.ReleaseHandles + method.

    +     + + + + +     + + + + + The URI addresses to get contact handles for. Supported + schemes can be found in + AddressableURISchemes. + + + + +

    A list of strings indicating which D-Bus interfaces the calling + process is interested in. All supported attributes from these + interfaces, whose values can be obtained without additional network + activity, will be in the reply.

    + +

    Attributes from this interface and from + org.freedesktop.Telepathy.Connection + are always returned, and need not be requested + explicitly.

    + +

    The behavior of this parameter is similar to the same + parameter in + Contacts.GetContactAttributes.

    +     +     + + + +

    A dictionary mapping the contact handles to contact attributes. + If any of the requested addresses are in fact invalid, they are + simply omitted from this mapping. If contact attributes are not + immediately known, the behaviour is defined by the interface; + the attribute should either be omitted from the result or + replaced with a default value.

    + +

    Requested URIs that cannot be satisfied MUST be ommitted + from the mapping.

    + +

    Each contact's attributes will always include at least the + identifier that would be obtained by inspecting the handle + (org.freedesktop.Telepathy.Connection/contact-id). +

    +     +     + + +

    Request contacts and retrieve their attributes using URI addresses.

    + +

    The connection manager should record that these handles are in + use by the client who invokes this method, and must not + deallocate the handles until the client disconnects from the + bus or calls the + Connection.ReleaseHandles + method.

    +     + + + + +     + + + +

    A mapping of vCard fields and addresses that repreent + the given contact.

    +     + + +     + + + + The various vCard addresses that identify this contact. + + + + + + The various URI addresses that identify this contact. + + + + + +

    The contact's address, as it was requested + through GetContactsByVCardField. This + attribute MUST be ommitted if the contact was not retrieved + through GetContactsByVCardField.

    + +

    When retrieving more than one contact + through GetContactsByVCardField, + there needs to be a way to map the given contact back o the + original request.

    +     +     +     + + + +

    The contact's URI, as it was requested through + GetContactsByURI. This + attribute MUST be ommitted if the contact was not retrieved + through GetContactsByURI.

    + +

    When retrieving more than one contact + through GetContactsByURI, + there needs to be a way to map the given contact back o the + original request.

    +     +     +     + + + + The address that has been requested by + GetContactsByVCardField or + GetContactsByURI. + + + + + The vCard field used in GetContactsByVCardField. + + + + + + The address that was requested. + + + + + +     + + diff --git a/spec/Connection_Interface_Anonymity.xml b/spec/Connection_Interface_Anonymity.xml index 31f1554..704263c 100644 --- a/spec/Connection_Interface_Anonymity.xml +++ b/spec/Connection_Interface_Anonymity.xml @@ -111,60 +111,30 @@     + tp:name-for-bindings="Anonymity_Mandatory" + tp:is-connection-parameter='yeah'>

    This specifies whether or not the anonymity settings MUST be respected by the CM and any intermediaries between the local and remote contacts. If this is set to true but anonymity settings cannot be followed, then the session MUST be denied with a - org.freedesktop.Telepathy.Errors.WouldBreakAnonymity + org.freedesktop.Telepathy.Error.WouldBreakAnonymity error. Any client that sets AnonymityModes SHOULD also set this property first (rather than accepting the CM's default value).

    - -

    This property SHOULD also be made available as a parameter of the - same (fully-qualified) name to RequestConnection, - with the DBus_Property flag in its - Conn_Mgr_Param_Flags. For connections managed - by the AccountManager, - this property SHOULD be set via the Account Manager as follows:

    - -
    - UpdateParameters({ - "org.freedesktop.Telepathy.Connection.Interface.Anonymity.AnonymityMandatory": new_value - }, []) -
    + access="readwrite" tp:name-for-bindings="Anonymity_Modes" + tp:is-connection-parameter='yeah'>

    The currently enabled anonymity modes for the connection. Setting has the effect of requesting new modes for the connection, and may raise an error if the unsupported modes are set. Successfully changing the modes will result in emission of AnonymityModesChanged signal.

    - -

    This property SHOULD also be made available as a parameter of the - same (fully-qualified) name to RequestConnection, - with the DBus_Property flag in its - Conn_Mgr_Param_Flags. For connections managed - by the AccountManager, - this property SHOULD be set via the Account Manager as follows:

    - -
    - UpdateParameters({ - "org.freedesktop.Telepathy.Connection.Interface.Anonymity.AnonymityModes": new_value - }, []) -
    diff --git a/spec/Connection_Interface_Cellular.xml b/spec/Connection_Interface_Cellular.xml index bf0f1a9..99a3602 100644 --- a/spec/Connection_Interface_Cellular.xml +++ b/spec/Connection_Interface_Cellular.xml @@ -30,7 +30,8 @@ + type="u" access="readwrite" + tp:is-connection-parameter='yup'>

    Define how long should the service centre try message delivery before giving up, failing delivery and deleting the message. A value of 0 @@ -40,55 +41,48 @@ implementations may round the value up (eg. to a minute or hour precision). The maximum validity period may vary depending on protocol or provider.

    +     +     -

    Connections with this interface SHOULD provide this property as a - parameter of the same (fully-qualified) name to ConnectionManager.RequestConnection, with the - DBus_Property flag. For connections managed by the - AccountManager, - this property SHOULD be set via the Account Manager as follows:

    - -
    - UpdateParameters({ - "org.freedesktop.Telepathy.Connection.Interface.Cellular.MessageValidityPeriod": new_validity_period - }, []) -
    - -

    The AccountManager provides change-notification, as long as all - other clients cooperate by using it instead of setting this property - directly.

    + + Previously, as an undocumented + feature, setting MessageServiceCentre + to the empty string caused the SIM's default SMSC to be used. + +

    If True, SMSes will be sent via the service centre + specified by MessageServiceCentre. If + False, the SIM's default SMSC will be used, ignoring the + value of MessageServiceCentre.

    + + +

    It could be desirable for a configuration interface to remember + the user's previous choice of custom SMSC, even if it's not in use. + This boolean allows that choice to be saved as an account parameter + by Mission Control, rather than the UI needing to save it elsewhere + to be restored if the user wants to reactivate it.

    +     + type="s" access="readwrite" + tp:is-connection-parameter='HELL YEAH!!!'> + This property's value is now + ignored unless + OverrideMessageServiceCentre is + True. + +

    Address for the messaging service centre. Typically (as is the case for GSM's SMSC), it's the ISDN / telephony address (ie. a phone - number).

    - -

    Connections with this interface SHOULD provide this property as a - parameter of the same (fully-qualified) name to ConnectionManager.RequestConnection, with the - DBus_Property flag. For connections managed by the - AccountManager, - this property SHOULD be set via the Account Manager as follows:

    - -
    - UpdateParameters({ - "org.freedesktop.Telepathy.Connection.Interface.Cellular.MessageServiceCentre": new_smsc_address - }, []) -
    - -

    The AccountManager provides change-notification, as long as all - other clients cooperate by using it instead of setting this property - directly.

    + number). If + OverrideMessageServiceCentre is + False, this property's value should be ignored by the CM + in favour of the SIM's default SMSC.

         @@ -120,7 +114,8 @@ + type="b" access="readwrite" + tp:is-connection-parameter='no... just kidding! yes!'>

    Determines whether SMSes containing characters that do not fit into a 7‐bit GSM character set should be sent as UCS‐2, or lossily @@ -129,26 +124,6 @@ financial cost of using twice as many SMSes); if True, the message will be recoded in an implementation‐specific way to fit into a country‐specific GSM reduced character set.

    - -

    Connections with this interface SHOULD provide this property as a - parameter of the same (fully-qualified) name to ConnectionManager.RequestConnection, with the - DBus_Property flag. For connections managed by the - AccountManager, - this property SHOULD be set via the Account Manager as follows:

    - -
    - UpdateParameters({ - "org.freedesktop.Telepathy.Connection.Interface.Cellular.MessageReducedCharacterSet": new_value - }, []) -
    - -

    The AccountManager provides change-notification, as long as all - other clients cooperate by using it instead of setting this property - directly.

         diff --git a/spec/Connection_Interface_Client_Types.xml b/spec/Connection_Interface_Client_Types.xml new file mode 100644 index 0000000..9790856 --- /dev/null +++ b/spec/Connection_Interface_Client_Types.xml @@ -0,0 +1,218 @@ + + + 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) + + + +

    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
      • + +
    + +

    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 returned client types are those for the resource whose + presence will be retreived using the + SimplePresence + interface.

    + +

    For example, if a contact has two resources:

    + +
      +
    • their phone, with presence "available"; and
      • +
    • their pc, with presence "busy";
      • +
    + +

    then the methods in this interface will return an array (with + one element: "phone") as the client types because that is the more + available resource. If at some later time the contact's phone's presence + changes to "away", the + ClientTypesUpdated signal will + notify that the contact's client types attribute has 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.

    +     +     + + + A string representing a single client type of a + contact. + + +     +     + diff --git a/spec/Connection_Interface_Communication_Policy.xml b/spec/Connection_Interface_Communication_Policy.xml new file mode 100644 index 0000000..9a92fa0 --- /dev/null +++ b/spec/Connection_Interface_Communication_Policy.xml @@ -0,0 +1,163 @@ + + + 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 +Library 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 interface supports controlling which contacts are allowed + to initiate text chats, incoming calls, and other forms of + communication as supported by the underlying protocol. The + policies supported for different communication methods on this + connection are listed in the + SupportedPolicies property. The + current configuration is held in + ActivePolicies; it can be modified + using SetPolicy, and changes + are signalled by PolicyChanged. +

    +     + + + + A mapping of communication methods (channel types), and their + associated policy. + + + + + The channel interface with the policy. + + + + + + The active policy for this channel type. + + + + + + + The communication policies supported by this connection. + + + + + +

    The active communication policies on this + connection. Communication methods that are not in this + mapping are considered open.

    + +

    For example, to allow incoming calls only from contacts + buddy list, and to allow text messages from anyone, + the policy would look like this:

    + + 
    +{
+    'org.freedesktop.Telepathy.Channel.Type.Text' : Access_Control_Type_Open,
+    'org.freedesktop.Telepathy.Channel.Type.Call' : Access_Control_Type_Publish_List
+}
+
    + +

    Changes to this property are signalled by + PolicyChanged.

    +     +     + + + + Set a policy for a communication method (channel + type). Depending on the server or protocol, more than one + communication method could be bound to the same policy, if + calling this method on one channel type changes the policy on + another channel type, the PolicyChanged + signal that would follow would include all the channel types + that have an altered policy. + + + + The channel type to set the policy for. + + + + + The policy to set for this channel. + + + + + + + ActivePolicies has + changed. This occurs when the server unilaterally changed the + policy or SetPolicy has been + called. + + + + A subset of the active policies that have changed. + + + + + + +

    The communication methods (channel types), and the policies + that can be applied to them. This is server and protocol + dependant.

    + +

    Grouped channel types will always have the same policy applied + to them.

    + + + Different protocols have different limitations to the + granularity of communication policies. One protocol might be + able to set a different policy for VoIP calls and text chat, + while another protocol might only be able to set one policy + to both VoIP and text chat. + +     + + + A list of channel interfaces that support these policies. + + + + + A list of supported policies. + + +     + +     +     diff --git a/spec/Connection_Interface_Contact_Groups.xml b/spec/Connection_Interface_Contact_Groups.xml index 87ab752..5282a82 100644 --- a/spec/Connection_Interface_Contact_Groups.xml +++ b/spec/Connection_Interface_Contact_Groups.xml @@ -18,15 +18,63 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.

    - + - - (draft 1) + + (as stable API)

    An interface for connections in which contacts can be placed in user-defined groups.

    + +

    The most basic functionality of this interface is to list and monitor + a contact's set of groups. To do this, use the + GroupsChanged signal, and the + groups contact attribute (this should + usually be done by connecting to the GroupsChanged signal, then + calling GetContactListAttributes with this interface + included in the Interfaces argument). Simple user interfaces can + limit themselves to displaying that information, and ignore the rest + of this interface: to ensure that this works, + GroupsChanged is emitted for every + change, even if that change could be inferred from another signal + such as GroupsRemoved.

    + +

    Looking at contacts' lists of groups is sufficient to present a + user interface resembling XMPP's data model, in which groups behave + like tags applied to contacts, and so an empty group cannot exist + or is not interesting. However, some protocols model groups as + objects in their own right. User interfaces may either track + the set of groups via the Groups + property and the GroupsCreated and + GroupsRemoved signals, or ignore + this extra information.

    + +

    Similarly, in some protocols it is possible to rename a group as + a single atomic operation. Simpler user interfaces will + see the new name being created, the old name being removed, and the + members moving to the new name, via the signals described above. + More advanced user interfaces can optionally distinguish between an + atomic rename and a create/remove pair, and display renamed groups + differently, by monitoring the + GroupRenamed signal.

    + +

    This interface also provides various methods to manipulate + user-defined groups, which can be expected to work if + GroupStorage is not None.

    + +

    Depending on the protocol, some methods might be implemented by + more than one protocol operation; for instance, in a + "contact-centric" protocol like XMPP, + SetContactGroups is a single + protocol operation and SetGroupMembers + requires a protocol operation per contact, whereas in a more + "group-centric" protocol it might be the other way around. User + interfaces SHOULD call whichever method most closely resembles the + way in which the user's action was represented in the UI, and + let the connection manager deal with the details.

     + + + Emitted when contacts' groups change. + + + + The relevant contacts. + + + + The names of groups to which the contacts were + added. + + + + The names of groups from which the contacts were + removed. + + + @@ -79,11 +147,9 @@ distinguish between a create/remove pair and a renamed group by receiving GroupRenamed.

    -

    This property's value is not meaningful until the initial contact - list has been received, in protocols where this is applicable. - Clients MAY wait for this property to be meaningful by calling - RequestContactList.

    +

    This property's value is not meaningful until the + ContactListState has become Success.

         @@ -101,7 +167,9 @@ -

    Emitted when a group is renamed.

    +

    Emitted when a group is renamed, in protocols where this can + be distinguished from group creation, removal and membership + changes.

    Immediately after this signal is emitted, GroupsCreated MUST signal the @@ -112,7 +180,7 @@

    Emitting these extra signals, in this order, means that clients that are interested in the set of groups that exist (but treat a - rename and a create/remove pair identically) to ignore the + rename and a create/remove pair identically) can ignore the GroupRenamed signal entirely.

    @@ -168,26 +236,6 @@     - - - Emitted when contacts' groups change. - - - - The relevant contacts. - - - - The names of groups to which the contacts were - added. - - - - The names of groups from which the contacts were - removed. - - -

    Add the given contact to the given groups (creating new groups @@ -213,6 +261,14 @@ GroupsChanged and GroupsRemoved signals that result from this method call MUST be emitted before the method returns.

    + +

    This method SHOULD NOT be called until the + ContactListState changes to Success. + If the ContactListState is Failure, this method SHOULD raise the + same error as + GetContactListAttributes.

     @@ -239,6 +295,7 @@ is Contact_Metadata_Storage_Type_None, i.e. groups cannot be edited.     +     @@ -265,6 +322,14 @@ GroupsChanged and GroupsRemoved signals that result from this method call MUST be emitted before the method returns.

    + +

    This method SHOULD NOT be called until the + ContactListState changes to Success. + If the ContactListState is Failure, this method SHOULD raise the + same error as + GetContactListAttributes.

    @@ -286,6 +351,7 @@ is Contact_Metadata_Storage_Type_None, i.e. groups cannot be edited. + @@ -306,6 +372,14 @@ GroupsChanged and GroupsRemoved signals that result from this method call MUST be emitted before the method returns.

    + +

    This method SHOULD NOT be called until the + ContactListState changes to Success. + If the ContactListState is Failure, this method SHOULD raise the + same error as + GetContactListAttributes.

    @@ -326,6 +400,7 @@ is Contact_Metadata_Storage_Type_None, i.e. groups cannot be edited.     + @@ -341,6 +416,14 @@

    Any GroupsChanged or GroupsRemoved signals that result from this method call MUST be emitted before the method returns.

    + +

    This method SHOULD NOT be called until the + ContactListState changes to Success. + If the ContactListState is Failure, this method SHOULD raise the + same error as + GetContactListAttributes.

    @@ -366,6 +449,7 @@ is Contact_Metadata_Storage_Type_None, i.e. groups cannot be edited.     + @@ -378,6 +462,14 @@

    Any GroupsChanged or GroupsRemoved signals that result from this method call MUST be emitted before the method returns.

    + +

    This method SHOULD NOT be called until the + ContactListState changes to Success. + If the ContactListState is Failure, this method SHOULD raise the + same error as + GetContactListAttributes.

    @@ -393,6 +485,7 @@ is Contact_Metadata_Storage_Type_None, i.e. groups cannot be edited.     + @@ -412,6 +505,14 @@

    Any GroupRenamed or GroupsRemoved signals that result from this method call MUST be emitted before the method returns.

    + +

    This method SHOULD NOT be called until the + ContactListState changes to Success. + If the ContactListState is Failure, this method SHOULD raise the + same error as + GetContactListAttributes.

    @@ -439,6 +540,7 @@ Raised if there is already a group with the new name.     + diff --git a/spec/Connection_Interface_Contact_List.xml b/spec/Connection_Interface_Contact_List.xml index 9db86aa..d602c19 100644 --- a/spec/Connection_Interface_Contact_List.xml +++ b/spec/Connection_Interface_Contact_List.xml @@ -18,10 +18,9 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.

    - + - (draft 2) + (as stable API)

    An interface for connections that have any concept of a list of @@ -35,7 +34,7 @@

    In some protocols (like link-local XMPP), while there might not be any server or roster, it's possible to list "nearby" contacts.

    -

    In Telepathy 0.18 and older, we represented contact lists as a +

    In Telepathy 0.20 and older, we represented contact lists as a collection of ContactList channels. This is remarkably difficult to @@ -46,87 +45,115 @@

    The list of contacts is not exposed as a D-Bus property; it can be - fetched using RequestContactList. + fetched using GetContactListAttributes.

    In some protocols, such as XMPP, the contact list may not be available immediately. The - RequestContactList method - will wait until the contact list is available before returning. + GetContactListAttributes method + will fail until the contact list is available. Using a method also allows extra attributes to be retrieved at the same time.

         - - (in draft: renamed from - GetContactListAttributes) - -

    Return some contact attributes for a list of contacts somehow - associated with the user.

    + + + The progress made in retrieving the contact list. + + + + The connection has not started to retrieve the contact + list. If GetContactListAttributes is + called in this state, it will raise NotYet. + + + + The connection has started to retrieve the contact + list, but has not yet succeeded or failed. + If GetContactListAttributes is called + in this state, it will raise NotYet. + + + + +

    The connection has tried and failed to retrieve the contact + list. If GetContactListAttributes + is called in this state, it will immediately raise an error + indicating the reason for failure.

    + +

    The connection manager SHOULD try again to obtain the contact + list, if appropriate for the protocol. If it succeeds later, + the ContactListState MUST advance + to Success.

    +     +     -

    This definition is deliberately vague: in practice, most user - interfaces should display some subset of this list, by filtering it - by some contact attributes (for instance, displaying all contacts - whose "subscribe" attribute is Yes is expected to be a common case). - This list MAY contain any contacts whatsoever, but MUST contain - at least the following:

    + + The connection has successfully retrieved the contact + list. If GetContactListAttributes + is called in this state, it will return successfully. + +     + + + + The progress made in retrieving the contact list. + Change notification is via + ContactListStateChanged. + + + + + + Emitted when ContactListState + changes. + + + + + The new value of ContactListState. + + + + + + +

    Return some contact attributes for a list of contacts + associated with the user. This list MUST include at least:

      -
    • all contacts whose "subscribe" attribute is Ask or Yes
      • -
    • all contacts whose "publish" attribute is Ask or Yes
      • -
    • all contacts with a persistently-stored stored alias, if - supported
      • -
    • all contacts in user-defined contact groups, if supported
      • +
    • all contacts whose subscribe + attribute is not No
      • +
    • all contacts whose publish + attribute is not No
    -

    This list does not need to contain every visible contact: for - instance, contacts seen in XMPP or IRC chatrooms SHOULD NOT appear - here. Blocked contacts SHOULD NOT appear here either, unless they - are still stored in a persistent roster/contact list as well as - being blocked.

    +

    but MAY contain other contacts.

    -

    This is basically the union of the historical ContactList subscribe, publish and stored - channels.

    - -

    For example, XMPP, it's the roster; on link-local XMPP, it's the - set of visible users on the local network; on MSN, it's the union - of the forward and reverse buddy lists.

    - -

    An easy way for an application to display a contact list is to - call this method with at least this interface in the Interfaces - argument, then check which subset of contacts should be displayed - (perhaps based on their subscribe attribute, for instance) and display - them. Any additional information required to display the contact - list, like aliases or presence, can be retrieved at the same - time.

    - -

    In practice, most user interfaces for the contact list will - usually display a large proportion of this list - (for instance, most contacts on the contact list will usually - have subscribe=Yes in practice, so contact lists that display - subscribe=Yes contacts need to display almost the entire list), - so the overhead of returning information about too many contacts - is small.

    +

    For instance, on XMPP, all contacts on the roster would appear + here even if they have subscription="none", unless there's + reason to believe the user does not want to see them (such as + having been blocked).

     -

    This method SHOULD NOT return before the contact list has been - retrieved, on protocols where this is possible. As a result, - clients SHOULD use a longer-than-default timeout for this method - call, since retrieving the contact list can take a significant - time on some servers.

    +

    This list does not need to contain every visible contact: for + instance, contacts seen in XMPP or IRC chatrooms SHOULD NOT appear + here. Blocked contacts SHOULD NOT appear here, unless they still + have a non-No subscribe or + publish attribute + for some reason.

    -

    This makes it possible for clients to wait for the contact list. - For instance, on XMPP this method shouldn't return until the - roster has been retrieved, which is an asynchronous process. - However, on link-local XMPP you can't know when you have the - complete list, so this method would have to return immediately.

    +

    It's reasonable to assume that blocked contacts should not be + visible to the user unless they specifically go looking for them, + at least in protocols like XMPP where blocking a contact + suppresses presence.

         @@ -150,12 +177,6 @@ Equivalent to the corresponding argument to GetContactAttributes.

    - -

    FIXME: if we do distributed refcounting, we should probably - rename this to 'Reference' and implement handle-refcounting - semantics first? On the other hand, if we make handles persist - for the lifetime of the connection, we can just remove this - parameter.

         @@ -171,31 +192,64 @@ - + + + + + + +

    The ContactListState is + None or Waiting. In particular, this error is raised if the + Status + is not yet Connection_Status_Connected.

    +     +     - + -

    A tristate indicating whether presence subscription is denied, +

    An enumeration indicating whether presence subscription is denied, denied but pending permission, or allowed. The exact semantics - vary according to where this type is used.

    + vary according to where this type is used: see the + subscribe and + publish contact attributes for + details.

     - - Presence information cannot be seen. + + The presence subscription state is + unknown. + + + + Presence information cannot be seen, and either the + subscription state Removed_Remotely does not apply, or it is + not known whether that state applies. + - - Presence information cannot be seen, but permission - to see presence information has been requested. + + + Presence information cannot be seen because the + remote contact took action: either the local user's request to + see the remote contact's presence was denied, or the remote + contact requested to see the local user's presence but then + cancelled their request. + + + + Presence information cannot be seen. Permission + to see presence information has been requested, and the request + has not yet been declined or accepted. - + + Presence information can be seen.     + type="u" tp:type="Subscription_State">

    If this attribute on a contact is Yes, this connection can expect to receive their presence, along with any other information @@ -207,7 +261,7 @@ the local user's buddy list" in ICQ, for example.

    -

    If this attribute is No or Ask, the local user cannot generally +

    If this attribute is not Yes, the local user cannot generally expect to receive presence from this contact. Their presence status as returned by GetPresences @@ -229,18 +283,30 @@ asked during the current session will ever have Ask status.

    -

    This attribute SHOULD be omitted from the - Contact_Attributes_Map returned by - GetContactAttributes until the initial contact - list has been received, in protocols where this is applicable. - Clients MAY wait for this by calling - RequestContactList.

    +

    If this attribute is Removed_Remotely, this indicates that the + local user has asked to receive the contact's presence at some time, + but the remote contact has rejected that request, and a local + user interface has not yet acknowledged this. It is + implementation-dependent whether contacts' subscribe attributes can + remain set to Removed_Remotely, or are reset to No, when the + connection disconnects.

    + +

    After notifying the user, user interfaces MAY acknowledge a change + to subscribe=Removed_Remotely by calling either + Unsubscribe or + RemoveContacts, which will set + subscribe to No (and perhaps remove the contact). This + allows user interfaces to detect that the user has been notified + about the rejected request.

    + +

    This attribute's value will be Unknown or omitted until the + ContactListState has changed to + Success.

         + type="u" tp:type="Subscription_State">

    If this attribute on a contact is Yes, the local user's presence is published to that contact, along with any other information that @@ -254,12 +320,12 @@ the contact's buddy list" in ICQ, for example.

    -

    If this attribute is No or Ask, the +

    If this attribute is not Yes, the local user's presence is not published to that contact; however, if it is Ask, the contact has requested that the local user's presence is made available to them.

    -

    It is implementation-dependent whether contacts' publish +

    It is implementation-dependent whether contacts' publish attributes can remain set to Ask, or are reset to No, when the connection disconnects.

    @@ -270,21 +336,32 @@ during the current session will ever have Ask status.

    -

    This attribute SHOULD be omitted from the - Contact_Attributes_Map returned by - GetContactAttributes until the initial contact - list has been received, in protocols where this is applicable. - Clients MAY wait for this by calling - RequestContactList.

    +

    If this attribute is Removed_Remotely, this indicates that the + remote contact has asked to receive the user's presence at some time, + but has then cancelled that request before a response was given by + the local user. User interfaces MAY reset publish from + Removed_Remotely to No, by calling either + Unpublish or + RemoveContacts.

    + +

    If multiple factors affect whether a contact can receive the local + user's presence, this attribute SHOULD reflect the overall + result. For instance, an XMPP contact with subscription="to" or + subscription="both", but who has been blocked via + XEP-0016 Privacy + Lists, SHOULD have publish=No.

    + +

    This attribute's value will be Unknown or omitted until the + ContactListState has changed to + Success.

         -

    If the "publish" attribute is Ask, an optional message that was - sent by the contact asking to receive the local user's presence; - omitted if none was given.

    +

    If the publish attribute is Ask, an + optional message that was sent by the contact asking to receive the + local user's presence; omitted if none was given.

    If the contact asking to receive our presence is also using @@ -294,17 +371,14 @@

    Otherwise, this SHOULD be omitted.

    -

    This attribute SHOULD be omitted from the - Contact_Attributes_Map returned by - GetContactAttributes until the initial contact - list has been received. Clients MAY wait for this by calling - RequestContactList.

    +

    This attribute will also be omitted until the + ContactListState has changed to + Success.

         - +

    If true, presence subscriptions (in both directions) on this connection are stored by the server or other infrastructure.

    @@ -323,17 +397,17 @@ presence from everyone else) so nothing is ever stored.

    -

    If CanChangeSubscriptions +

    If CanChangeContactList is true, Telepathy clients (e.g. user interfaces or address books) MAY keep a record of permission to publish and requests to subscribe locally, and attempt to restore it for each Connection. If - SubscriptionsPersist is false, clients MAY do this for all contacts; - if SubscriptionsPersist is true, clients SHOULD NOT change the state + ContactListPersists is false, clients MAY do this for all contacts; + if ContactListPersists is true, clients SHOULD NOT change the state of contacts that were not changed locally.

    -

    In SIMPLE (SIP), SubscriptionsPersist is false, but - CanChangeSubscriptions is true. Presence will not be received +

    In SIMPLE (SIP), ContactListPersists is false, but + CanChangeContactList is true. Presence will not be received unless clients renew any subscriptions they have for each connection, in the way described. There is no server-side storage, so clients have no alternative but to maintain independent contact @@ -359,10 +433,45 @@ - - Values of this enumeration indicate the extent to which metadata - such as aliases and group memberships can be stored for the contacts - on a particular connection. + +

    Values of this enumeration indicate the extent to which metadata + such as aliases and group memberships can be stored for the contacts + on a particular connection.

    + +

    On some protocols, certain metadata (for instance, contact aliases) + can only be stored for contacts on the contact list, or contacts + with a particular contact list state.

    + +

    To make it easier to deal with such protocols, if clients set + metadata on a contact who is not in the required state, the + Connection MUST cache the metadata for the duration of the session. + If clients request the attributes of that contact after the + appropriate "set" method has returned successfully, the Connection + MUST return the new (cached) value.

    + +

    If the contact is later placed in the required state to store + metadata (for instance, if subscription to the contact's presence + is requested, on a protocol like MSN where the alias has storage type + Subscribed_Or_Pending), the connection MUST store the cached + metadata at that time.

    + + +

    If the Connection didn't cache changes in this way, a client + intending to change the alias on MSN would have to wait until + the server acknowledged the subscription request; in the meantime, + other clients would still display the old alias.

    +     + +

    The only exception to that general rule is that if the Connection + cannot store particular metadata at all (i.e. the + storage type is None), it MUST reject attempts to set it.

    + + +

    If the implementation knows that metadata can't be stored at + all, it's useful to report that, which can be done + synchronously. In general, user interfaces should detect + storage type None and not display editing controls at all.

    +     @@ -391,22 +500,6 @@

    Contact aliases and groups on MSN have this behaviour.

     - -

    If this type of metadata is set on a contact with subscribe=No, - the Connection MUST cache it until disconnected, and return it - if requested. If subscription to the contact's presence is - subsequently requested, making it possible to store this metadata, - the Connection MUST store the cached value at that time.

    - - -

    This supports the recommended calling pattern for adding a - new contact, in which alias and groups are set (without - necessarily waiting for a reply) before requesting the - contact's presence. Until the subscription request is - processed by the server, the alias and groups will be cached - in memory; when the subscription request has been processed, - the connection manager will store the metadata on the server.

    -     @@ -419,19 +512,6 @@

    No service with this behaviour is currently known, but it's a stricter form of Subscribed_Or_Pending.

    - -

    If this type of metadata is set on a contact with subscribe != Yes, - the Connection MUST cache it until disconnected, and return it - if requested. If subscription to the contact's presence is - subsequently allowed, making it possible to store this metadata, - the Connection MUST store the cached value at that time.

    - - -

    The same rationale applies as for Subscribed_Or_Pending, - except that metadata must be stored until the subscription - request is not only processed by the server, but also allowed - by the remote user.

    -     @@ -455,13 +535,13 @@ A single contact's subscribe, publish and publish-request attributes. - + The new value of the contact's "subscribe" attribute. - + The new value of the contact's "publish" attribute. @@ -500,19 +580,32 @@

    Emitted when the contact list becomes available, when contacts' basic stored properties change, when new contacts are added to the list that would be returned by - RequestContactList, + GetContactListAttributes, or when contacts are removed from that list.

    This provides change notification for that list, and for - contacts' "subscribe", "publish" and - "publish-request" attributes.

    + contacts' subscribe, + publish and + publish-request attributes.

    +     + +

    Connection managers SHOULD also emit this signal when a contact + requests that the user's presence is published to them, even if + that contact's publish attribute is already + Ask and the publish-request has not changed.

    + + +

    If the same contact sends 10 identical requests, 10 identical + signals should be emitted.

     - The new subscribe, publish and publish-request attributes of all the + The new subscribe, + publish and + publish-request attributes of all the contacts that have been added, and all the contacts for which those attributes have changed. @@ -522,15 +615,15 @@ The contacts that have been removed from the list that would be returned by - RequestContactList. + GetContactListAttributes. This also implies that they have subscribe = No and publish = No; contacts MUST NOT be listed both here and in Changes. - +

    If true, presence subscription and publication can be changed using the @@ -590,10 +683,10 @@ request, with the given message, if allowed by the underlying protocol.

    -

    For contacts with subscribe=No, this method SHOULD request that - the contact allows the local user to subscribe to their presence; - in general, this will change their publish attribute from No - to Ask (although it could change directly from No to Yes in some +

    For contacts with subscribe=No or subscribe=Rejected, this method + SHOULD request that the contact allows the local user to subscribe + to their presence; in general, this will change their publish + attribute to Ask (although it could change directly to Yes in some situations).

    Any state changes that immediately result from this request MUST @@ -606,9 +699,20 @@

    If the remote contact accepts the request, their subscribe - attribute will later change from Ask to Yes; if they explicitly - reject the request (in protocols that allow this), their subscribe - attribute will later change from Ask to No.

    + attribute will later change from Ask to Yes.

    + +

    If the remote contact explicitly rejects the request (in protocols + that allow this), their subscribe attribute will later change from + Ask to Rejected.

    + +

    If the subscription request is cancelled by the local user, the + contact's subscribe attribute will change from Ask to No.

    + +

    This method SHOULD NOT be called until the + ContactListState changes to Success. + If the ContactListState changes to + Failure, this method SHOULD raise the same error as + GetContactListAttributes.

     + + + The ContactListState is None + or Waiting. + + It was not possible to perform the requested action, because - CanChangeSubscriptions is false. + CanChangeContactList is false. @@ -714,6 +824,12 @@

    This makes it easy for user interfaces to see what practical effect this method had.

    + +

    This method SHOULD NOT be called until the + ContactListState changes to Success. + If the ContactListState changes to + Failure, this method SHOULD raise the same error as + GetContactListAttributes.

    It was not possible to perform the requested action, because - CanChangeSubscriptions is false. + CanChangeContactList is false. + +     + + + The ContactListState is None + or Waiting. @@ -745,7 +867,7 @@

    If possible, this method SHOULD set the contacts' subscribe and publish attributes to No, remove any stored aliases for those contacts, and remove the contacts from the result of - RequestContactList.

    + GetContactListAttributes.

    This method SHOULD succeed even if it was not possible to carry out the request entirely or for all contacts (for instance, if there is an @@ -764,6 +886,12 @@ contact list's state), then consult its local cache of the contact list's state to see whether the contact is still there.

    + +

    This method SHOULD NOT be called until the + ContactListState changes to Success. + If the ContactListState changes to + Failure, this method SHOULD raise the same error as + GetContactListAttributes.

    It was not possible to perform the requested action because - CanChangeSubscriptions is false. + CanChangeContactList is false. + +     + + + The ContactListState is None + or Waiting. @@ -801,6 +935,12 @@ entirely or for all contacts; however, all signals that immediately result from this method call MUST be emitted before it returns.

    + +

    This method SHOULD NOT be called until the + ContactListState changes to Success. + If the ContactListState changes to + Failure, this method SHOULD raise the same error as + GetContactListAttributes.

    It was not possible to perform the requested action because - CanChangeSubscriptions is false. + CanChangeContactList is false. @@ -838,6 +978,12 @@ entirely or for all contacts; however, all signals that immediately result from this method call MUST be emitted before it returns.

    + +

    This method SHOULD NOT be called until the + ContactListState changes to Success. + If the ContactListState changes to + Failure, this method SHOULD raise the same error as + GetContactListAttributes.

    It was not possible to perform the requested action because - CanChangeSubscriptions is false. + CanChangeContactList is false. + + + + + The ContactListState is None + or Waiting. diff --git a/spec/Connection_Interface_Keepalive.xml b/spec/Connection_Interface_Keepalive.xml new file mode 100644 index 0000000..9f4ac68 --- /dev/null +++ b/spec/Connection_Interface_Keepalive.xml @@ -0,0 +1,73 @@ + + + + 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) + + +

    Most messaging protocols allow the client to send periodic + content-less pings to the server when the connection is otherwise idle, + to reassure both itself and the server that its connection is still + alive. Depending on the nature of the network connection, and the + device running the client, the desired interval between such pings may + vary.

    + + +

    For instance, on a mobile handset connected via 3G, + overly-frequent keepalives can drain the battery through needlessly + waking up the radio, and a relatively high interval is appropiate. By + contrast, a desktop computer is less likely to be asleep in the first + place, and users expect dropped connections to be noticed as soon as + possible.

    +     + +

    This interface provides a + KeepaliveInterval property which + controls the frequency of keepalive pings, if any. Connection managers + implementing this property should also include it in Protocol.Parameters + with the DBus_Property flag, allowing the desired value to + be stored in Account.Parameters + and passed onto the connection by the account manager.

    +     + + + +

    The time in seconds between pings sent to the server to ensure that + the connection is still alive, or 0 to disable such + pings.

    + +

    This property (and parameter) supersedes the older + keepalive-interval + Connection_Parameter_Name.

    +     +     + +     +     + diff --git a/spec/Connection_Interface_Location.xml b/spec/Connection_Interface_Location.xml index 6c69a80..fe54923 100644 --- a/spec/Connection_Interface_Location.xml +++ b/spec/Connection_Interface_Location.xml @@ -47,6 +47,15 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.Geoclue API where possible.

    + +

    Clients of this interface SHOULD register an interest in it by calling + Connection.AddClientInterest with an argument + containing the name of this interface, + before calling any Location method. If they do so, they SHOULD also call + Connection.RemoveClientInterest after use to allow + the CM to release resources associated with this interface.

    diff --git a/spec/Connection_Interface_Resources.xml b/spec/Connection_Interface_Resources.xml new file mode 100644 index 0000000..716089c --- /dev/null +++ b/spec/Connection_Interface_Resources.xml @@ -0,0 +1,212 @@ + + + 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.

    +     + + (draft 1) + + + +

    An interface on connections to show contact attributes for + specific resources of a contact, if the protocol supports + multiple resources. Resources are most common in XMPP, hence the + name of this interface, but they are also present in MSN, where + they are called points of presence.

    + +

    When a client requests some attribute of a contact using its + handle on the connection, the CM uses an algorithm to choose the + most appropriate resource for the job. If there is only one + resource, then the choice is obvious. If, however, there is more + than one resource connected at any one time, the CM either + aggregates all appropriate information to return (in the case of + capabilities), or chooses one specific resource (in the case of + presence).

    + +

    Resources in XMPP have names, and it can be extremely useful + for the user to be able to know which resources of a contact are + online, providing the names are human-readable. Before now, + resources have not been exposed in Telepathy, but this interface + attempts to change this.

    + +

    When using this interface, it is a little like using the + Contacts interface, but only resource-specific + attributes are ever returned. The resource-specific contact + attributes are decided on by the CM, but XMPP's are listed + below:

    + +
      +
    • SimplePresence/presence
      • +
    • ContactCapabilities/capabilities
      • +
    • ClientTypes/client-types
      • +
    + +     + + + + Return the resource information of the given contacts. If any + of the contact attributes for specific resources of the given + contacts' are not known return immediately without waiting for + a reply. + + + + + The contacts whose resource attributes should be returned. + + + + + +

    The contacts' resources and the contact attributes specific + to each resource. If contact attributes are not immediately + known, the behaviour is defined by the interface; the + attribute should either be omitted from the result or + replaced with a default value.

    + +

    For every contact handle passed into this method, it is + guaranteed that there will be a key in the returned map + that corresponds to said handle. If there is no information + regarding the contact the resource information map will be + empty.

    +     +     + + + + + +     + + + + + The resource string is never human-readable. + + + + + The resource string might be human-readable. + + + + + + +

    Whether the resources returned from GetResources + are human readable or not.

    + +

    If the connection manager knows that all resource names are + automatically generated, then the resource strings mean + nothing to the user. Showing these strings in the UI would + be confusing, so by setting this to + Resources_Human_Readability_Never, the UI is advised not to + show resources.

    + +

    If on the other hand, all resources are set to nice names + (such as "office" or "home") then it might be wise to expose + these strings in the UI, so this property would be set to + Resources_Human_Readability_Maybe. This is the case in XMPP -- + most resources are set in a way that the user can deduce some + information from them. The absence of an Always enum value is + because in the case of XMPP, the resource string could be + partially human-readable (as on Google Talk, where a resource + of "home" is changed by the server to a unique string like + "home_1234fdec") or not at all human-readable.

    + +     +     + + + + Emitted when a contact has a resource added or removed, or any + contact attribute for any resource changes. + + + + + The contact. + + + + + The contact's resource information. All resource information + is given, not just the details which have changed. + + + + + + + A map of a contact's resources to their resource-specific + information. + + + + +

    The name of the resource.

    +     +     + + + + A map of contact attributes whose data is specific to this + resource. + + +     + + + Mapping returned by + GetResources, representing a + collection of Contacts, their resources, and their + resource-specific contact attributes. + + + + A contact. + + + + + + A map of the contact's resources to their resource-specific + information. + + + + + + +

    The same mapping that would be returned by + GetResources for this contact.

    +     +     + +     +     + diff --git a/spec/Connection_Interface_Simple_Presence.xml b/spec/Connection_Interface_Simple_Presence.xml index 5c7ae97..7788161 100644 --- a/spec/Connection_Interface_Simple_Presence.xml +++ b/spec/Connection_Interface_Simple_Presence.xml @@ -349,17 +349,95 @@     + + +

    A type for communication access control. These control + policies are used in + CommunicationPolicy.DRAFT + as well as most rich presence interfaces.

    + +

    New interfaces should use this type, and NOT + Rich_Presence_Access_Control_Type.

    +     + + +

    Only allow contacts that are in a certain whitelist.

    + +

    The associated variant + in Access_Control is a list of + Contact_Handle representing + the whitelist, with signature au.

    +     +     + + + Allow contacts in the user's 'publish' list. The associated + variant in Access_Control is ignored. + + + + +

    Only allow contacts that are in a certain group.

    + +

    The associated variant in Access_Control is a + Group_Handle representing the permitted + group.

    +     +     + + + Allow all contacts. The associated + variant in Access_Control is ignored. + + + + + Allow all contacts in the user's 'subscribe' or 'publish' + list. The associated variant in Access_Control is + ignored. + + + + + Forbid all contacts. The associated variant in + Access_Control is ignored. + + + + +

    The access control rule is too complex to be represented + in the current Telepathy API. The associated variant is + meaningless. Setting this mode is never valid; the + connection manager MUST raise an error if this is attempted.

    + + + XEP-0016 Privacy Lists can easily produce access control + mechanisms that can't be expressed in a simpler API. We + need to be able to at least indicate that fact. + + +

    The associated variant in Access_Control is + ignored.

    +     +     +     + - - A type of access control for Rich_Presence_Access_Control. - For most types, the exact access control is given by an associated - variant. + +

    A type of access control for Rich_Presence_Access_Control. + For most types, the exact access control is given by an associated + variant.

    - These are the access control types from XMPP publish/subscribe - (XEP-0060). +

    These are the access control types from XMPP publish/subscribe + (XEP-0060).

     + +

    Location + uses this for historical reasons, new interfaces will use + Access_Control_Type.

     @@ -389,13 +467,42 @@     + + +

    An access control mode for extended presence items like geolocation. + This type isn't actually used by the SimplePresence interface, but + it's included here so it can be referenced by rich presence + interfaces.

    + +

    New interfaces should use this type, and NOT + Rich_Presence_Access_Control.

    +     + + + + The type of access control to apply. + + + + + Any additional information required by the Type. The required + type and semantics are defined for each + Access_Control_Type. + + +     + - - An access control mode for extended presence items like geolocation. - This type isn't actually used by the SimplePresence interface, but - it's included here so it can be referenced by rich presence interfaces - such as Location. + +

    An access control mode for extended presence items like geolocation. + This type isn't actually used by the SimplePresence interface, but + it's included here so it can be referenced by rich presence interfaces + such as Location.

    + +

    Location + uses this for historical reasons, new interfaces will use + Access_Control_Type.

     diff --git a/spec/Connection_Manager.xml b/spec/Connection_Manager.xml index 709a9b9..d75d866 100644 --- a/spec/Connection_Manager.xml +++ b/spec/Connection_Manager.xml @@ -147,13 +147,32 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. - This parameter is also a D-Bus property on the resulting Connection; a - parameter named com.example.Duck.Macaroni with this flag - corresponds to the Macaroni property on the - com.example.Duck interface. Its value can be queried - and possibly changed on an existing Connection using methods on the - org.freedesktop.DBus.Properties interface. +

    This parameter is also a D-Bus property on the resulting + Connection; a + parameter named com.example.Duck.Macaroni with this + flag corresponds to the Macaroni property on the + com.example.Duck interface. Its value can be queried + and possibly changed on an existing Connection using methods on the + org.freedesktop.DBus.Properties interface.

    + +

    When a parameter with this flag is changed with Account.UpdateParameters, the + account manager will attempt to update its value on any running + connections. Thus, clients generally do not need to directly access + or update the connection property; instead, they SHOULD manipulate + Account.Parameters.

    + + +

    This allows runtime-configurable options to be stored and + maintained by the AccountManager, without needing to + invent a separate account preference for “properties that should + be set on the connection as soon as it is created”. It was + originally invented to manage Cellular + preferences.

    +     @@ -273,7 +292,8 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. A dictionary mapping parameter names to values of the appropriate type, as indicated by GetParameters - and the above well-known list. + and the well-known list of names and value types documented on the + Connection_Parameter_Name type.     @@ -307,7 +327,55 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.To request values for these parameters from the user, a client must have prior knowledge of the meaning of the parameter names, so the - following well-known names and types should be used where appropriate:

    + well-known names and types defined by the + Connection_Parameter_Name type should be used where + appropriate.

    + +

    Connection manager authors SHOULD avoid introducing parameters + whose default values would not be serializable in a + .manager file.

    + + +

    The same serialization format is used in Mission Control + to store accounts.

    +     + +

    Every successful RequestConnection call will cause the emission of a + NewConnection signal for the same newly + created connection. The + requester can use the returned object path and service name + independently of the emission of that signal. In that case this signal + emission is most useful for, e.g. other processes that are monitoring + the creation of new connections.

    + + + + + + The requested protocol is not supported by this manager + + + + + The requested connection already appears to exist + + + + + Unrecognised connection parameters + + + + + + + + +

    Well-known connection parameter names, along with their expected + type. Where possible, connection managers should use names and types + from this list in the Parameters that may be passed + to RequestConnection.

    account (s)
    @@ -354,47 +422,29 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
    keepalive-interval (u)
    -
    The time in seconds between pings sent to the server to ensure - that the connection is still alive, or 0 to disable such - pings.
    +
    +

    The time in seconds between pings sent to the server to ensure + that the connection is still alive, or 0 to disable such + pings.

    + +

    This parameter is superseded by the KeepaliveInterval + property, which can be updated on an already-established + connection as well as being specified when requesting the + connection. Clients SHOULD provide that parameter instead, if + allowed; new connection managers SHOULD implement it in + preference to this one.

    +
    -

    Connection manager authors SHOULD avoid introducing parameters - whose default values would not be serializable in a - .manager file.

    - - -

    The same serialization format is used in Mission Control - to store accounts.

    -     +

    The following well-known parameter names correspond to D-Bus + properties, and thus their Conn_Mgr_Param_Flags + should include DBus_Property. See that flag for more details on this + kind of parameter.

    -

    Every successful RequestConnection call will cause the emission of a - NewConnection signal for the same newly - created connection. The - requester can use the returned object path and service name - independently of the emission of that signal. In that case this signal - emission is most useful for, e.g. other processes that are monitoring - the creation of new connections.

    +     - - - - - The requested protocol is not supported by this manager - - - - - The requested connection already appears to exist - - - - - Unrecognised connection parameters - - - - +     diff --git a/spec/Media_Stream_Handler.xml b/spec/Media_Stream_Handler.xml index c9ae78f..123ea8b 100644 --- a/spec/Media_Stream_Handler.xml +++ b/spec/Media_Stream_Handler.xml @@ -337,6 +337,53 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. + + + + + + +

    Informs the connection manager that a valid transport pair + has been discovered and streaming is in progress. Component + id MUST be the same for both transports and the pair is + only valid for that component.

    + + +

    The connection manager might need to send the details of + the active transport pair (e.g. c and o parameters of SDP + body need to contain address of selected native RTP transport + as stipulated by RFC 5245). However, the candidate ID might + not be enough to determine these info if the transport was + found after NativeCandidatesPrepared + has been called (e.g. peer reflexive ICE candidate).

    +     + +

    This method must be called before + NewActiveCandidatePair.

    + + +

    This way, connection managers supporting this method can + safely ignore subsequent + NewActiveCandidatePair call.

    +     + +

    Connection managers SHOULD NOT implement this method unless + they need to inform the peer about selected transports. As a + result, streaming implementations MUST NOT treat errors raised + by this method as fatal.

    + + +

    Usually, connection managers only need to do one answer/offer + round-trip. However, some protocols give the possibility to + to send an updated offer (e.g. ICE defines such mechanism to + avoid some race conditions and to properly set the state of + gateway devices).

    +     +     +     UDP (User Datagram Protocol) @@ -513,9 +560,9 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. - + - A telephony event code as defined by RFC 4733. + A telephony event code. @@ -523,6 +570,44 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. + + + + + A telephony event code as defined by RFC 4733. + + + + + The payload type to use when sending events. The value 0xFFFFFFFF + means to send with the already configured event type instead of using + the specified one. + + + + Request that a telephony event (as defined by RFC 4733) is transmitted + over this stream until StopTelephonyEvent is called. This differs from + StartTelephonyEvent in that you force the event to be transmitted + as a RFC 4733 named event, not as sound. You can also force a specific + Codec ID. + + + + + + + A telephony event code as defined by RFC 4733. + + + + Request that a telephony event (as defined by RFC 4733) is transmitted + over this stream until StopTelephonyEvent is called. This differs from + StartTelephonyEvent in that you force the event to be transmitted + as sound instead of as a named event. + + diff --git a/spec/Protocol.xml b/spec/Protocol.xml index 91c350f..e37fe22 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;
    @@ -178,6 +216,20 @@ allowed=org.freedesktop.Telepathy.Channel.TargetHandle;org.freedesktop.Telepathy Jabber/XMPP (including Google Talk), or tel for the PSTN.

    +

    A more exhaustive list of addressable vCard fields can be found in + the Protocol's Addressing interface's + AddressableVCardFields.

    + +

    It is not necessarily valid to interpret contacts' identifiers + as values of this vCard field. For instance, telepathy-sofiasip + supports contacts whose identifiers are of the form + sip:jenny@example.com or tel:8675309, which would not normally + both be represented by any single vCard field. Arbitrary + handles/identifiers as vCard fields are represented + through the Connection's + Addressing.DRAFT + contact attributes.

    +

    This is taken from Mission Control profiles as used on Maemo 5. One valid use of this field is to answer the question: given a @@ -187,15 +239,14 @@ allowed=org.freedesktop.Telepathy.Channel.TargetHandle;org.freedesktop.Telepathy protocols that handle x-jabber, then offer the user a list of accounts for those protocols and/or the option to create a new account for one of those protocols.

    - -

    It is not necessarily valid to interpret contacts' identifiers - as values of this vCard field. For instance, telepathy-sofiasip - supports contacts whose identifiers are of the form - sip:jenny@example.com or tel:8675309, which would not normally - both be represented by any single vCard field. Representing - 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 +274,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 +301,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.

    @@ -364,6 +429,6 @@ allowed=org.freedesktop.Telepathy.Channel.TargetHandle;org.freedesktop.Telepathy - + diff --git a/spec/Protocol_Interface_Addressing.xml b/spec/Protocol_Interface_Addressing.xml new file mode 100644 index 0000000..3722c3b --- /dev/null +++ b/spec/Protocol_Interface_Addressing.xml @@ -0,0 +1,300 @@ + + + + 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 draft) + +

    An interface for protocols that support multiple forms of + addressing contacts, for example through vCard addresses and URIs.

    + +

    If the ConnectionManager has a .manager file, and it + supports this interface, the interface's immutable properties + must be represented in the file; the representation is described as + part of the documentation for each property.

    + +

    For instance, a SIP connection manager might have the + following lines in the .manager file.

    + +
    +[Protocol sip]
+AddressableVCardFields=tel;x-sip;
+AddressableURISchemes=tel;sip;
+
    +     + + + +

    The vCard fields that can be used to request a contact with + normalized to lower case. If the URL vCard + field is addressable, a colon, followed by the supported URI + schemes will be concatenated.

    + +

    For example: ["tel", "x-sip"].

    + +

    The url vCard field MUST NOT appear here; see + AddressableURISchemes instead.

    + + +

    In practice, protocols have a limited set of URI + schemes that make sense to resolve as a contact.

    +     + +

    This property should only be used when the connection is + offline. When it is connected the addressable fields should be + retrieved from the + Requests.RequestableChannelClasses's + TargetVCardField fixed-property instead.

    + +

    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 + AddressableVCardFields. The corresponding value + is a list of strings, each followed with a semicolon and in the + syntax of the "localestring" type from the Desktop Entry + Specification.

    + +

    Well-known vCard fields:

    + +
    +
    tel
    +
    The TEL vCard field. Used for phone numbers.
    +
    x-sip
    +
    The X-SIP vCard field. Used for SIP addresses.
    +
    x-aim
    +
    The X-AIM vCard field. Used for AIM user IDs.
    +
    x-icq
    +
    The X-ICQ vCard field. Used for ICQ UINs.
    +
    x-skype
    +
    The X-SKYPE vCard field. Used for Skype user names or + telephone numbers. There is also a X-SKYPE-USERNAME field, + but for Telepathy purposes, x-skype is preferred
    +
    x-groupwise
    +
    The X-GROUPWISE vCard field. Used for Groupwise contacts.
    +
    x-gadugadu
    +
    The X-GADUGADU vCard field. Used for Gadu-Gadu contacts.
    +
    x-jabber
    +
    The X-JABBER vCard field. Used for XMPP JIDs.
    +
    x-msn
    +
    The X-MSN vCard field. Used for MSN contacts.
    +
    x-yahoo
    +
    The X-YAHOO vCard field. Used for Yahoo! IDs.
    +
    + +     +     + + + +

    The URI schemes that are supported by this protocol.

    + +

    For example: ["tel", "sip"].

    + +

    This property should only be used when the connection is + offline. When it is connected the addressable URI schemes should be + retrieved from the + Requests.RequestableChannelClasses's + TargetURIScheme fixed-property instead.

    + +

    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 + AddressableURISchemes. The corresponding value + is a list of strings, each followed with a semicolon and in the + syntax of the "localestring" type from the Desktop Entry + Specification.

    + +

    Well-known URI schemes:

    + +
    +
    sip
    +
    SIP protocol. + For example: sip:julien@example.com.
    +
    sips
    +
    Secure (encrypted) SIP protocol. + For example: sips:julien@example.com.
    +
    tel
    +
    Used for telephone numbers. + For example: tel:+12065551234.
    +
    xmpp
    +
    XMPP protocol. + For example: xmpp:julien@example.com.
    +
    msnim
    +
    For the purposes of + Protocol.Interface.Addressing.DRAFT, + Connection.Interface.Addressing.DRAFT, + and + Channel.Interface.Addressing.DRAFT, + the verb part is ignored, and SHOULD be add; the + contact field in the query string is used to + identify the contact. + For example: msnim:add?contact=julien.
    +
    aim
    +
    For the purposes of + Protocol.Interface.Addressing.DRAFT, + Connection.Interface.Addressing.DRAFT, + and + Channel.Interface.Addressing.DRAFT, + the verb part is ignored, and SHOULD be addbuddy; the + screenname field in the query string is used to + identify the contact. + For example: aim:addbuddy?screenname=julien.
    +
    skype
    +
    Skype protocol. + For example: skype:julien.
    +
    ymsgr
    +
    For the purposes of + Protocol.Interface.Addressing.DRAFT, + Connection.Interface.Addressing.DRAFT, + and + Channel.Interface.Addressing.DRAFT, + the verb part is ignored, and SHOULD be addfriend; the + query string is used to identify the contact. + For example: ymsgr:addfriend?julien.
    +
    gg
    +
    Gadu-Gadu protocol. + For example: gg:julien.
    +
    +     +     + + + +

    Attempt to normalize the given vCard address. Where possible, this + SHOULD return an address that would appear in the + org.freedesktop.Telepathy.Connection.Interface.Addressing.DRAFT/addresses + attribute for a contact on a connected + Connection. +

    + +

    If full normalization requires network activity or is otherwise + impossible to do without a Connection, + this method SHOULD perform a best-effort normalization.

    + +

    An example would be a vCard TEL field with a formatted + number in the form of +1 (206) 555 1234, this would be + normalized to +12065551234.

    + +

    This method MAY simply raise NotImplemented on some + protocols, if it has no use.

    +     + + + + The vCard field of the address we are normalizing. The + field name SHOULD be in lower case, and MUST appear in + AddressableVCardFields. + + + + + + The address to normalize. + + + + + + The vCard address, normalized as much as possible. + + + + + + + The vCard field is not supported (it is not in + AddressableVCardFields). + + + + + + The address is syntactically incorrect. + + + +     + + + +

    Attempt to normalize the given contact URI. Where possible, this + SHOULD return an address that would appear in the + org.freedesktop.Telepathy.Connection.Interface.Addressing.DRAFT/uris + attribute for a contact on a connected + Connection. +

    + +

    If full normalization requires network activity or is otherwise + impossible to do without a Connection, + this method SHOULD perform a best-effort normalization.

    + +

    Example: xmpp:eitan@EXAMPLE.COM would be normalized to + xmpp:eitan@example.com.

    + +

    This method MAY simply raise NotImplemented on some + protocols, if it has no use.

    +     + + + + The URI to normalize. The URI's scheme (i.e. the part before + the first colon) MUST appear in + AddressableURISchemes. + + + + + + A URI, normalized as much as possible. + + + + + + + The URI scheme is not supported (it is not in + AddressableURISchemes). + + + + + + The URI is syntactically incorrect. + + + +     + +     +     + diff --git a/spec/Protocol_Interface_Presence.xml b/spec/Protocol_Interface_Presence.xml index 47a37ea..ddff332 100644 --- a/spec/Protocol_Interface_Presence.xml +++ b/spec/Protocol_Interface_Presence.xml @@ -20,9 +20,8 @@ 02110-1301, USA.

    - - (draft 1) + + (as stable API) diff --git a/spec/all.xml b/spec/all.xml index 9140a1f..afb48df 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.21.4 Copyright © 2005-2010 Collabora Limited Copyright © 2005-2010 Nokia Corporation @@ -33,6 +33,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. + @@ -44,22 +45,28 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. + + + + + + @@ -95,6 +102,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. + @@ -108,6 +116,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. + @@ -121,12 +130,25 @@ 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. +

    +     + +     + @@ -160,6 +182,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. + @@ -171,9 +194,11 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. + + diff --git a/spec/errors.xml b/spec/errors.xml index 60a93c9..268087b 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 + server certificate chain exceeds 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. @@ -433,6 +483,31 @@ + + + + Raised when the requested functionality is not yet available, but is + likely to become available after some time has passed. + + + + + + + Raised when an incoming or outgoing Call.DRAFT is + rejected by the the receiver. + + + + + + + Raised when a call was terminated as a result of the local user + picking up the call on a different resource. + + + Copyright © 2005-2010 Collabora Limited Copyright © 2005-2009 Nokia Corporation diff --git a/spec/generic-types.xml b/spec/generic-types.xml index c017ba5..014f8ad 100644 --- a/spec/generic-types.xml +++ b/spec/generic-types.xml @@ -195,4 +195,21 @@ + + + A mapping from object path to the immutable properties of + the object. + + + The object path of an object + + + + + The immutable properties of the object + + + + diff --git a/spec/template.xml b/spec/template.xml index d752d72..7264720 100644 --- a/spec/template.xml +++ b/spec/template.xml @@ -22,7 +22,7 @@ - (draft 1) + (draft 1)

    Foo.

    -- cgit v1.2.3