Using VoiceXML in a UCMA 3.0 Application: UCMA Application (Part 3 of 4)

Article
01/20/2015

Summary: The Microsoft Unified Communications Managed API (UCMA) 3.0 Core SDK can be used to write interactive voice response (IVR) applications that work with VoiceXML documents. This article describes the Microsoft Unified Communications Managed API (UCMA) 3.0 application that interprets the VoiceXML document.

Applies to: Microsoft Unified Communications Managed API (UCMA) 3.0 Core SDK

Published: June 2011 | Provided by: Mark Parker, Microsoft | About the Author

Contents

Starting the VoiceXML Application
Retrieving Session State from the VoiceXML Document
Shutdown Process
Part 4
Additional Resources

Download code

See video

This is the third in a series of four articles about how to use VoiceXML in a UCMA 3.0 application.

Starting the VoiceXML Application

Note

All of the code for this series of articles appears in Using VoiceXML in a UCMA 3.0 Application: Code Listing and Conclusion (Part 4 of 4).

The following example shows the declarations of the global variables that are mentioned elsewhere in this topic.

private UCMASampleHelper _helper;
private UserEndpoint _userEndpoint;
private CollaborationPlatform _collabPlatform;
private AudioVideoCall _audioVideoCall;
private AudioVideoFlow _audioVideoFlow;

// The conversation.
private Conversation _conversation;
 
// The VoiceXML Browser and the location of the VoiceXML start page.
private Microsoft.Rtc.Collaboration.AudioVideo.VoiceXml.Browser _voiceXmlBrowser;
private String startPageURL = @"https://localhost/VoiceXmlTime/GetCityTime.vxml";

Create and establish the UserEndpoint instance that is used by the UCMA 3.0 application, as shown in the following example.
```
_helper = new UCMASampleHelper();
_userEndpoint = _helper.CreateEstablishedUserEndpoint("VoiceXML Sample User");
```
Register a delegate for an incoming call.

This action is performed by calling the RegisterForIncomingCall<TCall> method on the endpoint.
```
_userEndpoint.RegisterForIncomingCall<AudioVideoCall>(inboundAVCall_CallReceived);
```
Create a Browser instance. This step is performed in the InitializeVoiceXmlBrowser method.
```
_voiceXmlBrowser = new Microsoft.Rtc.Collaboration.AudioVideo.VoiceXml.Browser();
```

Register for notification of the Disconnecting, Disconnected, and SessionCompleted events on the Browser instance. This step is performed in the InitializeVoiceXmlBrowser method.

_voiceXmlBrowser.Disconnecting
       += new EventHandler<DisconnectingEventArgs>(HandleDisconnecting);
_voiceXmlBrowser.Disconnected
       += new EventHandler<DisconnectedEventArgs>(HandleDisconnected);
_voiceXmlBrowser.SessionCompleted
       += new EventHandler<SessionCompletedEventArgs>(HandleSessionCompleted);

Note

The Disconnecting event and the Disconnected event are not raised under typical circumstances. They are raised when the call ends unexpectedly.

When an incoming call is received, the delegate that was registered in step 2 should perform the following actions.

Retrieve the call (an AudioVideoCall instance) from the CallReceivedEventArgs<TCall> parameter.
Create a Conversation instance, passing the endpoint of the UCMA 3.0 application as the parameter to the Conversation constructor.
Accept the incoming call by using the BeginAccept method on the call.

The following example shows the delegate that is called when an incoming call arrives.

private void inboundAVCall_CallReceived(object sender, CallReceivedEventArgs<AudioVideoCall> e)
{
  _waitForCallReceived.Set();
  _audioVideoCall = e.Call;

  _audioVideoCall.AudioVideoFlowConfigurationRequested += this.audioVideoCall_FlowConfigurationRequested;
  _audioVideoCall.StateChanged += new EventHandler<CallStateChangedEventArgs>(audioVideoCall_StateChanged);

  // Create a new conversation instance.
  _conversation = new Conversation(_userEndpoint);
  // Accept the call.
  _audioVideoCall.BeginAccept(CallAcceptCB, _audioVideoCall);
  _audioVideoFlow = _audioVideoCall.Flow;
}

Associate the Browser instance with the AudioVideoCall instance by calling the SetAudioVideoCall method.
```
_voiceXmlBrowser.SetAudioVideoCall(_audioVideoCall);
```
Start the Browser instance by a call to the RunAsync method.
```
Uri startPageURI = new Uri(startPageURL);
_voiceXmlBrowser.RunAsync(startPageURI, null);
```
The first argument in the RunAsync method is the URI of the VoiceXML document (or the start page if there are multiple VoiceXML documents).

At this point, the IVR application represented by the VoiceXML document begins to run.

Retrieving Session State from the VoiceXML Document

When the VoiceXML document returns control to the UCMA 3.0 application, the SessionCompleted event on the Browser class is raised. An application that registers to receive notification of the SessionCompleted event can retrieve values in the Namelist attribute of the exit element in the VoiceXML document. The exit element of the VoiceXML document in this series of articles is <exit namelist="CityOffset CityOffset$.utterance CityOffset$.confidence timeAtRequestedCity"/> lists four names: CityOffset, CityOffset$.utterance, CityOffset$.confidence, and timeAtRequestedCity.

Each of these names is a key in a list of key-value pairs. For example, the expression Namelist[″CityList″] uses the CityOffset key to get the value associated with this key.

The following example shows the handler for the SessionCompleted event on the Browser instance.

private void HandleSessionCompleted(object sender, SessionCompletedEventArgs e)
{
  _waitForSessionCompleted.Set();
  VoiceXmlResult result = e.Result;
  String cityOffset = result.Namelist["CityOffset"].ToString();
  String utterance = result.Namelist["CityOffset$.utterance"].ToString();
  String confidence = result.Namelist["CityOffset$.confidence"].ToString();
  String requestedTime = result.Namelist["timeAtRequestedCity"].ToString();
  Console.WriteLine("Returned semantic result: " + cityOffset);
  Console.WriteLine("Utterance: " + utterance);
  Console.WriteLine("Confidence: " + confidence);
  Console.WriteLine("Requested time: " + requestedTime);
}

Shutdown Process

After the HandleSessionCompleted delegate returns, the UCMA 3.0 application begins its shutdown process.

The call is terminated by using the BeginTerminate method on the AudioVideoCall instance.
The conversation is terminated by using the BeginTerminate method on the Conversation instance.
The platform is shut down by using the BeginShutdown method on the CollaborationPlatform instance.

Part 4

Using VoiceXML in a UCMA 3.0 Application: Code Listing and Conclusion (Part 4 of 4)

Additional Resources

For more information, see the following resources:

About the Author

Mark Parker is a programming writer at Microsoft whose current responsibility is the UCMA SDK documentation. Mark previously worked on the Microsoft Speech Server 2007 documentation.