Lync Development: Accessing the inner endpoint

Although the title sounds very philosophical, I’m not going to talk in this post about an inward journey of discovery for your application endpoints. Instead, I want to talk about a way to access some parts of the signaling layer – the lower-level part of UCMA that allows you to work directly with SIP messages – from the collaboration layer, where most UCMA development takes place.

Recently I’ve gotten a lot of questions about how you can make UCMA do very specific things with SIP messages, like changing the way the SDP media offers are constructed. In many cases, the answer is, unfortunately, that you can’t have your cake and eat it too: if you want to take advantage of the relative simplicity of the collaboration layer, with high-level classes like AudioVideoCall, ConferenceSession, and RemotePresenceView, rather than building SIP messages from scratch, then you have to give up some control over what goes into the SIP messages that get generated. But there are a few places where you can have a little bit of extra control without giving up the collaboration layer completely. One of those is the various Options classes, where you can add extra SIP headers to many types of outgoing messages.

Another one that many people are unaware of is the InnerEndpoint property on the ApplicationEndpoint and UserEndpoint classes. This is a sort of secret trap-door into the signaling layer. It gives you access to the counterpart of UserEndpoint or ApplicationEndpoint in the Microsoft.Rtc.Signaling namespace: RealTimeEndpoint. Using RealTimeEndpoint, you can create and handle SIP dialogs at a much lower level than is possible with the collaboration layer.

For example, you can do something like this to send a SIP INVITE with your own, customized SDP body:

SignalingSession session = new SignalingSession(_endpoint.InnerEndpoint,
    new RealTimeAddress("sip:mgreenlee@claritycontest.com"));
session.OfferAnswerNegotiation = _customOfferAnswer;

try
{
    session.BeginEstablish(establishAsyncResult =>
    {
        try
        {
            session.EndEstablish(establishAsyncResult);
        }
        catch (RealTimeException ex)
        {
            Console.WriteLine(ex);
        }
    },
    null);
}
catch (InvalidOperationException ex)
{
    Console.WriteLine(ex);
}

In this example, _customOfferAnswer would contain an instance of a class that implements IOfferAnswer, to define how the media negotiation should be handled. I’ll talk more about IOfferAnswer and how to implement it in a future blog post, but the point is that you can use the classes in the Collaboration namespace to handle most functions of your application while still falling back on the Signaling namespace for more detailed work.

You can also hook up an event handler to handle incoming SIP messages:

_userEndpoint.InnerEndpoint.SessionReceived += OnInnerEndpointSessionReceived;

In any case, it’s good to be aware of the InnerEndpoint property for cases where you need to drop down to the signaling layer for specific messages.