UnifySquare Blog

Escalating an Audio/Video Call to a Conference Call using UCMA 2.0

One of the samples in the UCMA 2.0 SDK for Office Communication Server 2007 is the "ConferenceEscalation” sample application. The UCMA 2.0 SDK samples demonstrate how to use the new Microsoft.Rtc.Collaboration name space to easily perform many collaboration activities, without having an in-depth understanding of how OCS uses the SIP protocol.

Let’s take a closer look at the “ConferenceEscalation” sample. This sample sets up a peer-to-peer audio call between two user endpoints. Next, the first user endpoint creates an ad-hoc (unscheduled) conference. Then, the first endpoint calls the new Conversation.BeginEscalateToConference() and Conversation.EndEscalateToConference() methods to automatically transfer (escalate) the second endpoint’s conversation to the ad-hoc conference.

Unfortunately, the “ConferenceEscalation” sample does not work as shipped with OCS 2007 R2. Instead, a Microsoft.Rtc.Signalling.OperationFailureException is thrown by the EndEscalateToConference() method. The failure reason is that this media provider does not support escalation. And, if you read the fine print in the UCMACore2.0 help file for OCS 2007 R2, you will indeed find that the Conversation EscalateToConference methods are only supported for the Instant Messaging modality. Indeed, as an exercise, if you change the AudioVideoCall object to an InstantMessagingCall object, and register to receive incoming InstantMessagingCall events, the sample will work.

The code that I will share with you, however, shows how to successfully transfer an existing audio/video call to a conference call using the UCMA 2.0 SDK. Accomplishing this involves the following steps:

Create a new conversation.
Create a conference using the new conversation.
Join the conference.
Call into the conference (establish a call with the conference MCU).
Transfer the original P2P call to the conference audio/video MCU.
Terminate the original P2P call, since it is now defunct.

The following code is a modification of the code in the Escalate To Conference sample application from the UCMA 2.0 SDK for OCS 2007 R2. First, of course, you must download and install the UCMA 2.0 SDK. Follow the Microsoft instructions for installing carefully. There are several pre-requisites and the SDK setup itself is a two-part install.

Note that Chris Mayo’s blog – “Unified Communications Development” at http://blogs.msdn.com/cmayo/ contains lots of information on getting setup to do UCMA 2.0 development.

Once you have the SDK installed, navigate to the “Program Files\Microsoft Office Communications Server 2007 R2\UCMA SDK 2.0\UCMACore\Sample Applications\Collaboration\QuickStarts\ConferenceEscalation” folder. Take a look at the original EscalateToConference.cs file. Build the sample and run it, noting the exception.

Then, try changing the AudioVideoCall object and related callbacks to be an InstantMessagingCall object. Run the sample again and note that this succeeds.

Finally, follow the instructions below to modify the code in the EscalateToConference.cs file. Make sure that you change the server and user settings to match your environment. Pay particular attention to the Run() and EndJoinConference() methods:

Add the following namespaces to the EscalateToConference.cs file:
- using System.Collections.Generic;
- using Microsoft.Rtc.Collaboration.Conferencing;
- using Microsoft.Rtc.Collaboration.ConferenceManagement;
Add the following global variables before the Main() method:
- private AutoResetEvent _waitForFlowActive = new AutoResetEvent(false);
- private AudioVideoCall audioVideoCall; // original AV call
Replace the existing Run() method with the following:
Add the following two callback methods to determine when the new audio/video flow is configured and active.
// Called when flow configured

void conferenceAVCall_AudioVideoFlowConfigurationRequested(object sender, AudioVideoFlowConfigurationRequestedEventArgs args)
{
    // flow is configured
    // wait for the flow state to go to active.
    args.Flow.StateChanged += new EventHandler<MediaFlowStateChangedEventArgs>(Flow_StateChanged);

    _waitForFlowActive.Set();   // go ahead and set now
}

// Called when flow state changes

void Flow_StateChanged(object sender, MediaFlowStateChangedEventArgs args)
{
    if (args.State == MediaFlowState.Active)
    {
        // flow has gone active
        _waitForFlowActive.Set();
    }
}
Replace the EndJoinConference() method with this method:
        private void EndJoinConference(IAsyncResult ar)
        {
            ConferenceSession confSession = ar.AsyncState as ConferenceSession;
            try
            {
               confSession.EndJoin(ar);

            }
            catch (OperationFailureException opFailEx)
            {
                // OperationFailureException: Indicates failure to connect the call to the remote party.
                // It is left to the application to perform real error handling here.
                Console.WriteLine(opFailEx.ToString());
            }
            catch (RealTimeException realTimeEx)
            {
                // RealTimeException may be thrown on media or link-layer failures, or call rejection (FailureResponseException)
                // It is left to the application to perform real error handling here.
                Console.WriteLine(realTimeEx.ToString());
            }

            // Method which is NOT working for audio calls.
//            confSession.Conversation.BeginEscalateToConference(EndEscalateConference, confSession.Conversation);

            // START OF MODIFIED CODE.

            // Call into the conference ourselves.
            AudioVideoCall conferenceAVCall = new AudioVideoCall(confSession.Conversation);

            // Register for call backs.
            conferenceAVCall.AudioVideoFlowConfigurationRequested += new EventHandler<AudioVideoFlowConfigurationRequestedEventArgs>(conferenceAVCall_AudioVideoFlowConfigurationRequested);
            conferenceAVCall.StateChanged += _call_StateChanged;

            Console.WriteLine("");
            Console.WriteLine("Establishing call with audio/video MCU");

            // Call the audio/video MCU.
            // Do this sync just to reduce lines of code for this sample
            conferenceAVCall.EndEstablish(conferenceAVCall.BeginEstablish(null, null, null));

            // We would wait for the flow to be configured for real code.
            _waitForFlowActive.WaitOne();

            Console.WriteLine("");
            Console.WriteLine("Transfering existing call to Audio Video MCU");

            // We have now joined the conference on this conversation.
            // Add our other endpoint to the conference by transfering
            // their call to the conference audio video MCU.
            // Note that the conference audio video MCU is the third-party
            // that all conference attendees communicate with.
            // The MCU "mixes" the participants speech and multiplexes it to
            // all attendees.
            // Make this synchronous just to reduce sample lines of code.
            confSession.AudioVideoMcuSession.EndTransfer(confSession.AudioVideoMcuSession.BeginTransfer(audioVideoCall, null, null, null));

            // Note that the flow becomes active after we transfer the call

            Console.WriteLine("");
            Console.WriteLine("Call has been successfully transfered");

            // set the event for both the caller and the callee,
            // since the callee is automatically transfered
            _waitForConferenceEscalation.Set();
            // END OF MODIFIED CODE.
        }