UCMA 3.0 applications without Lync Server

One topic that I wanted to write about in Professional Unified Communications Development that did not make it into the book because of time and space considerations is how to create UCMA applications that don’t depend on Lync Server. Now, at first this may seem like a strange and clueless idea, akin to carrying around a cell phone when you haven’t got any cell phone service. But there are actually some very real reasons why you might like to build a UCMA application without Lync Server.

A simple and common example is interactive voice response (IVR) systems. It’s certainly possible to set these up as trusted endpoints that register with Lync Server. But if you want to route calls directly to an IVR (whether from a SIP trunk, a PBX, an Asterisk server, or something else) where Lync Server is not present, you can do this with a standalone UCMA application. In this post, I’ll show how to set up a simple UCMA application in this way, and how to place test calls to it using CounterPath‘s X-Lite softphone.

Since a standalone UCMA application by definition cannot be a trusted application, there are really no preliminaries here. We don’t need to provision anything using PowerShell, and we can dive straight into the code. If you’ve done some basic UCMA development, you know the drill: create a new C# Console Application or Windows Service project, using the 3.5 version of the .NET Framework, and add a reference to Microsoft.Rtc.Collaboration.dll. (If you are new to UCMA development, check out my book, previous posts on this blog, or MSDN’s Unified Communications Developer Center.)

To begin, let’s look at the code to start up the collaboration platform. It’s not all that different from the code you would use for an ordinary collaboration platform, but there are a couple of notable differences:

ServerPlatformSettings settings = new ServerPlatformSettings(
    "standalone", Dns.GetHostEntry("localhost").HostName,
    5060, string.Empty /* empty string for the GRUU */);

_platform = new CollaborationPlatform(settings);

try
{
    _platform.BeginStartup(ar =>
    {
        try
        {
            _platform.EndStartup(ar);

            Console.WriteLine("Platform started.");

            StartEndpoint();
        }
        catch (RealTimeException ex)
        {
            Console.WriteLine(ex);
        }
    }, null);
}
catch (InvalidOperationException ex)
{
    Console.WriteLine(ex);
}

There are a couple of key differences:

• No TLS certificate is supplied in the platform settings
• There is no GRUU; we’re passing in an empty string for that parameter

Since this is not a trusted application, and it will use ordinary TCP without TLS to communicate, neither of these things is a problem. Also, we’re using 5060 as the listening port, which is a standard port number for SIP connections.

The next step, as usual, is to establish an endpoint. Here’s some example code:

private void StartEndpoint()
{
    // Create a placeholder URI for the endpoint.
    ApplicationEndpointSettings endpointSettings =
        new ApplicationEndpointSettings("sip:default@" +
            Dns.GetHostEntry("localhost").HostName);

    // Make this a default routing endpoint, so that
    // all requests sent to the listening port on this IP,
    // regardless of To URI, will come to the endpoint.
    endpointSettings.IsDefaultRoutingEndpoint = true;

    // Create a new endpoint and register for AV calls.
    _endpoint = new ApplicationEndpoint(_platform, endpointSettings);
    _endpoint.RegisterForIncomingCall<AudioVideoCall>(OnCallReceived);

    try
    {
        _endpoint.BeginEstablish(ar =>
        {
            try
            {
                _endpoint.EndEstablish(ar);

                Console.WriteLine("Endpoint started.");
            }
            catch (RealTimeException ex)
            {
                Console.WriteLine(ex);
            }
        }, null);
    }
    catch (InvalidOperationException ex)
    {
        Console.WriteLine(ex);
    }
}

You’ll notice this code simply makes up a URI for the application. Since it’s not registering with a Lync Front End Server, the endpoint uses the hostname of the server it’s on for the host portion of the SIP URI (after the @ sign) and the user portion doesn’t really matter. It uses the overload of the ApplicationEndpointSettings constructor that does not take a proxy server FQDN and port, because it’s not going to communicate with a proxy server at all.

A very important step here is to set the IsDefaultRoutingEndpoint property on ApplicationEndpointSettings to true. This tells UCMA that all incoming requests that arrive on the listening port of the application should be handled by this endpoint, unless the SIP URI in the To header matches the SIP URI of another one of the application’s endpoints. In this case, there’s only one endpoint, so every single incoming request will go to the same endpoint.

The rest of this is fairly normal: it registers for incoming AV calls and establishes the endpoint.

There’s nothing really different about the rest of the code; all you need to do to start up a UCMA application without Lync Server is in the steps above. To make testing easy, though, here’s the test class I used in its entirety:

class Tester
{
    CollaborationPlatform _platform;
    ApplicationEndpoint _endpoint;

    public void Start()
    {
        ServerPlatformSettings settings = new ServerPlatformSettings(
            "standalone", Dns.GetHostEntry("localhost").HostName,
            5060, string.Empty);

        _platform = new CollaborationPlatform(settings);

        try
        {
            _platform.BeginStartup(ar =>
            {
                try
                {
                    _platform.EndStartup(ar);

                    Console.WriteLine("Platform started.");

                    StartEndpoint();
                }
                catch (RealTimeException ex)
                {
                    Console.WriteLine(ex);
                }
            }, null);
        }
        catch (InvalidOperationException ex)
        {
            Console.WriteLine(ex);
        }
    }

