Using UCMA 3.0 and Lync 2010 for Contextual Communication: How the Applications Interact (Part 2 of 6)

  • Article

Summary:   This article is the second in a series of six articles that describe how to create a Microsoft Unified Communications Managed API (UCMA) 3.0 Core application that sets up a two-way contextual data channel with a Microsoft Lync 2010 application that uses Microsoft Silverlight. The Lync 2010 application runs in the Lync 2010 Conversation Window Extension.

This article describes the interactions between the UCMA 3.0 application and the Lync 2010 application.

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

Published:   February 2011 | Provided by:   Mark Parker and John Clarkson, Microsoft | About the Authors

Contents

  • Interactions Between the UCMA 3.0 and Lync 2010 Applications

  • Part 3

  • Additional Resources

Code Gallery  Download code

This article is the second in a six-part series of articles on using UCMA 3.0 and Lync 2010 for contextual communications.

Interactions Between the UCMA 3.0 and Lync 2010 Applications

The following steps list the activities and interactions that occur when the UCMA 3.0 application and Lync 2010 application run. The first four steps are common to most UCMA 3.0 applications. For more information, see Unified Communications Managed API 3.0 Core SDK Documentation.

Note

All of the code for the UCMA 3.0 and Lync 2010 applications appears in Using UCMA 3.0 and Lync 2010 for Contextual Communication: Code Walkthrough (Part 5 of 6).

  1. The UCMA 3.0 application creates a CollaborationPlatform instance.

  2. The UCMA 3.0 application creates and establishes an endpoint, by using the previously created CollaborationPlatform instance and endpoint settings.

  3. The UCMA 3.0 application creates a Conversation instance.

  4. The UCMA 3.0 application creates an InstantMessagingCall instance.

  5. The UCMA 3.0 application places a call to the remote endpoint, which is the Lync 2010 user’s endpoint, by using the BeginEstablish method on the call. This causes a SIP INVITE message to be sent to the remote participant’s endpoint.

  6. The UCMA 3.0 application creates a ConversationContextChannel instance, passing the conversation and remote endpoint as parameters.

    _channel = new ConversationContextChannel( _conversation, _IMCall.RemoteEndpoint);

  7. The UCMA 3.0 application creates a ConversationContextChannelEstablishOptions instance, and sets the properties to appropriate values. In this application, the ContextualData string signals the Lync 2010 application that the context channel is ready to be used.

    ConversationContextChannelEstablishOptions channelOptions = 
    new ConversationContextChannelEstablishOptions();

channelOptions.ApplicationName = "Blue Yonder Airlines";
channelOptions.ContextualData = "Context channel is open."; 
// The text that appears in the “toast”.
channelOptions.Toast = "Get ready for incoming contextual data.";

  8. The UCMA 3.0 application establishes the ConversationContextChannel instance, by using the BeginEstablish method on the channel instance, and passing the Application ID and the ConversationContextChannelEstablishOptions instance. The Application ID is a globally unique identifier (GUID).

    Note

    To create a GUID for the application, use Guidgen.exe, a Microsoft Visual Studio development system tool. For more information, see Create GUID (guidgen.exe).

    The call to BeginEstablish causes a SIP INVITE message to be sent to the remote endpoint.

    _channel.BeginEstablish(guid, channelOptions, BeginEstablishCB, null);

  9. The Lync 2010 application executes form initialization code in the Lync 2010 application that obtains the conversation that is hosted by the UCMA 3.0 application, by using a call to the GetHostingConversation() method. The Lync 2010 application retrieves the first contextual data by calling the GetApplicationData method. The string returned by this method should be the same string that is in the ContextualData property on the ConversationContextChannelEstablishOptions passed in the call to BeginEstablish. If so, the Lync 2010 application indicates that the context channel is ready for use.

  10. The Lync 2010 user clicks one of the three option buttons appearing in the Lync 2010 application UI, and then clicks the SendData button. This action sends context data from the Lync 2010 application to the UCMA 3.0 application, by using a call to the BeginSendContextData method. For information about how this method is used, see Using UCMA 3.0 and Lync 2010 for Contextual Communication: Creating the Lync Application (Part 4 of 6).

  11. The UCMA 3.0 application raises the DataReceived event, and then the handler registered for this event runs.

    The UCMA 3.0 application registers to receive a notification when the DataReceived event is raised, and defines a handler for it. The next code example shows how to register to receive DataReceived event notifications, and shows the general form of a handler for this event.

    _channel.DataReceived += new EventHandler<ConversationContextChannelDataReceivedEventArgs>(channel_DataReceived);
.
.
.
// Event handler for the DataReceived event on ConversationContextChannel. 
void channel_DataReceived(object sender, ConversationContextChannelDataReceivedEventArgs e)
{
  // Actions to take when the DataReceived event is raised.
}

    The UCMA 3.0 application analyzes the context data sent from the Lync 2010 application to determine the kind of object that the Lync 2010 user chose. After determining which item was selected, the UCMA 3.0 application constructs a string that contains more information about the item, and sends it along the context channel. The UCMA 3.0 application sends this data by using a call to the BeginSendData method.

    Important

    The data sent in a call to BeginSendData must be a Byte array.

    ContentType contentType = 
    new ContentType("text/plain; charset=us-ascii");
_channel.BeginSendData(contentType, data, BeginSendDataCB, null);

    The contentType parameter specifies a MIME protocol Content-Type header that is used for the information in the data parameter. In the previous example, the data in the Byte array is sent as ASCII text.

    The definition of the BeginSendDataCB callback method appears in Using UCMA 3.0 and Lync 2010 for Contextual Communication: Code Walkthrough (Part 5 of 6).

  12. The Lync 2010 application raises the ContextDataReceived event. The handler that was registered for this event begins to run. The next code example shows how to register to receive ContextDataReceived event notifications, and shows the general form of a handler for this event.

    _conversation.ContextDataReceived += OnContextDataReceived;
.
.
.
public void OnContextDataReceived(object sender, ContextEventArgs args)
{
  // Handle ContextDataReceived event. 
}

    The handler for this event retrieves the context data from args parameter, splits it into three pieces, and updates the model, price, and availability text boxes. For more information, see Using UCMA 3.0 and Lync 2010 for Contextual Communication: Creating the Lync Application (Part 4 of 6).

  13. The UCMA 3.0 application begins shutting down. The UCMA 3.0 application first calls the BeginTerminate method on the context channel. At this point, the Lync 2010 Conversation Window Extension (CWE) remains open. To close the CWE, click the Application Name tab, and then at the bottom of the CWE click the close button.

    _channel.BeginTerminate(BeginTerminateCB, null);

    The definition of the BeginTerminateCB callback method appears in Using UCMA 3.0 and Lync 2010 for Contextual Communication: Code Walkthrough (Part 5 of 6).

  14. The UCMA 3.0 application finishes the shutdown process by calling the BeginTerminate, BeginTerminate, and BeginShutdown methods.

Part 3

Using UCMA 3.0 and Lync 2010 for Contextual Communication: Creating the Lync Application (Part 4 of 6)

Additional Resources

For more information, see the following resources:

About the Authors

Mark Parker and John Clarkson are programming writers with the Microsoft Lync product team.