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

Summary:   This article is the fourth 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 contains details about 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

• Lync Application Overview

• Lync Application Requirements

• Relevant Lync API Members

• Lync Application Run-Time Tasks

• Part 5

• Additional Resources

  Download code

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

• Using UCMA 3.0 and Lync 2010 for Contextual Communication: Scenario Overview (Part 1 of 6)

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

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

• Using UCMA 3.0 and Lync 2010 for Contextual Communication: Code Walkthrough (Part 5 of 6)

• Using UCMA 3.0 and Lync 2010 for Contextual Communication: Summary (Part 6 of 6)

Lync Application Overview

The Lync 2010 application is a Lync 2010 Silverlight application that is embedded in a web page. The scenario that appears in Using UCMA 3.0 and Lync 2010 for Contextual Communication: Scenario Overview (Part 1 of 6) will work equally well with a Microsoft Windows Presentation Foundation (WPF) Lync Control application. Microsoft Unified Communications Managed API (UCMA) 3.0 must start the session. The UCMA 3.0 application sends a conversation invitation to the user signed in to Lync 2010 on a separate computer, and then the Lync 2010 application opens in the Lync 2010 Conversation Window Extension.

Note

This article does not describe the steps that you must follow to embed a Lync 2010 Silverlight application in a web page. For more information, see Walkthrough: Write a Silverlight Application for the Conversation Window Extension.

Figure 1. Silverlight application UI

Lync Application Requirements

To develop the Lync 2010 side of the application you will need Microsoft Visual Studio development system and Microsoft Lync 2010 SDK. To develop a Lync 2010 Silverlight application you also need the Microsoft Silverlight SDK and runtime. For information about prerequisites, see Walkthrough: Presence Hello World.

To deploy the Lync 2010 application, you must register it on the Lync 2010 computers that will communicate with the UCMA 3.0 computer. For information about registering Lync 2010 applications for contextual communications, see Registering Contextual Conversation Packages. Although the Lync 2010 application runs only on the Lync 2010 computer but not the computer that is running the UCMA 3.0 application, the Application ID GUID should be registered on the Lync 2010 computer and must be known to the UCMA 3.0 computer.

Relevant Lync API Members

Important Lync 2010 classes and members that relate to this article appear in the following table.

Member	Description
Conversation class	Instances of the Conversation class are obtained from the conversation manager. The Conversation class exposes methods that you can use to get and set conversation properties, merge one active conversation with other active conversations, add or remove collaboration modalities, and end the active conversation represented by a Conversation instance. When a Lync 2010 application opens in the Conversation Window Extension (CWE), the Conversation object is created before the application starts to run. This means that events such as the ParticipantAdded and StateChanged events, that usually are raised when a conversation is created, might not be detected. What exactly is missed depends on the order in which the CWE is created, the application starts to run, and the GetHostingConversation method in the Silverlight version of the LyncClient class is called.
InitialContextReceived event	This event is raised when the initial context data is received in a conversation.
InitialContextSent event	This event is raised when the initial context data is sent in a conversation. The Lync 2010 application in these articles ignores this event.
ContextDataReceived event	This event is raised when context data is received in a conversation. The Lync 2010 application described in these articles registers a handler for this event. When context data from the UCMA 3.0 application is received, the handler is called.
ContextDataSent event	This event is raised when context data is sent in a conversation. The Lync 2010 application described in these articles registers a handler for this event. When this application sends context data to the UCMA 3.0 application, the handler is called.
GetApplicationData method	This method gets the contextual conversation application data by using the given Application ID. Only a registered application that uses the same Application ID can call this method. In a scenario where a call from a UCMA 3.0 application starts the Lync 2010 application, the InitialContextReceived event is raised before the application appears on the desktop. To obtain the initial context you must get the Conversation object and then call GetApplicationData.

Lync Application Run-Time Tasks

Three important Lync 2010 application tasks are associated with sending and receiving context data:

• Initialize the form in the Conversation Window Extension (CWE).

• Send context data to the UCMA 3.0 application.

• Receive context data from the UCMA 3.0 application.

Initialize the Form in the CWE

The first context data arrives at the Lync 2010 application when the UCMA 3.0 application establishes the context channel. The Lync 2010 application retrieves this data in the Initialize method, which initializes the form that is used in the CWE.

The Initialize method first obtains the hosting conversation, by using a call to GetHostingConversation(). The Initialize method then registers to receive notifications when the ContextDataReceived, InitialContextReceived, and ContextDataSent events are raised.

