Interface Call1.Content.Interface.Media

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

Methods

UpdateLocalMediaDescription (u: Remote_Contact, a{sv}: MediaDescription) → nothing
AcknowledgeDTMFChange (y: Event, u: State) → nothing
Fail ((uuss): Reason) → nothing

Signals

NewMediaDescriptionOffer (o: Media_Description, u: Contact, a{sv}: Properties)
MediaDescriptionOfferDone ()
LocalMediaDescriptionChanged (u: Remote_Contact, a{sv}: Updated_Media_Description)
RemoteMediaDescriptionsChanged (a{ua{sv}}: Updated_Media_Descriptions)
MediaDescriptionsRemoved (au: Removed_Media_Descriptions)
DTMFChangeRequested (y: Event, u: State)

Properties

RemoteMediaDescriptions a{ua{sv}} (Contact_Media_Description_Properties_Map) Read only
LocalMediaDescriptions a{ua{sv}} (Contact_Media_Description_Properties_Map) Read only
MediaDescriptionOffer (oua{sv}) (Media_Description_Offer) Read only
Packetization u (Call_Content_Packetization_Type) Read only Immutable
CurrentDTMFEvent y (DTMF_Event) Read only
CurrentDTMFState u (Sending_State) Read only

Types

Call_Content_Packetization_Type Enum u
Contact_Codec_Map Mapping a{ua(usuuba{ss})}
Contact_Media_Description_Properties_Map Mapping a{ua{sv}}
Codec Struct (usuuba{ss})
Media_Description_Offer Struct (oua{sv})
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 UNRELEASED. (draft 2)
Objects implementing this interface must also implement:

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 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 Call1 channel appears (whether it was requested or not) a MediaDescription object will either be waiting in the MediaDescriptionOffer property, or will appear at some point via the NewMediaDescriptionOffer signal.

If nothing is known about the remote side's Media capabilities (e.g. outgoing SIP/XMPP call), this MediaDescription will pop up with {HasRemoteInformation = false, FurtherNegotiationRequired = true}, and the local user's streaming implementation SHOULD call Accept, with a description of all supported codecs and other features. The CM will then send this information to the remote side (and LocalMediaDescriptionChanged will fire with details of the description passed into Accept for debugging purposes).

