diff options
Diffstat (limited to 'spec')
-rw-r--r-- | spec/Call_Content.xml | 127 | ||||
-rw-r--r-- | spec/Call_Content_Codec_Offer.xml | 33 | ||||
-rw-r--r-- | spec/Call_Content_Interface_Media.xml | 95 | ||||
-rw-r--r-- | spec/Call_Content_Interface_Mute.xml | 25 | ||||
-rw-r--r-- | spec/Call_Stream.xml | 124 | ||||
-rw-r--r-- | spec/Call_Stream_Endpoint.xml | 123 | ||||
-rw-r--r-- | spec/Call_Stream_Interface_Media.xml | 168 | ||||
-rw-r--r-- | spec/Channel_Interface_DTMF.xml | 93 | ||||
-rw-r--r-- | spec/Channel_Interface_Hold.xml | 5 | ||||
-rw-r--r-- | spec/Channel_Type_Call.xml | 19 | ||||
-rw-r--r-- | spec/Connection.xml | 119 | ||||
-rw-r--r-- | spec/Connection_Interface_Location.xml | 50 | ||||
-rw-r--r-- | spec/Connection_Interface_Mail_Notification.xml | 75 | ||||
-rw-r--r-- | spec/Protocol_Interface_Presence.xml | 5 | ||||
-rw-r--r-- | spec/all.xml | 2 | ||||
-rw-r--r-- | spec/errors.xml | 8 |
16 files changed, 724 insertions, 347 deletions
diff --git a/spec/Call_Content.xml b/spec/Call_Content.xml index 704769adf..82d40443e 100644 --- a/spec/Call_Content.xml +++ b/spec/Call_Content.xml @@ -25,19 +25,24 @@ <tp:added version="0.19.0">(draft 1)</tp:added> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - 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 <tp:dbus-ref namespace="ofdT.Call" - >Stream.DRAFT</tp:dbus-ref> objects which represent the actual - transport to one or more contacts. + This object represents one Content inside a <tp:dbus-ref + namespace="ofdT.Channel.Type">Call.DRAFT</tp:dbus-ref>. For + example, in an audio/video call there would be one audio content + and one video content. Each content has one or more <tp:dbus-ref + namespace="ofdT.Call">Stream.DRAFT</tp:dbus-ref> objects which + represent the actual transport to one or more remote contacts. </tp:docstring> <tp:enum name="Content_Removal_Reason" type="u"> <tp:added version="0.21.2"/> <tp:docstring> - A simple 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. + 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. </tp:docstring> <tp:enumvalue suffix="Unknown" value="0"> @@ -87,32 +92,32 @@ tp:type="DBus_Error_Name"> <tp:docstring> A more specific reason for the content removal, if one is - available, or an empty string otherwise. + available, or an empty string. </tp:docstring> </arg> <arg direction="in" name="Message" type="s"> <tp:docstring> A human-readable message for the reason of removing the - content, for example "Fatal streaming failure", "no codec - intersection", etc. This property can be left empty if no - reason is to be given. + content, such as "Fatal streaming failure" or "no codec + intersection". This property can be left empty if no reason + is to be given. </tp:docstring> </arg> <tp:possible-errors> - <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"> - </tp:error> + <tp:error name="org.freedesktop.Telepathy.Error.NetworkError" /> <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented"> <tp:docstring> - 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). </tp:docstring> </tp:error> </tp:possible-errors> </method> <property name="Interfaces" tp:name-for-bindings="Interfaces" - type="as" tp:type="DBus_Interface[]" access="read"> + type="as" tp:type="DBus_Interface[]" access="read" tp:immutable="yes"> <tp:added version="0.19.11"/> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>Extra interfaces provided by this content, such as <tp:dbus-ref @@ -123,37 +128,35 @@ </tp:docstring> </property> - <property name="Name" tp:name-for-bindings="Name" type="s" access="read"> + <property name="Name" tp:name-for-bindings="Name" type="s" access="read" + tp:immutable="yes"> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>The name of the content.</p> <tp: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 + 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. </tp:rationale> </tp:docstring> </property> <property name="Type" tp:name-for-bindings="Type" - type="u" tp:type="Media_Stream_Type" access="read"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>The media type of this content</p> - </tp:docstring> - </property> - - <property name="Creator" tp:name-for-bindings="Creator" - type="u" tp:type="Contact_Handle" access="read"> + type="u" tp:type="Media_Stream_Type" access="read" tp:immutable="yes"> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>The creator of this content</p> + <p>The media type of this content.</p> </tp:docstring> </property> <tp:enum name="Call_Content_Disposition" type="u"> <tp:docstring> - [FIXME] + The disposition of this content, which defines whether to + automatically start sending data on the streams when + <tp:dbus-ref + namespace="ofdT.Channel.Type">Call.DRAFT</tp:dbus-ref> is + called on the channel. </tp:docstring> <tp:enumvalue suffix="None" value="0"> @@ -162,31 +165,28 @@ </tp:docstring> </tp:enumvalue> - <tp:enumvalue suffix="Early_Media" value="1"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - [FIXME: what does this mean?] - </tp:docstring> - </tp:enumvalue> - - <tp:enumvalue suffix="Initial" value="2"> + <tp:enumvalue suffix="Initial" value="1"> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>The content was initially part of the call. When <tp:dbus-ref - namespace="ofdT.Channel.Type.Call.DRAFT">Accept</tp:dbus-ref> - is called on the channel, all streams of this content where - the self-handle's sending state in <tp:dbus-ref - namespace="ofdT.Call.Stream.DRAFT">Members</tp:dbus-ref> - is Sending_State_Pending_Send will be moved to - Sending_State_Sending as if <tp:dbus-ref - namespace="ofdT.Call.Stream.DRAFT">SetSending</tp:dbus-ref> - (TRUE) had been called.</p> + <p>The content was initially part of the call. When + <tp:dbus-ref + namespace="ofdT.Channel.Type.Call.DRAFT">Accept</tp:dbus-ref> + is called on the channel, all streams of this content with + <tp:dbus-ref + namespace="ofdT.Call.Stream.DRAFT">LocalSendingState</tp:dbus-ref> + set to <tp:type>Sending_State</tp:type>_Pending_Send will be + moved to <tp:type>Sending_State</tp:type>_Sending as if + <tp:dbus-ref + namespace="ofdT.Call.Stream.DRAFT">SetSending</tp:dbus-ref> + (True) had been called.</p> </tp:docstring> </tp:enumvalue> </tp:enum> <property name="Disposition" tp:name-for-bindings="Disposition" - type="u" tp:type="Call_Content_Disposition" access="read"> + type="u" tp:type="Call_Content_Disposition" access="read" + tp:immutable="yes"> <tp:docstring> - The disposition of this content. This property cannot change. + The disposition of this content. </tp:docstring> </property> @@ -198,7 +198,9 @@ </tp:docstring> <arg name="Streams" type="ao"> <tp:docstring> - The streams which were added. + The <tp:dbus-ref + namespace="ofdT.Call">Stream.DRAFT</tp:dbus-ref>s which were + added. </tp:docstring> </arg> </signal> @@ -211,7 +213,9 @@ </tp:docstring> <arg name="Streams" type="ao"> <tp:docstring> - The streams which were removed. + The <tp:dbus-ref + namespace="ofdT.Call">Stream.DRAFT</tp:dbus-ref>s which were + removed. </tp:docstring> </arg> </signal> @@ -224,16 +228,17 @@ content.</p> <tp:rationale> - <p>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.</p> + 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. </tp:rationale> - <p>Change notification is via + <p>Change notification is through the <tp:member-ref>StreamsAdded</tp:member-ref> and - <tp:member-ref>StreamsRemoved</tp:member-ref>.</p> + <tp:member-ref>StreamsRemoved</tp:member-ref> signals.</p> </tp:docstring> </property> @@ -265,11 +270,11 @@ </tp:enum> <property name="Packetization" tp:name-for-bindings="Packetization" - type="u" tp:type="Call_Content_Packetization_Type" access="read"> + type="u" tp:type="Call_Content_Packetization_Type" access="read" + tp:immutable="yes"> <tp:added version="0.21.2"/> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>The packetization method in use for this content. This - property is immutable.</p> + <p>The packetization method in use for this content.</p> </tp:docstring> </property> </interface> diff --git a/spec/Call_Content_Codec_Offer.xml b/spec/Call_Content_Codec_Offer.xml index 5fc45258a..e0a791f36 100644 --- a/spec/Call_Content_Codec_Offer.xml +++ b/spec/Call_Content_Codec_Offer.xml @@ -26,15 +26,27 @@ <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> This object represents an offer of a Codec payload mapping. - FIXME add Accept and Reject signals ? </tp:docstring> <method name="Accept" tp:name-for-bindings="Accept"> <arg name="Codecs" direction="in" - type="a(usuua{ss})" tp:type="Codec[]" /> + type="a(usuua{ss})" tp:type="Codec[]"> + <tp:docstring> + The local codec mapping to send to the remote contacts and + to use in the <tp:dbus-ref + namespace="ofdT.Call">Content.DRAFT</tp:dbus-ref>. + </tp:docstring> + </arg> <tp:docstring> - Accept the updated Codec mapping and update the local mapping + Accept the updated Codec mapping and update the local mapping. </tp:docstring> + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"> + <tp:docstring> + The codecs given as the argument are invalid in some way. + </tp:docstring> + </tp:error> + </tp:possible-errors> </method> <method name="Reject" tp:name-for-bindings="Reject"> @@ -44,11 +56,22 @@ </tp:docstring> </method> + <property name="Interfaces" tp:name-for-bindings="Interfaces" + type="as" tp:type="DBus_Interface[]" access="read" tp:immutable="yes"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Extra interfaces provided by this codec offer. This SHOULD + NOT include the CodecOffer interface itself, and cannot change + once the content has been created.</p> + </tp:docstring> + </property> + <property name="RemoteContactCodecMap" tp:name-for-bindings="Remote_Contact_Codec_Map" - type="a{ua(usuua{ss})}" tp:type="Contact_Codec_Map" access="read"> + type="a{ua(usuua{ss})}" tp:type="Contact_Codec_Map" access="read" + tp:immutable="yes"> <tp:docstring> - 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. </tp:docstring> </property> diff --git a/spec/Call_Content_Interface_Media.xml b/spec/Call_Content_Interface_Media.xml index 2b7a5ca88..0552111a6 100644 --- a/spec/Call_Content_Interface_Media.xml +++ b/spec/Call_Content_Interface_Media.xml @@ -26,62 +26,75 @@ <tp:requires interface="org.freedesktop.Telepathy.Call.Content.DRAFT"/> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - Interface to use by a software implementation of media streaming. + <p>Interface to use by a software implementation of media + streaming.</p> + + <p>On new <tp:dbus-ref + namespace="ofdT.Channel.Type">Call.DRAFT</tp:dbus-ref> channels, + handlers should wait for <tp:dbus-ref + namespace="ofdT.Call.Content">CodecOffer.DRAFT</tp:dbus-ref> + objects to appear (one will either already be present, or will + appear at some point in the channel's lifetime).</p> + + <p>If the Call is incoming, then the codec offer's <tp:dbus-ref + namespace="ofdT.Call.Content.CodecOffer.DRAFT">RemoteContactCodecMap</tp:dbus-ref> + will already be filled with the codec information of the + remote contacts. Depending on the protocol, an outgoing call's + <tp:dbus-ref + namespace="ofdT.Call.Content.CodecOffer.DRAFT">RemoteContactCodecMap</tp:dbus-ref> + 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, <tp:dbus-ref + namespace="ofdT.Call.Content">CodecOffer.DRAFT.Accept</tp:dbus-ref> + should be called with the details of these codecs.</p> - FIXME: How should the streaming implementation know when it is its turn - to set the codecs. </tp:docstring> <tp:struct name="Codec" array-name="Codec_List"> <tp:docstring> A description of a codec. </tp:docstring> - <tp:member name="Identifier" type="u"> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> Numeric identifier for the codec. This will be used as the PT in the SDP or content description. </tp:docstring> </tp:member> - <tp:member name="Name" type="s"> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> The name of the codec. </tp:docstring> </tp:member> - <tp:member name="Clockrate" type="u"> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - The clockrate of the codec + The clockrate of the codec. </tp:docstring> </tp:member> <tp:member name="Channels" type="u"> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - Number of channels of the codec if applicable, otherwise 0 + Number of channels of the codec if applicable, otherwise 0. </tp:docstring> </tp:member> - <tp:member name="Parameters" type="a{ss}" tp:type="String_String_Map"> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - Extra parameters for this codec + Extra parameters for this codec. </tp:docstring> </tp:member> </tp:struct> <tp:mapping name="Contact_Codec_Map"> <tp:docstring> - A map from contacts to the lists of codecs they support. + A map from contact to the list of codecs he or she supports. </tp:docstring> - <tp:member name="Handle" type="u" tp:type="Contact_Handle"> <tp:docstring> - A contact + A contact handle. </tp:docstring> </tp:member> - <tp:member name="Codecs" type="a(usuua{ss})" tp:type="Codec[]"> <tp:docstring> - The codecs that the contact supports + The codecs that the contact supports. </tp:docstring> </tp:member> </tp:mapping> @@ -90,14 +103,12 @@ <tp:docstring> A codec offer and its corresponding remote contact codec map. </tp:docstring> - <tp:member name="Codec_Offer" type="o"> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> The object path to the <tp:dbus-ref namespace="ofdT.Call.Content" >CodecOffer.DRAFT</tp:dbus-ref> </tp:docstring> </tp:member> - <tp:member name="Remote_Contact_Codec_Map" type="a{ua(usuua{ss})}" tp:type="Contact_Codec_Map"> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> @@ -117,16 +128,15 @@ signal implies that the <tp:member-ref>CodecOffer</tp:member-ref> property has changed to <code>('/', {})</code>.</p> </tp:docstring> - <arg name="Updated_Codecs" type="a{ua(usuua{ss})}" tp:type="Contact_Codec_Map"> <tp:docstring> - A map from contacts to their codecs. Each pair in this map is added - to the <tp:member-ref>ContactCodecMap</tp:member-ref> property, + A map from contact to his or her codecs. Each pair in this + map is added to the + <tp:member-ref>ContactCodecMap</tp:member-ref> property, replacing any previous pair with that key. </tp:docstring> </arg> - <arg name="Removed_Contacts" type="au" tp:type="Contact_Handle[]"> <tp:docstring> A list of keys which were removed from the @@ -136,17 +146,24 @@ </arg> </signal> - <method name="SetCodecs" tp:name-for-bindings="Set_Codecs"> + <method name="UpdateCodecs" tp:name-for-bindings="Update_Codecs"> <tp:docstring> - 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. </tp:docstring> - <arg name="Codecs" direction="in" type="a(usuua{ss})" tp:type="Codec[]"> <tp:docstring> The codecs now supported by the local user. </tp:docstring> </arg> + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"> + <tp:docstring> + Raised when not used during an existing call to update the codec mapping. + </tp:docstring> + </tp:error> + </tp:possible-errors> </method> <property name="ContactCodecMap" tp:name-for-bindings="Contact_Codec_Map" @@ -155,8 +172,8 @@ <p>A map from contact handles (including the local user's own handle) to the codecs supported by that contact.</p> - <p>Change notification is via - <tp:member-ref>CodecsChanged</tp:member-ref>.</p> + <p>Change notification is via the + <tp:member-ref>CodecsChanged</tp:member-ref> signal.</p> </tp:docstring> </property> @@ -174,25 +191,25 @@ <tp:member-ref>CodecOffer</tp:member-ref> property has changed to <code>(Offer, Codecs)</code>.</p> </tp:docstring> - <arg name="Offer" type="o"> <tp:docstring> The object path of the new codec offer. This replaces any previous codec offer. </tp:docstring> </arg> - <arg name="Codecs" type="a{ua(usuua{ss})}" tp:type="Contact_Codec_Map"> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>The <tp:dbus-ref namespace="ofdT.Call.Content" >CodecOffer.DRAFT.RemoteContactCodecMap</tp:dbus-ref> property of the codec offer.</p> - <tp:rationale> - <p>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.</p> - </tp:rationale> + <tp:rationale> + Having the <tp:dbus-ref + namespace="ofdT.Call.Content.CodecOffer.DRAFT">RemoteContactCodecMap</tp:dbus-ref> + property here saves a D-Bus round-trip - it shouldn't be + necessary to get the property from the CodecOffer object, in + practice. + </tp:rationale> </tp:docstring> </arg> </signal> @@ -209,16 +226,18 @@ codec offer, and the mapping MUST be empty.</p> <tp:rationale> - <p>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.</p> + Having the <tp:dbus-ref + namespace="ofdT.Call.Content.CodecOffer.DRAFT">RemoteContactCodecMap</tp:dbus-ref> + property here saves a D-Bus round-trip - it shouldn't be + necessary to get the property from the CodecOffer object, in + practice. </tp:rationale> - <p>Change notification is via + <p>Change notification is via the <tp:member-ref>NewCodecOffer</tp:member-ref> (which replaces the value of this property with a new codec offer), and <tp:member-ref>CodecsChanged</tp:member-ref> (which implies that - there is no longer any active codec offer).</p> + there is no longer any active codec offer) signals.</p> </tp:docstring> </property> </interface> diff --git a/spec/Call_Content_Interface_Mute.xml b/spec/Call_Content_Interface_Mute.xml index b727231e9..566d1b162 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. <interface name="org.freedesktop.Telepathy.Call.Content.Interface.Mute.DRAFT" tp:causes-havoc="experimental"> <tp:added version="0.19.6">(draft version, not API-stable)</tp:added> + <tp:requires interface="org.freedesktop.Telepathy.Call.Content.DRAFT"/> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>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. <p>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.</p> - <tp:rationale> - <p>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.</p> - </tp:rationale> + + <tp:rationale> + 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. + </tp:rationale> </tp:docstring> - <signal name="MuteStateChanged" tp:name-for-bindings="Mute_State_Changed"> + <signal name="MuteStateChanged" tp:name-for-bindings="Mute_State_Changed"> <tp:docstring> Emitted to indicate that the mute state has changed for this call content. This may occur as a consequence of the client calling - <tp:member-ref>Mute</tp:member-ref>, or as an indication that another + <tp:member-ref>SetMuted</tp:member-ref>, or as an indication that another client has (un)muted the content. </tp:docstring> - <arg name="MuteState" type="b"> <tp:docstring> True if the content is now muted. @@ -61,14 +62,14 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. </tp:docstring> </property> - <method name="Mute" tp:name-for-bindings="Mute"> - <tp:changed version="0.21.2">renamed from Muted</tp:changed> + <method name="SetMuted" tp:name-for-bindings="Set_Muted"> + <tp:changed version="0.21.2">renamed from SetMuted to Mute</tp:changed> + <tp:changed version="0.21.UNRELEASED">renamed back from Mute to SetMuted</tp:changed> <arg direction="in" name="Muted" type="b"> <tp:docstring> True if the client has muted the content. </tp:docstring> </arg> - <tp:docstring> <p>Inform the CM that the call content has been muted or unmuted by the client.</p> diff --git a/spec/Call_Stream.xml b/spec/Call_Stream.xml index 738564d23..b69398901 100644 --- a/spec/Call_Stream.xml +++ b/spec/Call_Stream.xml @@ -25,32 +25,32 @@ <tp:added version="0.19.0">(draft 1)</tp:added> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - One stream inside a content - FIXME, direction should be a mapping of contact -> (bool)sending ? + One stream inside a <tp:dbus-ref + namespace="ofdT.Call">Content.DRAFT</tp:dbus-ref>. </tp:docstring> <method name="SetSending" tp:name-for-bindings="Set_Sending"> <tp:docstring> Set the stream to start or stop sending media from the local - user to other contacts. + user to other contacts. </tp:docstring> <arg name="Send" type="b" direction="in"> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>If true, the local user's sending state should change - to Sending, if it isn't already.</p> + <p>If True, the + <tp:member-ref>LocalSendingState</tp:member-ref> should + change to <tp:type>Sending_State</tp:type>_Sending, if it isn't + already.</p> - <p>If false, the local user's sending state should change to None, - if it isn't already.</p> + <p>If False, the + <tp:member-ref>LocalSendingState</tp:member-ref> should + change to <tp:type>Sending_State</tp:type>_None, if it isn't + already.</p> </tp:docstring> </arg> <tp:possible-errors> - <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented"> - <tp:docstring> - [FIXME: when?] - </tp:docstring> - </tp:error> + <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented" /> </tp:possible-errors> </method> @@ -94,11 +94,12 @@ </tp:possible-errors> </method> - <signal name="MembersChanged" - tp:name-for-bindings="Members_Changed"> - <tp:changed version="0.21.2">renamed from SendersChanged</tp:changed> + <signal name="RemoteMembersChanged" + tp:name-for-bindings="Remote_Members_Changed"> + <tp:changed version="0.21.2">renamed from SendersChanged to MembersChanged</tp:changed> + <tp:changed version="0.21.UNRELEASED">renamed from MembersChanged to RemoteMembersChanged</tp:changed> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - Emitted when <tp:member-ref>Members</tp:member-ref> changes. + Emitted when <tp:member-ref>RemoteMembers</tp:member-ref> changes. </tp:docstring> <arg name="Updates" type="a{uu}" tp:type="Contact_Sending_State_Map"> @@ -110,21 +111,36 @@ </arg> <arg name="Removed" type="au" tp:type="Contact_Handle[]"> <tp:docstring> - The channel-specific handles that were removed from - the keys of the Members property, as a result of the - contact leaving this stream + The channel-specific handles that were removed from the keys + of the <tp:member-ref>RemoteMembers</tp:member-ref> + property, as a result of the contact leaving this stream + </tp:docstring> + </arg> + </signal> + + <signal name="LocalSendingStateChanged" + tp:name-for-bindings="Local_Sending_State_Changed"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + Emitted when <tp:member-ref>LocalSendingState</tp:member-ref> changes. + </tp:docstring> + + <arg name="State" type="u" tp:type="Sending_State"> + <tp:docstring> + The new value of + <tp:member-ref>LocalSendingState</tp:member-ref>. </tp:docstring> </arg> </signal> <tp:enum name="Sending_State" type="u"> <tp:docstring> - Tristate indicating whether a contact is sending media. + Enum indicating whether a contact is sending media. </tp:docstring> <tp:enumvalue suffix="None" value="0"> <tp:docstring> - 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. </tp:docstring> </tp:enumvalue> @@ -149,18 +165,22 @@ <tp:mapping name="Contact_Sending_State_Map"> <tp:docstring> - A map from contacts to their sending state. + A map from a contact to his or her sending state. </tp:docstring> <tp:member name="Contact" type="u" tp:type="Contact_Handle"> + <tp:docstring> + The contact handle. + </tp:docstring> </tp:member> <tp:member name="Sending" type="u" tp:type="Sending_State"> <tp:docstring> + The sending state of the contact. </tp:docstring> </tp:member> </tp:mapping> <property name="Interfaces" tp:name-for-bindings="Interfaces" - type="as" tp:type="DBus_Interface[]" access="read"> + type="as" tp:type="DBus_Interface[]" access="read" tp:immutable="yes"> <tp:added version="0.19.11"/> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>Extra interfaces provided by this stream, such as <tp:dbus-ref @@ -170,22 +190,16 @@ </tp:docstring> </property> - <property name="Members" tp:name-for-bindings="Members" + <property name="RemoteMembers" tp:name-for-bindings="Remote_Members" type="a{uu}" access="read" tp:type="Contact_Sending_State_Map"> <tp:changed version="0.21.2">renamed from Senders</tp:changed> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>A map from contacts to their sending state.</p> - - <p>The local user's handle in this map (the <tp:dbus-ref - namespace="ofdT.Channel.Interface" - >Group.SelfHandle</tp:dbus-ref> if the channel implements - Group, or the <tp:dbus-ref - namespace="org.freedesktop.Telepathy" - >Connection.SelfHandle</tp:dbus-ref> 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 Members mapping. Sending_State_Pending_Send - indicates that another contact has asked the local user to send + <p>A map from remote contacts to their sending state. The + local user's sending state is shown in + <tp:member-ref>LocalSendingState</tp:member-ref>.</p> + + <p><tp:type>Sending_State</tp:type>_Pending_Send indicates + that another contact has asked the local user to send media.</p> <p>Other contacts' handles in this map indicate whether they are @@ -195,8 +209,44 @@ </tp:docstring> </property> + <property name="LocalSendingState" tp:name-for-bindings="Local_Sending_State" + type="u" access="read" tp:type="Sending_State"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>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 + <tp:member-ref>RemoteMembers</tp:member-ref> mapping. Change + notification is given via the + <tp:member-ref>LocalSendingStateChanged</tp:member-ref> + signal.</p> + + <tp:rationale> + Implementations of the first Call draft had the self handle + in the <tp:member-ref>RemoteMembers</tp:member-ref> (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. + </tp:rationale> + + <p>A value of <tp:type>Sending_State</tp:type>_Pending_Send for + this property indicates that the other side requested the + local user start sending media, which can be done by calling + <tp:member-ref>SetSending</tp:member-ref>. When a call is + accepted, all initial contents with streams that have a + local sending state of + <tp:type>Sending_State</tp:type>_Pending_Send are + automatically set to sending. For example, on an incoming + call it means you need to <tp:dbus-ref + namespace="ofdT.Channel.Type.Call.DRAFT">Accept</tp:dbus-ref> + to start the actual call, on an outgoing call it might mean + you need to call <tp:dbus-ref + namespace="ofdT.Channel.Type.Call.DRAFT">Accept</tp:dbus-ref> + before actually starting the call.</p> + </tp:docstring> + </property> + <property name="CanRequestReceiving" tp:name-for-bindings="Can_Request_Receiving" - type="b" access="read"> + type="b" access="read" tp:immutable="yes"> <tp:added version="0.21.2"/> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>If true, the user can request that a remote contact starts diff --git a/spec/Call_Stream_Endpoint.xml b/spec/Call_Stream_Endpoint.xml index 34925eefe..4818168dc 100644 --- a/spec/Call_Stream_Endpoint.xml +++ b/spec/Call_Stream_Endpoint.xml @@ -21,73 +21,160 @@ </tp:license> <interface name="org.freedesktop.Telepathy.Call.Stream.Endpoint.DRAFT" - tp:causes-havoc="experimental"> + tp:causes-havoc="experimental"> <tp:added version="0.19.0">(draft 1)</tp:added> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - This object represents a set of candidates of one end-point. + <p>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.</p> + + <p>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.</p> </tp:docstring> <property name="RemoteCredentials" tp:name-for-bindings="Remote_Credentials" type="(ss)" tp:type="Stream_Credentials" access="read"> + <tp:docstring> + 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 + <tp:type>Candidate</tp:type>'s + <tp:type>Candidate_Info</tp:type> a{sv}. + </tp:docstring> </property> <signal name="RemoteCredentialsSet" - tp:name-for-bindings="Remote_Credentials_Set"> - <arg name="Username" type="s" /> - <arg name="Password" type="s" /> + tp:name-for-bindings="Remote_Credentials_Set"> + <arg name="Username" type="s"> + <tp:docstring> + The username set. + </tp:docstring> + </arg> + <arg name="Password" type="s"> + <tp:docstring> + The password set. + </tp:docstring> + </arg> + <tp:docstring> + Emitted when the remote ICE credentials for the endpoint are + set. If each candidate has different credentials, then this + signal will never be fired. + </tp:docstring> </signal> <property name="RemoteCandidates" tp:name-for-bindings="Remote_Candidates" type="a(usqa{sv})" tp:type="Candidate[]" access="read"> + <tp:docstring> + A list of candidates for this endpoint. + </tp:docstring> </property> <signal name="RemoteCandidatesAdded" - tp:name-for-bindings="Remote_Candidates_Added"> + tp:name-for-bindings="Remote_Candidates_Added"> + <tp:docstring> + Emitted when remote candidates are added to the + <tp:member-ref>RemoteCandidates</tp:member-ref> property. + </tp:docstring> <arg name="Candidates" - type="a(usqa{sv})" tp:type="Candidate[]"/> + type="a(usqa{sv})" tp:type="Candidate[]"> + <tp:docstring> + The candidates that were added. + </tp:docstring> + </arg> </signal> <signal name="CandidateSelected" - tp:name-for-bindings="Candidate_Selected"> + tp:name-for-bindings="Candidate_Selected"> + <tp:docstring> + Emitted when a candidate is selected for use in the stream. + </tp:docstring> <arg name="Candidate" - type="(usqa{sv})" tp:type="Candidate"/> + type="(usqa{sv})" tp:type="Candidate"> + <tp:docstring> + The candidate that has been selected. + </tp:docstring> + </arg> </signal> <property name="SelectedCandidate" - tp:name-for-bindings="Selected_Candidate" + tp:name-for-bindings="Selected_Candidate" type="(usqa{sv})" tp:type="Candidate" access="read"> + <tp:docstring> + The candidate that has been selected for use to stream packets + to the remote contact. Change notification is given via the + the <tp:member-ref>CandidateSelected</tp:member-ref> signal. + </tp:docstring> </property> <method name="SetSelectedCandidate" - tp:name-for-bindings="Set_Selected_Candidate"> + tp:name-for-bindings="Set_Selected_Candidate"> + <tp:docstring> + Set the value of + <tp:member-ref>CandidateSelected</tp:member-ref>. + </tp:docstring> <arg name="Candidate" type="(usqa{sv})" tp:type="Candidate" direction="in"> <tp:docstring> + The candidate that has been selected. </tp:docstring> </arg> + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"/> + </tp:possible-errors> </method> <property name="StreamState" tp:name-for-bindings="Stream_State" type="u" tp:type="Media_Stream_State" access="read"> + <tp:docstring> + The stream state of the endpoint. + </tp:docstring> </property> <signal name="StreamStateChanged" - tp:name-for-bindings="Stream_State_Changed"> - <arg name="state" - type="u" tp:type="Media_Stream_State"/> + tp:name-for-bindings="Stream_State_Changed"> + <tp:docstring> + Emitted when the <tp:member-ref>StreamState</tp:member-ref> + property changes. + </tp:docstring> + <arg name="state" type="u" tp:type="Media_Stream_State"> + <tp:docstring> + The new <tp:member-ref>StreamState</tp:member-ref> value. + </tp:docstring> + </arg> </signal> <method name="SetStreamState" - tp:name-for-bindings="Set_Stream_State"> - <arg name="State" type="u" tp:type="Media_Stream_State" - direction="in" /> + tp:name-for-bindings="Set_Stream_State"> + <tp:docstring> + Change the <tp:member-ref>StreamState</tp:member-ref> of the + endpoint. + </tp:docstring> + <arg direction="in" name="State" type="u" tp:type="Media_Stream_State"> + <tp:docstring> + The requested stream state. + </tp:docstring> + </arg> + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"/> + <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"/> + </tp:possible-errors> </method> <property name="Transport" tp:name-for-bindings="Transport" - type="u" tp:type="Stream_Transport_Type" access="read"> + type="u" tp:type="Stream_Transport_Type" access="read"> + <tp:docstring> + The transport type for the stream endpoint. + </tp:docstring> </property> </interface> diff --git a/spec/Call_Stream_Interface_Media.xml b/spec/Call_Stream_Interface_Media.xml index b009c4464..3d4fb1337 100644 --- a/spec/Call_Stream_Interface_Media.xml +++ b/spec/Call_Stream_Interface_Media.xml @@ -30,23 +30,28 @@ </tp:docstring> <method name="SetCredentials" tp:name-for-bindings="Set_Credentials"> - <tp:docstring> - Used to set the username fragment and password for streams that have - global credentials. - - <tp:rationale> - [FIXME: rationale?] - </tp:rationale> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Used to set the username fragment and password for streams that have + global credentials.</p> </tp:docstring> - <arg name="Username" type="s" direction="in"/> - <arg name="Password" type="s" direction="in" /> + <arg name="Username" type="s" direction="in"> + <tp:docstring> + The username to use when authenticating on the stream. + </tp:docstring> + </arg> + <arg name="Password" type="s" direction="in"> + <tp:docstring> + The password to use when authenticating on the stream. + </tp:docstring> + </arg> </method> <tp:mapping name="Candidate_Info"> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - Extra information about the candidate. Allowed and mandatory keys - depend on the transport protocol used. The following keys are commenly - used: + <p>Extra information about the candidate. Allowed and mandatory keys + depend on the transport protocol used. The following keys are commenly + used:</p> + <dl> <dt>Type (u)</dt> <dd>type of candidate (host, srflx, prflx, relay)</dd> @@ -78,41 +83,39 @@ </tp:docstring> <tp:member name="Key" type="s"> <tp:docstring>One of the well-known keys documented here, or an - implementation-specific key</tp:docstring> + implementation-specific key.</tp:docstring> </tp:member> <tp:member name="Value" type="v"> - <tp:docstring>The value corresponding to that key</tp:docstring> + <tp:docstring>The value corresponding to that key.</tp:docstring> </tp:member> </tp:mapping> <tp:struct name="Candidate" array-name="Candidate_List"> - <tp:docstring>A Stream Candidate</tp:docstring> - + <tp:docstring>A Stream Candidate.</tp:docstring> <tp:member name="Component" type="u"> - <tp:docstring>The component number</tp:docstring> + <tp:docstring>The component number.</tp:docstring> </tp:member> <tp:member name="IP" type="s"> - <tp:docstring>The IP address to use</tp:docstring> + <tp:docstring>The IP address to use.</tp:docstring> </tp:member> <tp:member name="Port" type="q"> - <tp:docstring>The port number to use</tp:docstring> + <tp:docstring>The port number to use.</tp:docstring> </tp:member> <tp:member name="Info" type="a{sv}" tp:type="Candidate_Info"> - <tp:docstring>Additional information about the candidate</tp:docstring> + <tp:docstring>Additional information about the candidate.</tp:docstring> </tp:member> </tp:struct> <method name="AddCandidates" tp:name-for-bindings="Add_Candidates"> <tp:docstring> - Add candidates to <tp:member-ref>LocalCandidates</tp:member-ref> - and signal them to the remote contact(s). + Add candidates to the + <tp:member-ref>LocalCandidates</tp:member-ref> property and + signal them to the remote contact(s). </tp:docstring> - - <arg name="candidates" direction="in" + <arg name="Candidates" direction="in" type="a(usqa{sv})" tp:type="Candidate[]"> <tp:docstring> - Candidates to be appended to - <tp:member-ref>LocalCandidates</tp:member-ref> + The candidates to be added. </tp:docstring> </arg> </method> @@ -120,12 +123,8 @@ <method name="CandidatesPrepared" tp:name-for-bindings="Candidates_Prepared"> <tp:docstring> - This indicates to the CM that the initial batch of candidates has been - added. - - <tp:rationale> - [FIXME: rationale] - </tp:rationale> + This indicates to the CM that the initial batch of candidates + has been added. </tp:docstring> </method> @@ -134,7 +133,6 @@ <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> A transport that can be used for streaming. </tp:docstring> - <tp:enumvalue suffix="Raw_UDP" value="0"> <tp:docstring> Raw UDP, with or without STUN. All streaming clients are assumed to @@ -145,7 +143,6 @@ interface.] </tp:docstring> </tp:enumvalue> - <tp:enumvalue suffix="ICE" value="1"> <tp:docstring> Interactive Connectivity Establishment, as defined by RFC @@ -154,7 +151,6 @@ Media.StreamHandler interface.] </tp:docstring> </tp:enumvalue> - <tp:enumvalue suffix="GTalk_P2P" value="2"> <tp:docstring> Google Talk peer-to-peer connectivity establishment, as implemented @@ -163,7 +159,6 @@ interface.] </tp:docstring> </tp:enumvalue> - <tp:enumvalue suffix="WLM_2009" value="3"> <tp:docstring> The transport used by Windows Live Messenger 2009 or later, which @@ -172,66 +167,61 @@ interface.] </tp:docstring> </tp:enumvalue> - <tp:enumvalue suffix="SHM" value="4"> <tp:added version="0.21.2"/> <tp:docstring> Shared memory transport, as implemented by the GStreamer - shmmsrc and shmsink plugins. + shmsrc and shmsink plugins. </tp:docstring> </tp:enumvalue> </tp:enum> <property name="Transport" tp:name-for-bindings="Transport" - type="u" tp:type="Stream_Transport_Type" access="read"> + type="u" tp:type="Stream_Transport_Type" access="read" tp:immutable="yes"> <tp:docstring> - The transport for this stream. This property is immutable. + The transport for this stream. </tp:docstring> </property> <property name="LocalCandidates" tp:name-for-bindings="Local_Candidates" type="a(usqa{sv})" tp:type="Candidate[]" access="read"> <tp:docstring> - [FIXME]. Change notification is via - <tp:member-ref>LocalCandidatesAdded</tp:member-ref>. + [FIXME]. Change notification is via the + <tp:member-ref>LocalCandidatesAdded</tp:member-ref> signal. </tp:docstring> </property> <signal name="LocalCandidatesAdded" tp:name-for-bindings="Local_Candidates_Added"> <tp:docstring> - Emitted when local candidates are added to - <tp:member-ref>LocalCandidates</tp:member-ref>. + Emitted when local candidates are added to the + <tp:member-ref>LocalCandidates</tp:member-ref> property. </tp:docstring> - - <arg name="Candidates" - type="a(usqa{sv})" tp:type="Candidate[]"> + <arg name="Candidates" type="a(usqa{sv})" tp:type="Candidate[]"> <tp:docstring> - Candidates that have been appended to - <tp:member-ref>LocalCandidates</tp:member-ref> + Candidates that have been added. </tp:docstring> </arg> </signal> <tp:struct name="Stream_Credentials"> - <tp:docstring>A username/password pair.</tp:docstring> + <tp:docstring>A username and password pair.</tp:docstring> <tp:member name="Username" type="s"> - <tp:docstring>The username</tp:docstring> + <tp:docstring>The username.</tp:docstring> </tp:member> <tp:member name="Password" type="s"> - <tp:docstring>The password</tp:docstring> + <tp:docstring>The password.</tp:docstring> </tp:member> </tp:struct> <property name="LocalCredentials" tp:name-for-bindings="Local_Credentials" type="(ss)" tp:type="Stream_Credentials" access="read"> <tp:docstring> - [FIXME]. Change notification is via - <tp:member-ref>LocalCredentialsChanged</tp:member-ref>. + [FIXME]. Change notification is via the + <tp:member-ref>LocalCredentialsChanged</tp:member-ref> signal. </tp:docstring> - </property> <signal name="LocalCredentialsChanged" @@ -241,19 +231,36 @@ Emitted when the value of <tp:member-ref>LocalCredentials</tp:member-ref> changes. </tp:docstring> - <arg name="Username" type="s" /> <arg name="Password" type="s" /> </signal> + <signal name="RelayInfoChanged" + tp:name-for-bindings="Relay_Info_Changed"> + <tp:docstring> + Emitted when the value of + <tp:member-ref>RelayInfo</tp:member-ref> changes. + </tp:docstring> + <arg name="Relay_Info" type="aa{sv}" tp:type="String_Variant_Map[]" /> + </signal> + + <signal name="STUNServersChanged" + tp:name-for-bindings="STUN_Servers_Changed"> + <tp:docstring> + Emitted when the value of + <tp:member-ref>STUNServers</tp:member-ref> changes. + </tp:docstring> + <arg name="Servers" type="a(sq)" tp:type="Socket_Address_IP[]" /> + </signal> + <property name="STUNServers" tp:name-for-bindings="STUN_Servers" type="a(sq)" tp:type="Socket_Address_IP[]" access="read"> - <tp:docstring> - 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. + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>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 + <tp:member-ref>STUNServersChanged</tp:member-ref> + signal. The IP addresses MUST NOT be given as DNS hostnames.</p> <tp:rationale> High-quality connection managers already need an asynchronous @@ -332,7 +339,11 @@ if Transport is GTalk_P2P, this is a Google relay server; otherwise, the meaning of RelayInfo is undefined.</p> - <p>If relaying is not possible for this stream, the list is empty.</p> + <p>If relaying is not possible for this stream, the list is + empty.</p> + + <p>Change notification is given via the + <tp:member-ref>RelayInfoChanged</tp:member-ref> signal.</p> </tp:docstring> </property> @@ -341,40 +352,38 @@ <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>Signals that the initial information about STUN and Relay servers has been retrieved, i.e. the - <tp:member-ref>RetrievedServerInfo</tp:member-ref> property is now - true.</p> + <tp:member-ref>HasServerInfo</tp:member-ref> property is + now true.</p> </tp:docstring> </signal> - <property name="RetrievedServerInfo" type="b" - tp:name-for-bindings="Retrieved_Server_Info" access="read"> + <property name="HasServerInfo" type="b" + tp:name-for-bindings="Has_Server_Info" access="read"> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>True if the initial information about STUN servers and Relay servers - has been retrieved. Change notification is via the + <p>True if all the initial information about STUN servers and Relay + servers has been retrieved. Change notification is via the <tp:member-ref>ServerInfoRetrieved</tp:member-ref> signal.</p> <tp:rationale> - <p>Streaming implementations that can't cope with STUN and relay - servers being added later SHOULD wait for this property - to become true before proceeding.</p> + 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:rationale> </tp:docstring> </property> <signal name="EndpointsChanged" - tp:name-for-bindings="Endpoints_Changed"> + tp:name-for-bindings="Endpoints_Changed"> <tp:docstring> Emitted when the <tp:member-ref>Endpoints</tp:member-ref> property changes. </tp:docstring> - - <arg name="EndpointsAdded" type="ao"> + <arg name="Endpoints_Added" type="ao"> <tp:docstring> Endpoints that were added. </tp:docstring> </arg> - - <arg name="EndpointsRemoved" type="ao"> + <arg name="Endpoints_Removed" type="ao"> <tp:docstring> Endpoints that no longer exist. </tp:docstring> @@ -384,8 +393,9 @@ <property name="Endpoints" tp:name-for-bindings="Endpoints" type="ao" access="read"> <tp:docstring> - <p>The list of endpoints <tp:dbus-ref namespace="ofdT.Call.Stream" - >Endpoint.DRAFT</tp:dbus-ref> that exist for this stream.</p> + <p>The list of <tp:dbus-ref namespace="ofdT.Call.Stream" + >Endpoint.DRAFT</tp:dbus-ref> objects that exist for this + stream.</p> <p>Change notification is via the <tp:member-ref>EndpointsChanged</tp:member-ref> signal.</p> diff --git a/spec/Channel_Interface_DTMF.xml b/spec/Channel_Interface_DTMF.xml index c74dd5136..806d8642d 100644 --- a/spec/Channel_Interface_DTMF.xml +++ b/spec/Channel_Interface_DTMF.xml @@ -19,7 +19,10 @@ License along with this library; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</p> </tp:license> <interface name="org.freedesktop.Telepathy.Channel.Interface.DTMF"> - <tp:requires interface="org.freedesktop.Telepathy.Channel.Type.StreamedMedia"/> + <tp:xor-requires> + <tp:requires interface="org.freedesktop.Telepathy.Channel.Type.StreamedMedia"/> + <tp:requires interface="org.freedesktop.Telepathy.Channel.Type.Call.DRAFT"/> + </tp:xor-requires> <tp:changed version="0.19.6">The <tp:type>Stream_ID</tp:type>s in this interface should now be ignored by CMs. This is primarily to allow this interface to be used with <tp:dbus-ref @@ -126,22 +129,47 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ <method name="MultipleTones" tp:name-for-bindings="Multiple_Tones"> <tp:added version="0.19.6" /> + <tp:changed version="0.21.UNRELEASED">The characters [pPxXwW,] must + also be supported.</tp:changed> <arg direction="in" name="Tones" type="s"> - <tp:docstring>A string representation of one or more DTMF - events.</tp:docstring> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>A string representation of one or more DTMF + events. Implementations of this method MUST support all of the + following characters in this string:</p> + + <ul> + <li>the digits 0-9, letters A-D and a-d, and symbols '*' and '#' + correspond to the members of <tp:type>DTMF_Event</tp:type></li> + + <li>any of 'p', 'P', 'x', 'X' or ',' (comma) results in an + implementation-defined pause, typically for 3 seconds</li> + + <li>'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 <tp:member-ref>TonesDeferred</tp:member-ref> signal + with the rest of the string as its argument: see that signal + for details</li> + </ul> + </tp:docstring> </arg> <tp:docstring> <p>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 - <a href="http://www.rfc-editor.org/rfc/rfc4733.txt">RFC4733</a>). - 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.</p> + 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.</p> + <tp:rationale> - 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. + <p>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.</p> + + <p>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 <code>audio/telephone-event</code>.</p> </tp:rationale> <p>Tone overlaping or queueing is not supported, so this method can only @@ -191,6 +219,47 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ </tp:docstring> </property> + <property name="DeferredTones" tp:name-for-bindings="Deferred_Tones" + type="s" access="read"> + <tp:added version="0.21.UNRELEASED" /> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The tones waiting for the user to continue, if any.</p> + + <p>When this property is set to a non-empty value, + <tp:member-ref>TonesDeferred</tp:member-ref> is emitted. + When any tones are played (i.e. whenever + <tp:member-ref>SendingTones</tp:member-ref> is emitted), + this property is reset to the empty string.</p> + </tp:docstring> + </property> + + <signal name="TonesDeferred" tp:name-for-bindings="Tones_Deferred"> + <tp:added version="0.21.UNRELEASED" /> + <arg name="Tones" type="s"> + <tp:docstring>The new non-empty value of + <tp:member-ref>DeferredTones</tp:member-ref>.</tp:docstring> + </arg> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Emitted when 'w' or 'W', indicating "wait for the user to continue", + is encountered while playing a DTMF string queued by + <tp:member-ref>MultipleTones</tp:member-ref> or + <tp:member-ref>InitialTones</tp:member-ref>. Any queued DTMF events + after the 'w', which have not yet been played, are placed in the + <tp:member-ref>DeferredTones</tp:member-ref> property and copied + into this signal's argument.</p> + + <p>When the channel handler is ready to continue, it MAY pass the + value of <tp:member-ref>DeferredTones</tp:member-ref> to + <tp:member-ref>MultipleTones</tp:member-ref>, 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.</p> + + <p>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.</p> + </tp:docstring> + </signal> + <signal name="SendingTones" tp:name-for-bindings="Sending_Tones"> <tp:added version="0.19.6" /> <arg name="Tones" type="s"> diff --git a/spec/Channel_Interface_Hold.xml b/spec/Channel_Interface_Hold.xml index 1e3a832d9..ef5a08f19 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. </tp:license> <interface name="org.freedesktop.Telepathy.Channel.Interface.Hold"> - <tp:requires interface="org.freedesktop.Telepathy.Channel.Type.StreamedMedia"/> + <tp:xor-requires> + <tp:requires interface="org.freedesktop.Telepathy.Channel.Type.StreamedMedia"/> + <tp:requires interface="org.freedesktop.Telepathy.Channel.Type.Call.DRAFT"/> + </tp:xor-requires> <tp:changed version="0.17.4">first API-stable version</tp:changed> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> diff --git a/spec/Channel_Type_Call.xml b/spec/Channel_Type_Call.xml index 50bf83f22..eb1a66358 100644 --- a/spec/Channel_Type_Call.xml +++ b/spec/Channel_Type_Call.xml @@ -344,6 +344,14 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. <td>""</td> <td>The outgoing call was not picked up and the call ended.</td> </tr> + <tr> + <td>False</td> + <td><tp:type>Call_State</tp:type>_Ended</td> + <td>Remote contact handle</td> + <td><tp:type>Call_State_Change_Reason</tp:type>_User_Requested</td> + <td><tp:error-ref>PickedUpElsewhere</tp:error-ref></td> + <td>The incoming call was ended because it was picked up elsewhere.</td> + </tr> </table> <h4>Requestable channel classes</h4> @@ -457,9 +465,9 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. <tp:dbus-ref namespace="ofdT.Call.Content.DRAFT" >Disposition</tp:dbus-ref> is <tp:type>Call_Content_Disposition</tp:type>_Initial, any - streams where the self-handle's sending state in <tp:dbus-ref - namespace="ofdT.Call.Stream.DRAFT" >Members</tp:dbus-ref> is - <tp:type>Sending_State</tp:type>_Pending_Send will be + streams where the <tp:dbus-ref + namespace="ofdT.Call.Stream.DRAFT">LocalSendingState</tp:dbus-ref> + is <tp:type>Sending_State</tp:type>_Pending_Send will be moved to <tp:type>Sending_State</tp:type>_Sending as if <tp:dbus-ref namespace="ofdT.Call.Stream.DRAFT" >SetSending</tp:dbus-ref>(True) had been called.</p> @@ -932,7 +940,10 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. <tp:member type="u" tp:type="Call_State_Change_Reason" name="Reason"> <tp:docstring> The reason, chosen from a limited set of possibilities defined by - the Telepathy specification. + the Telepathy specification. If + <tp:type>Call_State_Change_Reason</tp:type>_User_Requested then + the Actor member will dictate whether it was the local user or + a remote contact responsible. </tp:docstring> </tp:member> diff --git a/spec/Connection.xml b/spec/Connection.xml index 084705504..063e4f072 100644 --- a/spec/Connection.xml +++ b/spec/Connection.xml @@ -1050,6 +1050,125 @@ USA.</p> </tp:docstring> </tp:contact-attribute> + <method name="AddClientInterest" tp:name-for-bindings="Add_Client_Interest"> + <tp:added version="0.21.UNRELEASED"/> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Register a client's interest in notifications related to one or + more interfaces.</p> + + <p>Groups of notifications are identified by a token which is either + a D-Bus interface name, or a string that starts with a D-Bus + interface name. The meaning of each token is given by that D-Bus + interface, which MUST define it in its documentation.</p> + + <tp:rationale> + <p>Initially, all interests are in entire interface, but allowing + other strings allows subscription to part of an interface; for + instance, an interest in ...MailNotification/count could track + the number of messages without caring about their detailed + content.</p> + </tp:rationale> + + <p>For each token with which this method interacts, the + Connection tracks an "interest count" (like a reference count) for + each unique bus name that has called this method. When a client + calls this method, for each token, the interest count for its + unique bus name is incremented; when + <tp:member-ref>RemoveClientInterest</tp:member-ref> is called, + all interest counts for that unique bus name are decremented. + If the unique bus name leaves the bus (for instance, if the + client crashes or exits), all interest counts for that unique bus + name are set to zero.</p> + + <p>The Connection can then use these reference counts to + avoid subscribing to protocol-level notifications unless at least + one client has a non-zero interest count for the relevant + token.</p> + + <tp:rationale> + <p>This method exists to reduce memory and network overhead when + there is no active subscription.</p> + + <p>One situation where this is useful is <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Connection.Interface" + >Location</tp:dbus-ref>: on XMPP, location updates are received + over PEP. If the Connection advertises the + <code>geoloc+notify</code> capability, it will be sent location + updates for all contacts. To avoid consuming resources for this, + the connection should avoid advertising that capability until + a client has expressed an interest in contacts' locations.</p> + + <p>Another example of a protocol that benefits from this method is + the Google XMPP Mail Notification extension, which can be used + to implement <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Connection.Interface" + >MailNotification.DRAFT</tp:dbus-ref>. In this protocol, the CM + receives a notification that something has changed, but to get + more information, the CM must request this information. Knowing + that nobody is currently interested in this information, the CM + can avoid generating useless network traffic. Similarly, the CM + may free the list of unread messages to reduce memory overhead.</p> + </tp:rationale> + + <p>If this method is called for an interface that might require + protocol-level subscription, but the connection cannot set up + that subscription yet (for instance because the + <tp:member-ref>Status</tp:member-ref> is not Connected yet), the + Connection MUST remember the client's interest, and attempt to + subscribe to the appropriate protocol feature when this becomes + possible.</p> + + <p>Clients MAY ignore any errors raised by this method; it is intended + to be called with the reply ignored.</p> + + <tp:rationale> + <p>The only reason it could fail is if it's unimplemented, in which + case the only thing the client can usefully do is to proceed as if + it had succeeded.</p> + </tp:rationale> + </tp:docstring> + + <arg name="Tokens" type="as" direction="in"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Interfaces or parts of interfaces in which to register an + interest, represented by either a + <tp:type>DBus_Interface</tp:type>, or a string prefixed with a + <tp:type>DBus_Interface</tp:type>.</p> + + <p>If the Connection does not support one of these tokens, this + is not considered to be an error; the unsupported token is + simply ignored.</p> + </tp:docstring> + </arg> + </method> + + <method name="RemoveClientInterest" + tp:name-for-bindings="Remove_Client_Interest"> + <tp:added version="0.21.UNRELEASED"/> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Release an interest registered using + <tp:member-ref>AddClientInterest</tp:member-ref>. See that + method's documentation for details.</p> + + <p>Clients MAY ignore any errors raised by this method; it is intended + to be called with the reply ignored.</p> + + <tp:rationale> + <p>The only reasons it could fail are if it's unimplemented, or if + the client's reference-counting is wrong and it has tried to + remove a client interest that it did not add. In both cases, + there's nothing the client could do about it.</p> + </tp:rationale> + </tp:docstring> + + <arg name="Tokens" type="as" direction="in"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Interfaces or parts of interfaces that were previously passed to + <tp:member-ref>AddClientInterest</tp:member-ref>.</p> + </tp:docstring> + </arg> + </method> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>This models a connection to a single user account on a communication service. Its basic capability is to provide the facility to request and diff --git a/spec/Connection_Interface_Location.xml b/spec/Connection_Interface_Location.xml index 6c69a80c5..fe5492345 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.</ or the XEP-0080-derived <a href="http://geoclue.freedesktop.org/">Geoclue</a> API where possible.</p> + + <p>Clients of this interface SHOULD register an interest in it by calling + <tp:dbus-ref namespace="org.freedesktop.Telepathy" + >Connection.AddClientInterest</tp:dbus-ref> with an argument + containing the name of this interface, + before calling any Location method. If they do so, they SHOULD also call + <tp:dbus-ref namespace="org.freedesktop.Telepathy" + >Connection.RemoveClientInterest</tp:dbus-ref> after use to allow + the CM to release resources associated with this interface.</p> </tp:docstring> <!-- Potentially to be reinstated later: @@ -250,19 +259,29 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ </tp:mapping> <method name="GetLocations" tp:name-for-bindings="Get_Locations"> - <tp:docstring> - Return the current locations of the given contacts, if they are - already known. If any of the given contacts' locations are not known, - request their current locations, but return immediately without waiting - for a reply; if a reply with a non-empty location is later received - for those contacts, the <tp:member-ref>LocationUpdated</tp:member-ref> - signal will be emitted for them. + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Return the current locations of the given contacts, if they are + already known. If any of the given contacts' locations are not known, + request their current locations, but return immediately without waiting + for a reply; if a reply with a non-empty location is later received + for those contacts, the <tp:member-ref>LocationUpdated</tp:member-ref> + signal will be emitted for them.</p> <tp:rationale> - This method is appropriate for "lazy" location finding, for instance - displaying the location (if available) of everyone in your contact - list. + <p>This method is appropriate for "lazy" location finding, for instance + displaying the location (if available) of everyone in your contact + list.</p> </tp:rationale> + + <p>For backwards compatibility, if this method is called by a client + whose "interest count" for this interface, as defined by <tp:dbus-ref + namespace="org.freedesktop.Telepathy" + >Connection.AddClientInterest</tp:dbus-ref>, is zero, the + Connection SHOULD behave as if AddClientInterest had been called for + this interface just before that method call. Clients that do not + explicitly call AddClientInterest SHOULD NOT call <tp:dbus-ref + namespace="org.freedesktop.Telepathy" + >Connection.RemoveClientInterest</tp:dbus-ref> either.</p> </tp:docstring> <arg direction="in" name="Contacts" type="au" tp:type="Contact_Handle[]"> @@ -426,6 +445,17 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ <tp:member-ref>GetLocations</tp:member-ref> for this contact. Omitted from the result if the contact's location is not known.</p> + + <p>For backwards compatibility, if contact attributes that include + this interface are requested + by a client whose "interest count" for this interface, as defined by + <tp:dbus-ref namespace="org.freedesktop.Telepathy" + >Connection.AddClientInterest</tp:dbus-ref>, is zero, the + Connection SHOULD behave as if AddClientInterest was called for this + interface just before that request. Clients that do not explicitly + call AddClientInterest SHOULD NOT call <tp:dbus-ref + namespace="org.freedesktop.Telepathy" + >Connection.RemoveClientInterest</tp:dbus-ref> either.</p> </tp:docstring> </tp:contact-attribute> diff --git a/spec/Connection_Interface_Mail_Notification.xml b/spec/Connection_Interface_Mail_Notification.xml index cfe67a8f8..4675cad7c 100644 --- a/spec/Connection_Interface_Mail_Notification.xml +++ b/spec/Connection_Interface_Mail_Notification.xml @@ -19,10 +19,9 @@ License along with this library; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</p> </tp:license> <interface - name="org.freedesktop.Telepathy.Connection.Interface.MailNotification.DRAFT" - tp:causes-havoc="experimental"> + name="org.freedesktop.Telepathy.Connection.Interface.MailNotification.DRAFT"> <tp:requires interface="org.freedesktop.Telepathy.Connection"/> - <tp:added version="0.19.1">(as draft 1)</tp:added> + <tp:added version="0.21.UNRELEASED">(as stable API)</tp:added> <tp:flags name="Mail_Notification_Flags" value-prefix="Mail_Notification_Flag" type="u" > <tp:flag suffix="Supports_Unread_Mail_Count" value="1"> @@ -470,65 +469,6 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ </tp:docstring> </signal> - <method name="Subscribe" - tp:name-for-bindings="Subscribe"> - <tp:docstring> - <p>This method subscribes a client to the notification interface. This - MUST be called by clients before using this interface.</p> - - <p>The Connection tracks a subscription count (like a refcount) for - each unique bus name that has called Subscribe(). When a client calls - Unsubscribe(), it releases one "reference". If a client exits - (or crashes), the Connection releases all "references" held on its - behalf.</p> - - <tp:rationale> - <p>The reference count imposed on the subscription simplifies - implementation of client running in the same process - (e.g. plug-ins): two plug-ins interested in mail notification can - call Subscribe and Unsubscribe independently without interfering - with each other.</p> - - <p>This method exists to reduce memory and network overhead when - there is no active subscription. An example of a protocol that - benefits from this method is the Google XMPP Mail Notification - extension: in this protocol, the CM receives a notification - that something has changed, but to get more information, the CM - must request this information. Knowing that nobody is currently - interested in this information, the CM can avoid generating - useless network traffic. Similarly, the CM may free - the list of unread messages to reduce memory overhead.</p> - </tp:rationale> - - </tp:docstring> - <tp:possible-errors> - <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> - <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented"/> - </tp:possible-errors> - </method> - - <method name="Unsubscribe" - tp:name-for-bindings="Unsubscribe"> - <tp:docstring> - This method unsubscribes a client from the notification interface. - This SHOULD be called by each client that has successfully called - Subscribe when it no longer needs the mail notification interface. - - <tp:rationale> - See <tp:member-ref>Subscribe</tp:member-ref> for rationale. - </tp:rationale> - </tp:docstring> - <tp:possible-errors> - <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"> - <tp:docstring> - Raised if the client calling this method has no references to - release. - </tp:docstring> - </tp:error> - <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented"/> - </tp:possible-errors> - </method> - <method name="RequestInboxURL" tp:name-for-bindings="Request_Inbox_URL"> <arg direction="out" name="URL" type="(sua(ss))" tp:type="Mail_URL" > @@ -606,13 +546,16 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ connection manager to provide the necessary information for clients to open a web-based mail client without having to re-authenticate.</p> - <p>To use this interface, a client MUST first subscribe using the - <tp:member-ref>Subscribe</tp:member-ref> method. The subscription + <p>To use this interface, a client MUST first subscribe by passing the + name of this interface to the <tp:dbus-ref + namespace="org.freedesktop.Telepathy" + >Connection.AddClientInterest</tp:dbus-ref> method. The subscription mechanic aims at reducing network traffic and memory footprint in the situation where nobody is currently interesting in provided information. When done with this interface, clients SHOULD call - <tp:member-ref>Unsubscribe</tp:member-ref> to release resources in - the CM.</p> + <tp:dbus-ref namespace="org.freedesktop.Telepathy" + >Connection.RemoveClientInterest</tp:dbus-ref> to allow the CM to + release resources.</p> <p>Protocols have various different levels of Mail Notification support. To describe the level of support, the interface provides a property diff --git a/spec/Protocol_Interface_Presence.xml b/spec/Protocol_Interface_Presence.xml index 47a37eab0..314d8d37e 100644 --- a/spec/Protocol_Interface_Presence.xml +++ b/spec/Protocol_Interface_Presence.xml @@ -20,9 +20,8 @@ 02110-1301, USA.</p> </tp:license> - <interface name="org.freedesktop.Telepathy.Protocol.Interface.Presence.DRAFT" - tp:causes-havoc="experimental"> - <tp:added version="0.19.8">(draft 1)</tp:added> + <interface name="org.freedesktop.Telepathy.Protocol.Interface.Presence"> + <tp:added version="0.21.UNRELEASED">(as stable API)</tp:added> <tp:requires interface="org.freedesktop.Telepathy.Protocol"/> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> diff --git a/spec/all.xml b/spec/all.xml index 22568f5ad..d3f1d851b 100644 --- a/spec/all.xml +++ b/spec/all.xml @@ -3,7 +3,7 @@ xmlns:xi="http://www.w3.org/2001/XInclude"> <tp:title>Telepathy D-Bus Interface Specification</tp:title> -<tp:version>0.21.2</tp:version> +<tp:version>0.21.3</tp:version> <tp:copyright>Copyright © 2005-2010 Collabora Limited</tp:copyright> <tp:copyright>Copyright © 2005-2010 Nokia Corporation</tp:copyright> diff --git a/spec/errors.xml b/spec/errors.xml index 58a9d9d5d..289b8b2dd 100644 --- a/spec/errors.xml +++ b/spec/errors.xml @@ -500,6 +500,14 @@ </tp:docstring> </tp:error> + <tp:error name="Picked Up Elsewhere"> + <tp:added version="0.21.UNRELEASED"/> + <tp:docstring> + Raised when a call was terminated as a result of the local user + picking up the call on a different resource. + </tp:docstring> + </tp:error> + <tp:copyright>Copyright © 2005-2010 Collabora Limited</tp:copyright> <tp:copyright>Copyright © 2005-2009 Nokia Corporation</tp:copyright> <tp:license xmlns="http://www.w3.org/1999/xhtml"> |