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.

(as stable API)

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.

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. 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 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). 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. The remote contact this description refers to or 0. This matches the RemoteContact property on MediaDescription The properties of the description The remote description offer and its information The object path to the MediaDescription The immutable properties of all interfaces of the codec description. 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. 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. The updated media description that the local side wants to use.

The protocol does not support changing the codecs mid-call. The description given is invalid in some way.

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.

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

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.

The object path of the new media description. This replaces any previous media description. The immutable properties of the remote media description. 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 MediaDescription has been handled.

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

Change notification for LocalMediaDescriptions

The local content description that was updated

Change notification for RemoteMediaDescriptions

The remote content descriptions that were updated

Removal notification for RemoteMediaDescriptions and LocalMediaDescriptions

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

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.

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.

A packetization method that can be used for a content. Real-time Transport Protocol, as documented by RFC 3550. Raw media. 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.

The packetization method in use for this content.

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. The event to send (or stop sending). Either Pending_Send or Pending_Stop_Sending. Called by the streaming implementation in response to DTMFChangeRequested to confirm that it has started or stopped sending the event in question. The event referred to in the corresponding DTMFChangeRequested signal. Either Sending or None. The currently requested DTMF event (for state-recoverability of DTMFChangeRequested). Should be ignored if CurrentDTMFState is None. The current DTMF state (for state-recoverability of DTMFChangeRequested). Signal an unrecoverable error for this content, and remove it. A reason struct describing the error.