advanced ucma 3.0 development -...

Hands-On Lab

Advanced UCMA 3.0 Development

Lab version: 1.0

Last updated: 12/17/2010

CONTENTS

OVERVIEW ............................................................................................................................................. 3 System Requirements 3

EXERCISE 1: BACK-TO-BACK CALL FUNCTIONALITY ...................................................................... 4 Task 1 – Open the Visual Studio Solution ......................................................................................... 4

Task 2 – Create and Establish a Back-to-Back Call ............................................................................. 4

EXERCISE 2: MANUAL AUDIO ROUTES .............................................................................................. 6 Task 1 – Open the Visual Studio Solution ......................................................................................... 6

Task 2 – Register for an Incoming Call on the Application Endpoint .................................................. 7

EXERCISE 3: APPLICATION ENDPOINT DRAINING .......................................................................... 12 Task 1 – Open the Visual Studio Solution ....................................................................................... 12

Task 2 – Draining an Application Endpoint ..................................................................................... 12

SUMMARY ............................................................................................................................................ 15

Overview

Lab Time: 45 Minutes

Lab Folder: C:\%UC14TrainingKit%\Labs\8\Source\Before

The After folder contains the completed lab exercises.

Lab Overview: The Unified Communications Managed API 3.0 SDK provides a managed API for

developing server-side communications solutions for Microsoft Lync Server 2010 such as personal virtual

assistants, automatic call distributors, and communications-enabled business processes.

This lab introduces new and advanced UCMA 3.0 development concepts such as back-to-back calling,

audio routes, and application endpoint draining.

The lab solution you will build will use the UCMA 3.0 SDK to demonstrate the following.

Establishing a back-to-back call between two users.

Using audio routes to maintain fine-grained control over the experience of callers in a

conference.

Using application endpoint draining to gracefully shutdown an application endpoint.

System Requirements

You must have the following items to complete this lab:

Microsoft Visual Studio 2010

Unified Communications Managed API 3.0 SDK

A provisioned UCMA 3.0 application

◦ Please refer to the Lab 6 - Introduction to UCMA 3.0 to learn how to create and

provision a UCMA 3.0 application.

Exercise 1: Back-to-Back Call

Functionality

Task 1 – Open the Visual Studio Solution

In this task, you will open the project and configure it to run with your parameter values.

1. Navigate to Start >> All Programs >> Microsoft Visual Studio 2010.

2. Click on the Microsoft Visual Studio 2010 icon to start Visual Studio 2010.

3. Select File >> Open Project.

4. Navigate to the folder C:\%UC14TrainingKit%\Labs\8\Source\Before.

5. Open the AdvancedUCMA solution.

6. In Solution Explorer, right-click the BackToBack project and select Set as StartUp Project.

7. In Solution Explorer, open the App.config file.

8. Change the value of ApplicationId to the application id of your provisioned UCMA 3.0

application, e.g. urn:application:LabApp10600.

9. Change the value of ApplicationName to the application name of your provisioned UCMA

3.0 application, e.g. LabApp10600.

10. Change the value of TrustedContactUri to SIP URI of the contact associated with your

provisioned UCMA 3.0 application, e.g. sip:[email protected].

11. Change the value of SecondaryLabUserId with the SIP URI of your secondary lab user.

12. Select View >> Task List and select Comments from the menu.

Task 2 – Create and Establish a Back-to-Back Call

In this task, you will create and establish a back-to-back call between your primary and secondary lab

user ids.

Back-to-Back allows a UCMA application to maintain control over a communication session by dividing it

into two legs and acting as a proxy between the two participating endpoints. From the perspective of

each endpoint, it is in a call with the UCMA application. However, audio is sent directly between the

two endpoints, allowing the application to maintain control over the call and provide additional services.

1. In the Task List, navigate to TODO: 8.1.1.

2. Add the following code after the TODO: 8.1.1 comment. This creates an instance of

BackToBackCallSettings for the incoming call to the application endpoint.

C#

sip:[email protected]

