Call.Content.I.Media.DRAFT — Telepathy D-Bus Interface Specification

# Interface Call.Content.Interface.Media.DRAFT

Interface Index (Compact) | Summary | Description | Methods | Signals | Properties | Types

### Methods

UpdateCodecs | (a(usuua{ss}): Codecs) | → | nothing |

### Signals

CodecsChanged | (a{ua(usuua{ss})}: Updated_Codecs, au: Removed_Contacts) |
NewCodecOffer | (u: Contact, o: Offer, a(usuua{ss}): Codecs) |

### Properties

ContactCodecMap | a{ua(usuua{ss})} (Contact_Codec_Map) | Read only |  |
CodecOffer | (oua(usuua{ss})) (Codec_Offering) | Read only |  |

### Types

Contact_Codec_Map | Mapping | a{ua(usuua{ss})} |
Codec | Struct | (usuua{ss}) |
Codec_Offering | Struct | (oua(usuua{ss})) |

WARNING: This interface is experimental and is likely to cause havoc to your API/ABI if bindings are generated. Do not include this interface in libraries that care about compatibility.
Added in 0.19.0. (draft 1)
Objects implementing this interface must also implement:

- org.freedesktop.Telepathy.Call.Content.DRAFT

### Description

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.

# Methods

(Permalink)

## UpdateCodecs (a(usuua{ss}): Codecs) → nothing

### Parameters

- Codecs — a(usuua{ss}) (Codec_List)
The codecs now supported by the local user.

Update the local codec mapping. This method should only be used during an existing call to update the codec mapping.

### Possible Errors

- Not Available
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.

# Signals

(Permalink)

## CodecsChanged (a{ua(usuua{ss})}: Updated_Codecs, au: Removed_Contacts)

### Parameters

- Updated_Codecs — a{ua(usuua{ss})} (Contact_Codec_Map)
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.
- Removed_Contacts — au (Contact_Handle_List)
A list of keys which were removed from the ContactCodecMap, probably because those contacts left the call.

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 `('/', {})`.

(Permalink)

## NewCodecOffer (u: Contact, o: Offer, a(usuua{ss}): Codecs)

### Parameters

- Contact — u
The contact the codec offer belongs to.
- Offer — o
The object path of the new codec offer. This replaces any previous codec offer.
- Codecs — a(usuua{ss}) (Codec_List)

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

##### Rationale:

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.

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

# Properties

Accessed using the org.freedesktop.DBus.Properties interface.
(Permalink)

## ContactCodecMap — a{ua(usuua{ss})} (Contact_Codec_Map)

Read only

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.

(Permalink)

## CodecOffer — (oua(usuua{ss})) (Codec_Offering)

Read only

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.

##### Rationale:

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.

# Types

Mapping (Permalink)

## Contact_Codec_Map — a{ua(usuua{ss})}

A map from contact to the list of codecs he or she supports.

- Handle — u (Contact_Handle)
A contact handle.
- Codecs — a(usuua{ss}) (Codec_List)
The codecs that the contact supports.

Struct (Permalink)

## Codec — (usuua{ss})

A description of a codec.

- Identifier — u
Numeric identifier for the codec. This will be used as the PT in the SDP or content description.
- Name — s
The name of the codec.
- Clockrate — u
The clockrate of the codec.
- Channels — u
Number of channels of the codec if applicable, otherwise 0.
- Parameters — a{ss} (String_String_Map)
Extra parameters for this codec.

Struct (Permalink)

## Codec_Offering — (oua(usuua{ss}))

A codec offer and its corresponding remote contact codec map.

- Codec_Offer — o
The object path to the CodecOffer.DRAFT
- Remote_Contact — u (Contact_Handle)
The contact handle that this codec offer applies to.
- Remote_Contact_Codecs — a(usuua{ss}) (Codec_List)
The CodecOffer.DRAFT.RemoteContactCodecs property of the codec offer.