AudioVideoFlow

This content is no longer actively maintained. It is provided as is, for anyone who may still be using these technologies, with no warranties or claims of accuracy with regard to the most recent product version or service release.

An AudioVideoFlow instance represents a media connection with a single remote participant.

AudioVideoFlow State Transitions

The AudioVideoFlow state transitions are shown in the following illustration.

1. The transition from Idle to Active occurs when the AudioVideoFlow instance determines that media can now be exchanged (or should be able to be exchanged) with the remote peer. The most common causes for this transition are:

   • Media (RTP or RTCP) is received from the remote peer.

   • For an incoming call, acknowledgement from the caller that it has received a provisional or final acceptance of the call (by the application calling, respectively, BeginEstablishEarlyMedia() or BeginAccept()). That is, a SIP PRACK or ACK message is received from the caller.

   • Special case: The remote endpoint negotiates the audio channel to be disabled. Disabled media means that no transport connection will be established; in SDP, the media is identified with a ‘c=IN IP4 0.0.0.0’ connection address line.

2. The transition from Active to Terminated occurs when a call ends after the media session is established. The most common causes for this transition are:

   • One of the endpoints terminates the call.

   • The media session fails due to loss of media (for example, an RTP timeout).

   • An unrecoverable error (for example, a SIP timeout) occurs during a renegotiation (re-INVITE) request sent to the remote peer.

3. The transition from Idle to Terminated occurs when there is a failure in establishing the call. The most common causes for this transition are:

   • The call is rejected.

   • There is a failure in the offer/answer negotiation (for example, a failure to negotiate encryption parameters (SRTP)).

   • The application terminates the call before the media session is established.

   • The media session fails to establish a working transport connection between endpoints.

AudioVideoFlow Constructors

The AudioVideoFlow class has no public constructors.

AudioVideoFlow Properties

The following are the public properties on the AudioVideoFlow class.

// Gets the current hold status.
public HoldType HoldStatus {get;}

// Gets the AudioVideoFlow's TonePolicy.
public TonePolicy TonePolicy {get;}

// Gets whether tone is enabled.
public bool ToneEnabled {get;}

// Gets the current encryption policy.
public MediaEncryption EncryptionPolicy {get;}

// Gets the Audio control.
public AudioControl Audio {get;}

// Gets the Player currently attached to this object.
public Player Player {get;}

// Gets the Recorder currently attached to this object.
public Recorder Recorder {get;}

// Gets the DTMF currently attached to this object.
public ToneController ToneController {get;}

// Gets the speech recognition connector attached to this AudioVideoFlow.
public SpeechRecognitionConnector SpeechRecognitionConnector {get;}

// Gets the speech synthesis connector attached to this AudioVideoFlow.
public SpeechSynthesisConnector SpeechSynthesisConnector {get;}

The Audio property provides access to an AudioControl instance, which provides access to the audio channel and can be used to mute and unmute the audio channel.

The Recorder property provides access to a Recorder instance, which can be used to record audio and video data.

The Player property provides access to a Player instance, which can be used to play audio data captured previously.

The ToneController property provides access to a ToneController instance. A ToneController can be used to send and receive Dual-Tone Multiple-Frequency (DTMF) tones.

The SpeechRecognitionConnector property provides access to a SpeechRecognitionConnector instance, which can use one or more grammars to analyze human speech for semantic meaning.

The SpeechSynthesisConnector property provides access to a SpeechSynthesisConnector instance, which can be used to convert text to speech.

Player, Recorder, ToneController, SpeechRecognitionConnector, and SpeechSynthesisConnector are considered to be devices. Although these devices are represented as properties on the AudioVideoFlow class, they are not automatically instantiated. Before any of these devices can be used, it must be created, and then attached to an AudioVideoFlow instance. The following code example shows the steps required to create a Player and attach it to an existing AudioVideoFlow instance.

Player myPlayer = new Player();
myPlayer.AttachFlow(avFlow);

When the device is no longer needed, the AudioVideoFlow instance that is attached to the device must be detached, as this does not happen automatically. The following sample shows how this is done.

myPlayer.DetachFlow(avFlow);

For more information about these devices, see Audio Devices in UCMA 2.0 Core.

AudioVideoFlow Methods

The following are the public methods on the AudioVideoFlow class.

// Applies changes based on a template.
public IAsyncResult BeginApplyChanges(
    AudioVideoFlowTemplate template,
    AsyncCallback userCallback,
    object o);

// Applies changes based on a template.
public IAsyncResult BeginApplyChanges(
    AudioVideoFlowTemplate template,
    IEnumerable<SignalingHeader> headers,
    AsyncCallback userCallback,
    object o);

// Waits for the pending BeginApplyChanges operation
// to complete.
public void EndApplyChanges(IAsyncResult result);

// Copies the properties from the template to an AudioVideoFlow.
// Must raise an exception if the AudioVideoFlow is not in the Idle state.
public void Initialize(AudioVideoFlowTemplate template);

// Holds the AudioVideoFlow.
public IAsyncResult BeginHold(
    HoldType holdType,
    AsyncCallback userCallback,
    object o);

// Holds the AudioVideoFlow.
public IAsyncResult BeginHold(
    HoldType holdType,
    IEnumerable<SignalingHeader> headers,
    AsyncCallback userCallback,
    object o);

// Ends the hold.
public void EndHold(IAsyncResult result);

// Retrieves the AudioVideoFlow.
public IAsyncResult BeginRetrieve(AsyncCallback userCallback, object o);

// Retrieves the AudioVideoFlow.
public IAsyncResult BeginRetrieve(
    IEnumerable<SignalingHeader> headers,
    AsyncCallback userCallback,
    object o);

// Ends the retrieval.
public void EndRetrieve(IAsyncResult result);

An application that intends to configure the AudioVideoFlow by using Initialize() must process the AudioVideoFlowConfigurationRequested event synchronously. AudioVideoFlowConfigurationRequested is an AudioVideoCall event. The application can assume that the AudioVideoFlowState will not change from Idle during the event callback, so no state check is necessary. Only an invalid template configuration can possibly cause Initialize to throw an exception.

If BeginHold(), BeginRetrieve(), or BeginApplyChanges() are called shortly after the State of an AudioVideoFlow instance is Active, each of these methods can fail, producing the error message, “A renegotiate is already in progresss.” To work around this problem, embed each call to BeginHold, BeginRetrieve, and BeginApplyChanges in a try - catch block inside a loop. This way, if an exception is thrown, another attempt at calling the method can take place after the renegotiation has completed.

AudioVideoFlow Events

The following are the public events on the AudioVideoFlow class.

//Raised by AudioVideoFlow when any configuration changes.
// Changes can occur due to remote user, internal configurations, ApplyChanges, Hold, and Retrieve.
public event EventHandler<AudioVideoFlowConfigurationChangedEventArgs> ConfigurationChanged;