With this post, we would like to provide you an overview of how one could write a simple .NET based application to perform point-to-point Instant Messaging session (IM) using the Unified Client Communications API (UCC API) which can be downloaded from here.

The UCC SDK enables one to add features like Presence, Instant Messaging as well as Voice, Video and others offered by the Unified Communications Client Platform to applications (managed or unmanaged).

For an SDK overview and how to use the API in general, please refer to the MSDN library focused on UCC 1.0 SDK section within the Communications Server 2007 of the Office System.

A brief architecture overview follows.

The diagram above shows some of the various components involved within the UCC API SDK. The UCC SDK includes various communication modalities, conferencing capabilities, a presence infrastructure built on top of a signaling stack and a media stack. The signaling and media stack combined supports various different protocols including (but not limited to) the following: SIP, RTP, RTCP, STUN/TURN/ICE (for NAT/FW traversal), SRTP (for encryption), CCCP (for conferencing) and ECMA-based CSTA for Remote Call Control.

As before mentioned, this blog entry will primarily focus on the instant messaging APIs. Future posts may focus on other aspects of the API based on demand (please drop a comment if you would like us to focus on other areas in the future).

With that, let us dive into what one needs to do to integrate UCC API into their product to offer basic point-to-point Instant Messaging (IM) capabilities.

First, one will have to ensure that a manifest is included in the application that contains UCCAPI as a dependency (see sample below).

 

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>

<assembly xmlns="urn:schemas-microsoft-com:asm.v1" manifestVersion="1.0">

    <assemblyIdentity

        version="1.1.0.0"

        processorArchitecture="x86"

        name="IMVoIPSample.exe"

        type="win32"

    />

    <dependency>

        <dependentAssembly>

                   <assemblyIdentity

                           version="2.0.0.0"

                           processorArchitecture="x86"

                           name="UCCAPI"

                             type="win32"

                    />

        </dependentAssembly>

    </dependency>

</assembly>

 

 

Next, the inter-op COM dependency needs to be added as a reference to the application: Microsoft.Office.Interop.UccApi.dll. The following DLLs are also needed to run the application: UccApi.dll and RTMPLTFM.dll.

The following will give an overview of what an application needs to prior to initiating an IM session.

An application should first initialize the platform as shown below. The following piece of code performs the following functions:

-          Initializes the platform

-          Connects to the SIP outbound proxy (specified as the server address below) using TLS

-          Sets NTLM as the authentication scheme with specified username and password (credentials)

-          Enables the endpoint: at which point the application sends out a SIP REGISTER request to the outbound proxy which then routes the SIP REGISTER request (RFC 3261, RFC 3327 and a few others) to the SIP registrar within OCS (Office Communications Server 2007). The UCCP stack internally handles SIP 401/407 SIP challenge responses with the supplied credentials.

-          In the event that a challenge response fails again, an event is raised to the events interface as will be later shown.

 

NOTE: What is not shown is the setting the application up to receive the events as shown in the comments below.

//Create the singleton platform object

IUccPlatform platform = new UccPlatform();

 

//Advise for platform events

//Initialize the platform with application name

platform.Initialize(“SampleApp", null);

 

//Advise for platform events

//Create an endpoint object from the platform object

IUccEndpoint endpoint = platform.CreateEndpoint(userURI, null, null);

 

//Advise for endpoint objects

//QI server IUccServerSignalingSettings interface from the endpoint

IUccServerSignalingSettings serverSignalingSettings = (IUccServerSignalingSettings)endpoint;

 

//Set servername, transport, authentication mode and login credentials

serverSignalingSettings.Server = serverAddress;

serverSignalingSettings.TransportMode = UCC_TRANSPORT_MODE.UCCTM_TLS;

serverSignalingSettings.AllowedAuthenticationModes = (int)UCC_AUTHENTICATION_MODES.UCCAM_NTLM;

 

IUccCredential credential = serverSignalingSettings.CredentialCache.CreateCredential(username, passwd, domain);

serverSignalingSettings.CredentialCache.SetCredential("*", credential);

 

//Enable the endpoint in order to register with server

endpoint.Enable();

 

Next, handle the sign-in completion events as follows.

void _IUccEndpointEvents.OnEnable(IUccEndpoint pEventSource,IUccOperationProgressEvent pEventData){

  if (pEventData.IsComplete) {

    if (pEventData.StatusCode >= 0)

    // Sign in succeeded.

          sessionManager = (IUccSessionManager) endpoint;

    else

    // Sign in failed. Clean up and retry.

          endpoint = null;

  }      

}

 

Next, the application can send an IM out by creating an IM session and adding participants to it. An IM session sets up a SIP session-mode IM session using an SIP INVITE dialog and uses MESSAGE requests within the dialog to transfer Instant Messages.

The following piece of code does the following:

-          Obtains the session manager from the endpoint: the session manager is a factory for creating session objects that are responsible for maintaining run-time state information for different kinds of sessions, including Instant Messaging, Audio and Video and others.

-          Creates a new Instant Messaging (SIP) session

-          Adds a remote participant

NOTE: What is not shown is the setting the application up to receive the events as shown in the comments below.

//QI the IUccSessionManager interfaces from endpoint object

IUccSessionManager sessionManager = (IUccSessionManager)endpoint;

 

//Advise for _IUccSessionManagerEvents to receive notifications about incoming sessions

 

//Create a session of type Instant messaging

IUccSession session = (IUccInstantMessagingSession) sessionManager.CreateSession(UCC_SESSION_TYPE.UCCST_INSTANT_MESSAGING, null);

 

// Advise for _IUccSessionEvents, _IUccInstantMessagingSessionEvents and

// _IUccSessionParticipantCollectionEvents

IUccParticipant participant = session.CreateParticipant(“alice@constoso.com”,0)

 

// Advise for _IUccSessionParticipantEvents and

// _IUccInstantMessagingSessionParticipantEvents

session.AddParticipnat(participant,0);

 

Once the application registers for events, an application may receive Instant Messages as follows.

void _IUccSessionManagerEvents.OnIncomingSession(IUccEndpoint eventSource,

                         IUccIncomingSessionEvent eventData)      

{

  this.session = eventData.session;

  // Advise for _IUccSessionEvents, _IUccInstantMessagingSessionEvents and

  // _IUccSessionParticipantCollectionEvents

  eventData.accept();

  // If user wants to reject,

  // eventData.Reject(UCC_REQUEST_REJECT_REASON.UCCRRR_DECLINE);

}

 

Sending a message is quite straightforward as shown below.

// QI the IUccInstantMessagingSession

IUccInstantMessagingSession imSession = session as IUccInstantMessagingSession;

 

// Send message

String message = “Hello world!”;

imSession.SendMessage(message,null);

 

And there you have it, a basic point-to-point IM example using the Unified Communication Client API ver 1.0!

Srivatsa Srinivasan
Program Manager


Published Tuesday, May 13, 2008 9:07 AM by octeam
Filed Under: IM/Presence