var incomingCallSettings = new BackToBackCallSettings(e.Call);

3. Navigate to TODO: 8.1.2.

4. Add the following code after the TODO: 8.1.2 comment. This create a new outgoing call on

the application endpoint.

C#

var outgoingCallConversation = new Conversation(_applicationEndpoint);

var outgoingCall = new AudioVideoCall(outgoingCallConversation);


6. Add the following code after the TODO: 8.1.3 comment. This creates an instance of

BackToBackCallSettings for the outgoing call to the secondary lab user.

C#

var outgoingCallSettings = new BackToBackCallSettings(outgoingCall,

_secondaryLabUserId);


8. Add the following code after the TODO: 8.1.4 comment. This creates a new BackToBackCall

and pass in the incoming and outgoing BackToBackCallSettings.

C#

backToBackCall = new BackToBackCall(incomingCallSettings,

outgoingCallSettings);


10. Add the following code after the TODO: 8.1.5 comment. This establishes the back-to-back

call between the primary and secondary lab users.

C#

Console.WriteLine("Established back-to-back call.");

backToBackCall.EndEstablish(result);

11. Go to Debug >> Start Without Debugging or use the shortcut key [CTRL]+[F5] to start the

application. The platform will start up, establish the application endpoint, register for an

incoming call, and notify the user that it is ready and waiting for an incoming call.

12. Switch to Microsoft Lync and locate the contact for your provisioned lab contact, e.g.

[email protected].

13. Place an audio call to the contact. The application begins establishing the back-to-back call

to the secondary lab user.

14. Switch to the secondary lab user’s session. The call appears to be coming from the UCMA

application.

mailto:[email protected]

15. Accept the call. The back-to-back call is established between the primary and secondary lab

users. Notice that the identity of the primary lab user is masked from the secondary lab

user.

16. Switch to the primary lab user’s session. The identity of the secondary lab user is also

masked from the primary lab user.

17. Switch to the console application.

18. Press Enter to shut down the console application.

Exercise 2: Manual Audio Routes






4. Navigate to the folder C:\%UC14TrainingKit%\Labs\8\Before.


6. In Solution Explorer, right-click the AudioRoutes project and select Set as StartUp Project.










Task 2 – Register for an Incoming Call on the Application Endpoint

The UCMA 3.0 SDK provides developers with fine-grained control over the audio routes in an

Audio/Video call. This enables functionality such as Supervisor Whisper which allows a supervisor to talk

to a customer service agent who is on a call with a customer, without the customer hearing the

supervisor.

In this task, you will create a hold music player and attach it to the flow of the audio/video call, invite

the primary and secondary lab users to a conference, remove the conference participants from the

default audio route to place them on hold, and finally add the conference participants back to the

default audio route to take them off hold.


2. Add the following code after the TODO: 8.2.1 comment. This defines a source for the hold

music and creates an instance of the Player object to act as the hold music player. It also

sets the source of the hold music player and sets the player mode to Automatic so that the

hold music will loop continuously.

C#

_holdMusicSource.EndPrepareSource(prepareSourceResult);

Console.WriteLine("Prepared hold music source.");

// Create a new Player object using the WMA file source.

_holdMusicPlayer = new Player();

_holdMusicPlayer.SetSource(_holdMusicSource);

// Set the mode to automatic so that the music will loop.

_holdMusicPlayer.SetMode(PlayerMode.Automatic);

Console.WriteLine("Prepared hold music player.");


4. Add the following code after the TODO: 8.2.2 comment. This creates a new conversation on

the application endpoint and joins the ad hoc conference. Every conversation has a

ConferenceSession to enable the application to join a conference and perform other

operations related to an activated conference. The application joins the conference as a


trusted participant, meaning that other participants will not see it in the call. An instance of

ConferenceJoinOptions with JoinMode set to JoinMode.TrustedParticipant specifies that

the participant is joining the conference as a trusted participant.

C#

conversation.ConferenceSession.EndJoin(result);