    private void StartEndpoint()
    {
        // Create a placeholder URI for the endpoint.
        ApplicationEndpointSettings endpointSettings =
            new ApplicationEndpointSettings("sip:default@" +
                Dns.GetHostEntry("localhost").HostName);

        // Make this a default routing endpoint, so that
        // all requests sent to the listening port on this IP,
        // regardless of To URI, will come to the endpoint.
        endpointSettings.IsDefaultRoutingEndpoint = true;

        // Create a new endpoint and register for AV calls.
        _endpoint = new ApplicationEndpoint(_platform, endpointSettings);
        _endpoint.RegisterForIncomingCall<AudioVideoCall>(OnCallReceived);

        try
        {
            _endpoint.BeginEstablish(ar =>
            {
                try
                {
                    _endpoint.EndEstablish(ar);

                    Console.WriteLine("Endpoint started.");
                }
                catch (RealTimeException ex)
                {
                    Console.WriteLine(ex);
                }
            }, null);
        }
        catch (InvalidOperationException ex)
        {
            Console.WriteLine(ex);
        }
    }

    void OnCallReceived(object sender, CallReceivedEventArgs<AudioVideoCall> e)
    {
        CallHandler handler = new CallHandler();
        handler.Handle(e.Call);
    }

    public void Stop()
    {
        try
        {
            _endpoint.BeginTerminate(
                ar =>
                {
                    try
                    {
                        _endpoint.EndTerminate(ar);

                        Console.WriteLine("Endpoint terminated.");

                        ShutDownPlatform();
                    }
                    catch (RealTimeException ex)
                    {
                        Console.WriteLine(ex);
                    }
                },
                null);
        }
        catch (InvalidOperationException ex)
        {
            Console.WriteLine(ex);
        }
    }

    private void ShutDownPlatform()
    {
        try
        {
            _platform.BeginShutdown(ar =>
            {
                try
                {
                    _platform.EndShutdown(ar);

                    Console.WriteLine("Platform shut down.");
                }
                catch (RealTimeException ex)
                {
                    Console.WriteLine(ex);
                }
            }, null);
        }
        catch (InvalidOperationException ex)
        {
            Console.WriteLine(ex);
        }
    }
}

public class CallHandler
{
    Player _player;

    public void Handle(AudioVideoCall call)
    {
        call.StateChanged += new EventHandler<CallStateChangedEventArgs>(Call_StateChanged);

        try
        {
            call.BeginAccept(
                ar =>
                {
                    try
                    {
                        call.EndAccept(ar);

                        WmaFileSource source = new WmaFileSource("music.wma");

                        source.EndPrepareSource(source.BeginPrepareSource(MediaSourceOpenMode.Buffered, null, null));

                        _player = new Player();
                        _player.SetSource(source);

                        _player.AttachFlow(call.Flow);
                        _player.Start();
                    }
                    catch (RealTimeException ex)
                    {
                        Console.WriteLine(ex);
                    }
                },
                null);
        }
        catch (InvalidOperationException ex)
        {
            Console.WriteLine(ex);
        }
    }

    void Call_StateChanged(object sender, CallStateChangedEventArgs e)
    {
        Console.WriteLine("State changed from {0} to {1}", e.PreviousState, e.State);

        if (e.State == CallState.Terminated)
        {
            _player.Source.Close();
            _player = null;
        }
    }
}

You’ll also need to put a WMA file named music.wma in your application’s working directory (you can find one in the sample applications for the UCMA SDK), and something like the following in your application startup code to create an instance of the tester and get it rolling:

Tester t = new Tester();
t.Start();
Console.ReadLine();
t.Stop();
Console.ReadLine();

No need to configure anything or ensure that you have connectivity to Lync Server; just go ahead and start your application. The only thing you’ll need to watch out for is that the listening port (in this case 5060) is not being blocked by a firewall or being used by another application. If you get an error message on startup saying “Failed to listen on any address and port supplied,” then try changing your listening port to something else instead of 5060.

Now, there’s not much use in having a UCMA application sitting around unless you can place calls to it, and this is where X-Lite comes in. X-Lite is a free SIP softphone from a company called CounterPath (they also have more full-featured versions for sale). Using X-Lite, which you can download at http://www.counterpath.com/x-lite.html, you can place calls directly to your UCMA application from the same computer.

Once you’ve installed X-Lite, there’s a bit of configuration to do before you can call your application. Note that the steps below are based on X-Lite 4.1, build 63214, so if you have an older or newer version you may need to do something a bit different. Also, I want to give credit here to Marshall Harrison, whose post on doing something similar to this with X-Lite and Speech Server helped get me started with this technique.

First, go to the Softphone menu and select Account Settings, as shown below.

In the Account tab in the window that comes up, enter a name for your account in the Account name box and a user ID (which can be anything) in the User ID box. In the Domain box, enter the IP address of the computer you are running X-Lite and your UCMA application on. Leave Password blank, and uncheck the box that says Register with domain and receive calls. Make sure the Domain radio button is selected under Send outbound via. That’s all for this tab.

Switch to the Transport tab. There’s only one option here, Signaling transport, which you need to change to TCP.

Last but not least, go to the Advanced tab, and select Send outgoing request directly to target.

At this point, you are ready to go. In the dialing box in the X-Lite main window, enter a SIP URI like sip:whatever@192.168.0.1:5060, substituting your own IP address instead of 192.168.0.1 and your own listening port from the UCMA application instead of 5060. The user portion of the URI can be anything you want, since the call will go to your application regardless.

Click the Call button, and X-Lite will call your application. If all goes well, you will shortly hear music, and see something like the following:

Congratulations! You’ve created your first standalone UCMA application.

If you have any trouble getting this to work, feel free to drop me an email and I’ll do my best to help.