From dfd04471de219b42095b1bb5319207a07b70a738 Mon Sep 17 00:00:00 2001 From: Jonny Lamb Date: Wed, 20 Oct 2010 14:21:26 +0100 Subject: Call_Content_Interface_Media: clarify codec offering Signed-off-by: Jonny Lamb --- spec/Call_Content_Interface_Media.xml | 72 ++++++++++++++++++++++++++++------- 1 file changed, 58 insertions(+), 14 deletions(-) (limited to 'spec/Call_Content_Interface_Media.xml') diff --git a/spec/Call_Content_Interface_Media.xml b/spec/Call_Content_Interface_Media.xml index 0552111a..470e6d0d 100644 --- a/spec/Call_Content_Interface_Media.xml +++ b/spec/Call_Content_Interface_Media.xml @@ -29,25 +29,69 @@

Interface to use by a software implementation of media streaming.

-

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

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

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

-

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

For incoming calls on protocols where codecs are proposed when + starting the call (for example, Jingle), the 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, + +

The streaming implementation should look at the remote codec + map and the codecs known by the local user and call + CodecOffer.DRAFT.Accept - should be called with the details of these codecs.

+ on the intersection of these two codec lists.

+ +

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

+ +

Changing codecs mid-call

+ +

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

+ +

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

-- cgit v1.2.3 From 71ddf93f2ec6635189bd1bfc419c4ab41b0f1b6e Mon Sep 17 00:00:00 2001 From: Jonny Lamb Date: Wed, 20 Oct 2010 14:22:55 +0100 Subject: Call_Content_Interface_Media: documented when not to use UpdateCodecs Signed-off-by: Jonny Lamb --- spec/Call_Content_Interface_Media.xml | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) (limited to 'spec/Call_Content_Interface_Media.xml') diff --git a/spec/Call_Content_Interface_Media.xml b/spec/Call_Content_Interface_Media.xml index 470e6d0d..6df2f2de 100644 --- a/spec/Call_Content_Interface_Media.xml +++ b/spec/Call_Content_Interface_Media.xml @@ -204,7 +204,14 @@ - Raised when not used during an existing call to update the codec mapping. + Raised when a CodecOffer.DRAFT + object exists and is referred to in the + CodecOffer property which + should be used instead of calling this method, or before + the content's initial CodecOffer.DRAFT + object has appeared. -- cgit v1.2.3 From cd03fba66d879d792aa8794251745da4a14a08eb Mon Sep 17 00:00:00 2001 From: Jonny Lamb Date: Thu, 21 Oct 2010 18:22:35 +0100 Subject: Call_Content_Interface_Media: add note about non-negotiable codecs Signed-off-by: Jonny Lamb --- spec/Call_Content_Interface_Media.xml | 10 ++++++++++ 1 file changed, 10 insertions(+) (limited to 'spec/Call_Content_Interface_Media.xml') diff --git a/spec/Call_Content_Interface_Media.xml b/spec/Call_Content_Interface_Media.xml index 6df2f2de..5b895010 100644 --- a/spec/Call_Content_Interface_Media.xml +++ b/spec/Call_Content_Interface_Media.xml @@ -78,6 +78,16 @@ set is accepted, CodecsChanged will fire to signal this change.

+

Protocols without codec negotiation

+ +

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

+

Changing codecs mid-call

To update the codec list used mid-call, the -- cgit v1.2.3 From 33bcfba2cbce2059ebd9303875d4dcd53daf91b6 Mon Sep 17 00:00:00 2001 From: Jonny Lamb Date: Tue, 26 Oct 2010 16:14:20 +0100 Subject: Codec_Offer: make it one per contact Fixes: fd.o#28695 Signed-off-by: Jonny Lamb --- spec/Call_Content_Codec_Offer.xml | 17 ++++++++++++----- spec/Call_Content_Interface_Media.xml | 20 ++++++++++---------- 2 files changed, 22 insertions(+), 15 deletions(-) (limited to 'spec/Call_Content_Interface_Media.xml') diff --git a/spec/Call_Content_Codec_Offer.xml b/spec/Call_Content_Codec_Offer.xml index e0a791f3..f88143f6 100644 --- a/spec/Call_Content_Codec_Offer.xml +++ b/spec/Call_Content_Codec_Offer.xml @@ -65,16 +65,23 @@ - - A map from remote contact to the list of codecs he or she - supports. + A list of codecs the remote contact supports. + + + The contact handle that this codec offer applies to. + + + + diff --git a/spec/Call_Content_Interface_Media.xml b/spec/Call_Content_Interface_Media.xml index 5b895010..2d023572 100644 --- a/spec/Call_Content_Interface_Media.xml +++ b/spec/Call_Content_Interface_Media.xml @@ -41,14 +41,14 @@ NewCodecOffer signal.