Console.WriteLine("Joined the conference.");

_initialAVCall = new AudioVideoCall(conversation);


6. Add the following code after the TODO: 8.2.3 comment. With the ad hoc conference

established, invite the primary and secondary lab users to the conference. Send a

conference invitation to the primary lab user. Only send a conference invitation to the

secondary lab user when the primary lab user has accepted the invitation.

C#

confInvitePrimaryLabUser.EndDeliver(deliverResult);

Console.WriteLine("Primary lab user accepted.");


8. Add the following code after the TODO: 8.2.4 comment. Once both the primary and

secondary lab users have joined the conference, the console application prompts us to press

Enter to put them both on hold. This code attaches the hold music player to the flow of the

audio/video call and starts it. Get a reference to the AudioVideoMcuSession of the call and

iterate through each conference participant.

C#

_holdMusicPlayer.AttachFlow(_initialAVCall.Flow);

_holdMusicPlayer.Start();


10. Add the following code after the TODO: 8.2.5 comment. This removes each participant

from the default MCU routing. Removing a participant from the default MCU routing

indicates that there are no longer any audio routes that begin or terminate at that

participant’s endpoint. Nobody can hear the participant and the participant can’t hear

anything. It is up to the application to now manually add the audio routes to and from that

participant’s endpoint as needed.

C#

avMcu.EndRemoveFromDefaultRouting(removeResult);

Console.WriteLine("Removed participant {0} from default MCU routing.",

participantEndpoint.Participant.Uri);


12. Add the following code after the TODO: 8.2.6 comment. This creates a new

OutgoingAudioRoute to the participant’s endpoint. Set the route’s Operation property to

RouteUpdateOperation.Add to indicate that a new route is being added to the

AudioVideoMcuRouting for the call.

C#

OutgoingAudioRoute outgoingRoute = null;

outgoingRoute = new OutgoingAudioRoute(participantEndpoint);

outgoingRoute.Operation = RouteUpdateOperation.Add;

outgoingRoutes.Add(outgoingRoute);

