Methods
UpdateLocalMediaDescription | (a{sv}: MediaDescription) | → | nothing | |
AcknowledgeDTMFChange | (y: Event, u: State) | → | nothing | |
Fail | ((uuss): Reason) | → | nothing |
Signals
NewMediaDescriptionOffer | (o: Media_Description, a{sv}: Properties) | |
MediaDescriptionOfferDone | () | |
LocalMediaDescriptionChanged | (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 | (oa{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 | (oa{sv}) |
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
UpdateLocalMediaDescription (a{sv}: MediaDescription) → nothing
Parameters
- MediaDescription — a{sv} (Media_Description_Properties)
Possible Errors
- Not Implemented
- Invalid Argument
AcknowledgeDTMFChange (y: Event, u: State) → nothing
Parameters
- Event — y (DTMF_Event)
- State — u (Sending_State)
Fail ((uuss): Reason) → nothing
Parameters
- Reason — (uuss) (Call_State_Reason)
Signals
NewMediaDescriptionOffer (o: Media_Description, a{sv}: Properties)
Parameters
- Media_Description — o
- Properties — a{sv} (Media_Description_Properties)
Rationale:
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.
MediaDescriptionOfferDone ()
Emitted when a MediaDescription has been handled.
Emission of this signal indicates that the
MediaDescriptionOffer property has
changed to
("/", 0, {})
.
LocalMediaDescriptionChanged (a{sv}: Updated_Media_Description)
Parameters
- Updated_Media_Description — a{sv} (Media_Description_Properties)
The local content description that was updated
Change notification for LocalMediaDescriptions
RemoteMediaDescriptionsChanged (a{ua{sv}}: Updated_Media_Descriptions)
Parameters
- Updated_Media_Descriptions — a{ua{sv}} (Contact_Media_Description_Properties_Map)
The remote content descriptions that were updated
Change notification for RemoteMediaDescriptions
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
DTMFChangeRequested (y: Event, u: State)
Parameters
- Event — y (DTMF_Event)
- State — u (Sending_State)
Properties
RemoteMediaDescriptions — a{ua{sv}} (Contact_Media_Description_Properties_Map)
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.
LocalMediaDescriptions — a{ua{sv}} (Contact_Media_Description_Properties_Map)
A map from contact handles to the descriptions the local side responsed with.
MediaDescriptionOffer — (oa{sv}) (Media_Description_Offer)
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:
Change notification is via the NewMediaDescriptionOffer and MediaDescriptionOfferDone signals.
Packetization — u (Call_Content_Packetization_Type)
The packetization method in use for this content.
CurrentDTMFEvent — y (DTMF_Event)
CurrentDTMFState — u (Sending_State)
Types
Call_Content_Packetization_Type — u
- RTP (0)
- Raw (1)
- MSN_Webcam (2)
Contact_Codec_Map — a{ua(usuuba{ss})}
- Handle — u (Contact_Handle)
- Codecs — a(usuuba{ss}) (Codec_List)
Contact_Media_Description_Properties_Map — a{ua{sv}}
- Remote_Contact — u (Handle)
- Media_Description_Properties — a{sv} (Media_Description_Properties)
Codec — (usuuba{ss})
- Identifier — u
- Name — s
- Clockrate — u
- Channels — u
- Updated — b
- Parameters — a{ss} (String_String_Map)
Rationale:
Media_Description_Offer — (oa{sv})
- Media_Description — o
- Properties — a{sv} (Media_Description_Properties)