The RemoteContactCodecMap + namespace="ofdT.Call.Content.CodecOffer.DRAFT">RemoteContactCodecs property on the codec offer will determine the codecs that should be proposed by the local user's streaming implementation. An empty list means all codecs are available.

For incoming calls on protocols where codecs are proposed when starting the call (for example, Jingle), the RemoteContactCodecMap + namespace="ofdT.Call.Content.CodecOffer.DRAFT">RemoteContactCodecs will contain information on the codecs that have already been proposed by the remote contact, otherwise the codec map will be the empty list.

@@ -61,7 +61,7 @@

This means that in practice, outgoing calls will have a codec offer pop up with no information in the RemoteContactCodecMap, + namespace="ofdT.Call.Content.CodecOffer.DRAFT">RemoteContactCodecs, so the local user will call Accept with the list of all codecs supported. If this codec offer is @@ -70,7 +70,7 @@ Accept. If the call is incoming, then the RemoteContactCodecMap + namespace="ofdT.Call.Content.CodecOffer.DRAFT">RemoteContactCodecs will contain details of the remote contact's codecs and the local user will call Accept @@ -84,7 +84,7 @@ popping up the initial content's CodecOffer.DRAFT object with an empty RemoteContactCodecMap, + namespace="ofdT.Call.Content.CodecOffer.DRAFT">RemoteContactCodecs, the CM should set the supported codec values to known codec values in the said object's codec map.

@@ -167,7 +167,7 @@ tp:type="Contact_Codec_Map"> The CodecOffer.DRAFT.RemoteContactCodecMap property + >CodecOffer.DRAFT.RemoteContactCodecs property of the codec offer. @@ -261,12 +261,12 @@

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

Having the RemoteContactCodecMap + namespace="ofdT.Call.Content.CodecOffer.DRAFT">RemoteContactCodecs property here saves a D-Bus round-trip - it shouldn't be necessary to get the property from the CodecOffer object, in practice. @@ -282,13 +282,13 @@ CodecOffer.DRAFT object, and its CodecOffer.DRAFT.RemoteContactCodecMap property. + >CodecOffer.DRAFT.RemoteContactCodecs property. If the object path is "/" then there isn't an outstanding codec offer, and the mapping MUST be empty.

Having the RemoteContactCodecMap + namespace="ofdT.Call.Content.CodecOffer.DRAFT">RemoteContactCodecs property here saves a D-Bus round-trip - it shouldn't be necessary to get the property from the CodecOffer object, in practice. -- cgit v1.2.3 From 43c519f9711df709ea3df44a8e9597026be322d3 Mon Sep 17 00:00:00 2001 From: Sjoerd Simons Date: Wed, 3 Nov 2010 17:31:17 +0000 Subject: Add contact item to the structs referring to a CodecOffer --- spec/Call_Content_Interface_Media.xml | 46 ++++++++++++++++++++++++----------- 1 file changed, 32 insertions(+), 14 deletions(-) (limited to 'spec/Call_Content_Interface_Media.xml') diff --git a/spec/Call_Content_Interface_Media.xml b/spec/Call_Content_Interface_Media.xml index 2d023572..e86a07a1 100644 --- a/spec/Call_Content_Interface_Media.xml +++ b/spec/Call_Content_Interface_Media.xml @@ -42,12 +42,15 @@

The RemoteContactCodecs - property on the codec offer will determine the codecs that - should be proposed by the local user's streaming - implementation. An empty list means all codecs are available.

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

For incoming calls on protocols where codecs are proposed when - starting the call (for example, Jingle), the Jingle), + the RemoteContactCodecs will contain information on the codecs that have already been proposed by the remote contact, otherwise the codec map will @@ -163,8 +166,13 @@ >CodecOffer.DRAFT - + + + The contact handle that this codec offer applies to. + + + The CodecOffer.DRAFT.RemoteContactCodecs property @@ -250,15 +258,20 @@

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

+ (Contact, Offer, Codecs).

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

The CodecOffer.DRAFT.RemoteContactCodecs property @@ -276,21 +289,26 @@ + type="(oua(usuua{ss}))" tp:type="Codec_Offering" access="read">

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

Having the RemoteContactCodecs - property here saves a D-Bus round-trip - it shouldn't be - necessary to get the property from the CodecOffer object, in + namespace="ofdT.Call.Content.CodecOffer.DRAFT" + >RemoteContact and + RemoteContactCodecs + properties here saves a D-Bus round-trip - it shouldn't be + necessary to get these properties from the CodecOffer object, in practice. -- cgit v1.2.3