The Initialize method then calls GetApplicationData, which returns a string that contains the context data.

Note

The string that GetApplicationData returns is the string that the UCMA 3.0 application sends when it calls BeginEstablish on the context channel (in the ContextualData property of the ConversationContextChannelEstablishOptions parameter).

Finally, the Initialize method verifies that this initial context data contains the string "open". If "open" appears, Initialize updates the UI in the form to inform the user that the application can be used. If the context data is an empty string, the handler for the InitialContextReceived event should handle the UI update.

The following example shows calls to the Logger method, which displays text in the Logger text box in the Silverlight form. The definition of this method appears in Using UCMA 3.0 and Lync 2010 for Contextual Communication: Code Walkthrough (Part 5 of 6).

// Get the hosting Conversation object, register for event notification, and then get the application data.
private void Initialize()
{
  String appData;
  try
  {
    _conversation = (Conversation)Microsoft.Lync.Model.LyncClient.GetHostingConversation();
  }
  catch (LyncClientException ex)
  {
    Logger("LyncClientException error: " + ex);
  }

  catch (Exception ex)
  {
    Logger("Other conversation initialization error: " + ex);
  }

  _conversation.ContextDataReceived += OnContextDataReceived;
  _conversation.InitialContextReceived += OnInitialContextReceived;
  _conversation.ContextDataSent += OnContextDataSent;
  
  appData = _conversation.GetApplicationData(_appId);
  Logger("Application data: " + appData);
  
  if (appData.Contains("open"))
  {
    channelStatus.Foreground = new SolidColorBrush(Colors.Green);
    channelStatus.Text = "Ready";
  }
}

The following example shows the handler for the InitialContextReceived event.

void OnInitialContextReceived(object sender, InitialContextEventArgs args)
{
  channelStatus.Foreground = new SolidColorBrush(Colors.Green);
  channelStatus.Text = "Ready";
  Logger("InitialContextReceived event raised. Data received: " + args.ApplicationData);
}

Send Context Data to the UCMA 3.0 Application

When the Lync 2010 user selects one of the three option buttons that appear in the form, a handler for the option button sets a global variable, _itemChosen, with a value that indicates the item. The next example shows a handler for the Click event on one option button. The other two handlers are similar.

private void radioButton_Click1(object sender, RoutedEventArgs e)
{
  _itemChosen = "Camera";
}

When the Lync 2010 user then clicks the SendData button, a Click event for the option button is raised, and the SendAdditionalData_Click handler that appears in the following example is called. The handler calls the BeginSendContextData method to send the context data to the UCMA 3.0 application.

Important

The MIME type string must be formed correctly, because the BeginSendContextData method does not validate the value of this parameter.

private void SendAdditionalData_Click(object sender, RoutedEventArgs e)
{
  try
  {
    Logger("Sending additional context: Query item = " + _itemChosen);

    _conversation.BeginSendContextData(AppId, @"plain/text", _itemChosen, SendAdditionalDataCallBack, null);
  }

  catch (Exception ex)
  {
    Logger("SendAdditionalData error: " + ex);
  }
}

Receive Context Data from the UCMA 3.0 Application

After the Lync 2010 application sends context data that identifies the selected item, the UCMA 3.0 application sends additional information about that item on the context channel. This action causes the ContextDataReceived event to be raised to the Lync 2010 application.

The context data consists of a string that contains the model number, the price, and whether the item is currently available. The three values are separated by commas. After the handler separates the three values, they appear in the UI.

// Handler for the ContextDataReceived event on the Conversation object.
// This handler displays the data sent to it from the UCMA application.
public void OnContextDataReceived(object sender, ContextEventArgs args)
{
  if ((args != null) && (args.ContextData.Length != 0))
  {
    Logger("OnContextDataReceived:" + args.ContextData);
    string str = args.ContextData;
    string[] substr = str.Split(new char[] { ',' });

    // Populate the three text boxes.
    ModelBox.Text = substr[0];
    PriceBox.Text = substr[1];
    AvailabilityBox.Text = substr[2];
  }
  else
  {
    Logger("OnContextDataReceived called with no data.");
  }
}

Part 5

Using UCMA 3.0 and Lync 2010 for Contextual Communication: Code Walkthrough (Part 5 of 6)

Additional Resources

For more information, see the following resources:

• Lync Developer Center

• Getting Started with Lync Server Deployment

• Lync Server TechCenter

• Lync by Lync

About the Authors

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