When the remote codecs and other content information are available (e.g. Remote user replies to initial offer, or sends a new offer of their own, a new MediaDescription will appear, with {HasRemoteInformation = true, FurtherNegotiationRequired = false}, and the Codecs property on the description offer set to the codecs which are supported by the remote contact. The local user's streaming implementation SHOULD then call Accept, with a description that is compatible with the one one in the offer. After the codec set is accepted, both LocalMediaDescriptionChanged and RemoteMediaDescriptionsChanged will fire to signal their respective changes, to aid with debugging. Note that if Accept is called, with FurtherNegotiationRequired set to false, the CM should be able to rely on the fact that the description passed into Accept is compatible with the one in the offer, and the description passed into Accept will not be signalled to the remote side.

Changing codecs mid-call

To update the codecs in the local (and optionally remote) media descriptions mid-call, the UpdateLocalMediaDescription method should be called with details of the new codec list. If this is accepted, then LocalMediaDescriptionChanged will be emitted with the new codec set.

If parameters requiring negotiation are changed, then the FurtherNegotiationRequired property should be set to TRUE, and the new media description should only be used once they come in a new MediaDescriptionOffer

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

Protocols without negotiation

For protocols where the codecs are not negotiable, the initial content's MediaDescription object will appear with HasRemoteInformation, set to true and the known supported codec values in Codecs.

Methods

(Permalink)

UpdateLocalMediaDescription (u: Remote_Contact, a{sv}: MediaDescription) → nothing

Parameters

  • Remote_Contact — u (Handle)
    • The remote contact that this description should be negotiated with (or 0 to mean "negotiate this with everyone"). Note that encoding the same video multiple times is often needlessly expensive, so differences in MediaDescriptions negotiated with different parties in the call should be limited to payloading parameters if possible.
  • MediaDescription — a{sv} (Media_Description_Properties)
    • The updated media description that the local side wants to use.
Update the local codec mapping and other interfaces of the MediaDescription. This method should only be used during an existing call to update the local media description. This may trigger a re-negotiation which may result in new new MediaDescriptionOffers if the "FurtherNegotiationRequired" property is TRUE. Otherwise, only parameters which strictly describe the media being sent can be changed.

Possible Errors

(Permalink)

AcknowledgeDTMFChange (y: Event, u: State) → nothing

Parameters

Called by the streaming implementation in response to DTMFChangeRequested to confirm that it has started or stopped sending the event in question.
(Permalink)

Fail ((uuss): Reason) → nothing

Parameters

Signal an unrecoverable error for this content, and remove it.

Signals

(Permalink)

NewMediaDescriptionOffer (o: Media_Description, u: Contact, a{sv}: Properties)

Parameters

  • Media_Description — o
    • The object path of the new media description. This replaces any previous media description.
  • Contact — u
    • The remote contact the media description belongs to.
  • Properties — a{sv} (Media_Description_Properties)
    • The immutable properties of the remote media description.
    Rationale:
    Having all the MediaDescription properties here saves a D-Bus round-trip - it shouldn't be necessary to get the properties from the MediaDescription object, in practice.

Emitted when a new MediaDescription appears. The streaming >implementation MUST respond by calling the Accept or Reject method on the description object appeared.

Emission of this signal indicates that the MediaDescriptionOffer property has changed to (Description, Contact, MediaDescriptionProperties).

When the MediaDescriptionOffer has been dealt with then MediaDescriptionOfferDone must be emitted before NewMediaDescriptionOffer is emitted again.

(Permalink)

MediaDescriptionOfferDone ()

Emitted when a MediaDescription has been handled.

Emission of this signal indicates that the MediaDescriptionOffer property has changed to ("/", 0, {}).

(Permalink)

LocalMediaDescriptionChanged (u: Remote_Contact, a{sv}: Updated_Media_Description)

Parameters

  • Remote_Contact — u (Handle)
    • The remote contact that this description was negotiated with (or 0 to mean "negotiated with everyone").
  • Updated_Media_Description — a{sv} (Media_Description_Properties)

    • The local content description that was updated

Change notification for LocalMediaDescriptions

(Permalink)

RemoteMediaDescriptionsChanged (a{ua{sv}}: Updated_Media_Descriptions)

Parameters

Change notification for RemoteMediaDescriptions

(Permalink)

MediaDescriptionsRemoved (au: Removed_Media_Descriptions)

Parameters

  • Removed_Media_Descriptions — au (Contact_Handle_List)

    • The local and remote content descriptions that are no longer part of this content

Removal notification for RemoteMediaDescriptions and LocalMediaDescriptions

(Permalink)

DTMFChangeRequested (y: Event, u: State)

Parameters

Used by the CM to relay instructions from Channel.Interface.DTMF to the streaming implementation. If any contact in this call supports the telephone-event codec in their MediaDescription, this event should be sent as outlined in RFC 4733. Otherwise, it should be sent as an audible tone.

Properties

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

RemoteMediaDescriptions — a{ua{sv}} (Contact_Media_Description_Properties_Map)

Read only

A map from contact handles to descriptions supported by that contact.

Keys of this map will appear in at most one RemoteMembers. See RemoteContact for more details on how to map between MediaDescriptions and Streams.

(Permalink)

LocalMediaDescriptions — a{ua{sv}} (Contact_Media_Description_Properties_Map)

Read only

A map from contact handles to the descriptions the local side responsed with.

(Permalink)

MediaDescriptionOffer — (oua{sv}) (Media_Description_Offer)

Read only

The object path to the current MediaDescription object, its RemoteContact and a mapping of the MediaDescriptions properties. If the object path is "/" then there isn't an outstanding content description, and the mapping MUST be empty.

Rationale:
Having all MediaDescription properties here saves a D-Bus round-trip - it shouldn't be necessary to get these properties from the Content MediaDescription object, in practice.

Change notification is via the NewMediaDescriptionOffer and MediaDescriptionOfferDone signals.

(Permalink)

Packetization — u (Call_Content_Packetization_Type)

Read only
This property is immutable which means that it can never change.
Added in 0.21.2.

The packetization method in use for this content.

(Permalink)

CurrentDTMFEvent — y (DTMF_Event)

Read only
The currently requested DTMF event (for state-recoverability of DTMFChangeRequested). Should be ignored if CurrentDTMFState is None.
(Permalink)

CurrentDTMFState — u (Sending_State)

Read only
The current DTMF state (for state-recoverability of DTMFChangeRequested).

Types

Enum (Permalink)

Call_Content_Packetization_Type — u

Added in 0.21.2.
A packetization method that can be used for a content.
  • RTP (0)
    • Real-time Transport Protocol, as documented by RFC 3550.
  • Raw (1)
    • Raw media.
  • MSN_Webcam (2)
    • MSN webcam. This is the video-only one-way type which was used in earlier versions of WLM. Although no longer used, modern WLM clients still support the MSN webcam protocol.
Mapping (Permalink)

Contact_Codec_Map — a{ua(usuuba{ss})}

A map from contact to the list of codecs he or she supports.
  • Handle — u (Contact_Handle)
    • A contact handle.
  • Codecs — a(usuuba{ss}) (Codec_List)
    • The codecs that the contact supports.
Mapping (Permalink)

Contact_Media_Description_Properties_Map — a{ua{sv}}

Struct (Permalink)

Codec — (usuuba{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.
  • Updated — b
    • This should be set to true in calls to Accept and UpdateLocalMediaDescription if this codec has changed in a way that needs to be signalled over the network. If it is set to false, the CM is allowed ignore any differences between the current parameters and the previous ones
    Rationale:
    This mechanism may be used to save bandwidth and avoid the CM having to calculate diffs against previous versions of this struct, which can lead to false-positives (e.g. redundant ptime updates).
  • Parameters — a{ss} (String_String_Map)
    • Extra parameters for this codec.
Struct (Permalink)

Media_Description_Offer — (oua{sv})

The remote description offer and its information
  • Media_Description — o
    • The object path to the MediaDescription
  • Remote_Contact — u (Contact_Handle)
    • The contact handle that this description applies to.
  • Properties — a{sv} (Media_Description_Properties)
    • The immutable properties of all interfaces of the codec description.
    Rationale:
    Having all the codec description properties here saves a D-Bus round-trip - it shouldn't be necessary to get the properties from the MediaDescription object, in practice.