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)

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.

Codec negotiation

When a new Call.DRAFT channel appears, whether it was requested or not, a CodecOffer.DRAFT will either be waiting in the CodecOffer property, or will appear at some point via the NewCodecOffer signal.

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

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

The streaming implementation should look at the remote codec map and the codecs known by the local user and call CodecOffer.DRAFT.Accept on the intersection of these two codec lists.

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

Protocols without codec negotiation

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

Changing codecs mid-call

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

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

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. Number of channels of the codec if applicable, otherwise 0. Extra parameters for this codec. A map from contact to the list of codecs he or she supports. A contact handle. The codecs that the contact supports. A codec offer and its corresponding remote contact codec map. The object path to the CodecOffer.DRAFT The contact handle that this codec offer applies to. The CodecOffer.DRAFT.RemoteContactCodecs property of the codec offer.

Emitted when the codecs in use change.

As well as acting as change notification for the ContactCodecMap, emission of this signal implies that the CodecOffer property has changed to ('/', {}).

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 ContactCodecMap, probably because those contacts left the call. 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 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.

A map from contact handles (including the local user's own handle) to the codecs supported by that contact.

Change notification is via the CodecsChanged signal.

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

Emission of this signal indicates that the CodecOffer property has changed to (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 of the codec offer.

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

The object path to the current CodecOffer.DRAFT object, its 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 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.

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