Console.WriteLine("Adding an outgoing audio route for participant {0}.",



14. Add the following code after the TODO: 8.2.7 comment. This calls

BeginUpdateAudioVideoRoutes to begin the route update operation.

BeginUpdateAudioVideoRoutes accepts a list of outgoing and incoming audio routes.

Multiple outgoing and incoming routes can be added or removed at the same time. It is

recommended that route update operations be processed in bulk, e.g. update outgoing and

incoming audio routes to multiple endpoints in the same call to

BeginUpdateAudioVideoRoutes.

C#

_initialAVCall.AudioVideoMcuRouting.BeginUpdateAudioRoutes(

outgoingRoutes: outgoingRoutes,

incomingRoutes: null,

userCallback: result =>

{

try

{

var avMcuRouting = result.AsyncState as AudioVideoMcuRouting;

avMcuRouting.EndUpdateAudioRoutes(result);

}

catch (RealTimeException rtExAudioRoutes)

{

throw rtExAudioRoutes;

}

},

state: _initialAVCall.AudioVideoMcuRouting);


16. Add the following code after the TODO: 8.2.8 comment. Instead of stopping the hold music

player, we can just remove all the audio routes from the application to the conference

participant endpoints. Get a reference to the AudioVideoMcuSession of the call and iterate

through each conference participant. Create a route update operation to remove the audio

routes.

C#

foreach (var participantEndpoint in

avMcu.GetRemoteParticipantEndpoints())

{

OutgoingAudioRoute outgoingRoute = null;

outgoingRoute = new OutgoingAudioRoute(participantEndpoint);

outgoingRoute.Operation = RouteUpdateOperation.Remove;

outgoingRoutes.Add(outgoingRoute);

}

17. Add the following code after the TODO: 8.2.9 comment. This adds each participant back to

the default routing of the AudioVideoMcuSession. The participants can now resume the

conference.

C#

avMcu.EndAddToDefaultRouting(addResult);

Console.WriteLine("Added participant {0} to default MCU routing.",



application. The application starts the collaboration platform and establishes the

application endpoint. The application then sets up and prepares the hold music player and

invites the primary lab user to the conference.

19. Accept the conference invitation. The primary lab user joins the conference. The

application then invites the secondary lab user to the conference. Note: After accepting the

incoming call, press the microphone icon in the conversation window to mute the call and

prevent audio feedback.

20. Switch to the secondary lab user’s session.

21. Accept the conference invitation. The secondary lab user joins the conference. Note that

the conference appears to only have two participants. The application is not visible in the

People list since it joined the conference as a trusted participant. Note: After accepting the

incoming call, press the microphone icon in the conversation window to mute the call and

prevent audio feedback.

22. Switch to the primary lab user’s session.

23. Press Enter to put the conference participants on hold. The hold music player starts. Both

participants can now hear the hold music. The participants cannot hear each other.

24. Press Enter to take the conference participants off hold. The hold music player stops. The

participants can resume the conference.

25. Press Enter to terminate the application endpoint and shutdown the collaboration platform.

Exercise 3: Application Endpoint

Draining






4. Navigate to the folder C:\%UC14TrainingKit%\Labs\8\Before.


6. In Solution Explorer, right-click the Draining project and select Set as StartUp Project.










Task 2 – Draining an Application Endpoint

In previous versions of UCMA, once an application endpoint is terminated, all current calls in place with

the endpoint are also immediately terminated. Gracefully shutting down a UCMA application thus

involved writing code to wait for all active calls to terminate, while at the same time forwarding any

incoming calls to another application endpoint or gracefully declining them.

The UCMA 3.0 SDK introduces the concept of draining, allowing an application endpoint to shutdown

gracefully after all active calls have terminated. The endpoint does not accept any new calls, but waits

until all calls are terminated before shutting down without affecting any calls currently in progress.


2. Add the following code after the TODO: 8.3.1 comment. This drains the application

endpoint before terminating it.

C#


DrainEndpoint();


4. Add the following code after the TODO: 8.3.2 comment. Before draining the application

endpoint, configure its draining sessions by calling ApplyDrainingSettings. Passing in

DeclineNewIncomingConversations indicates that the application endpoint will decline

incoming calls while draining. Begin draining the application endpoint by calling

BeginDraining.

C#

_applicationEndpoint.BeginDrain(userCallback: DrainingCompleted, state:

null);


6. Add the following code after the TODO: 8.3.3 comment. The application endpoint is ready

to be terminated once it has completed draining.

C#

_applicationEndpoint.EndDrain(result);

Console.WriteLine("Draining completed.");


8. Add the following code after the TODO: 8.3.4 comment. This terminates the application

endpoint.

C#

Console.WriteLine("\nTerminating the endpoint.");

_applicationEndpoint.BeginTerminate(userCallback:

TerminateEndpointCompleted, state: null);


application. The application starts the collaboration platform and establishes the

application endpoint.


[email protected].

11. Place an audio call to the contact. The application endpoint accepts and establishes the

incoming call.

12. Switch to the console application.

13. Press Enter to begin draining the application endpoint. The state of the application

endpoint changes from Established to Draining. Note that the current call is unaffected.

14. Switch to the secondary lab user’s session.


[email protected].

16. Place an audio call to the contact. The application endpoint declines the call. The

AudioVideoCall_Received event never fires on the application endpoint since it has begun

draining.

17. Switch back to the primary user’s session.

18. Hang up the call. All active calls with the application endpoint have now terminated.

19. The application endpoint completes draining.

20. Press Enter. The application endpoint is terminated and the collaboration platform is shut

down.

Summary

In this lab, you learned how to create and establish a back-to-back call between two participants while

masking their identity from each other. You also saw how UCMA 3.0 allows you to manually create

audio routes between participants in a conference to give you fine-grained control over the participants’

experience. Finally, you saw how to use draining to gracefully shutdown an application endpoint.

advanced ucma 3.0 development -...

Documents