Send and Update Context in a UCMA Conversation

[This is preliminary documentation and is subject to change.]

Use Microsoft Lync 2013 Preview SDK and Microsoft Lync 2013 Preview to participate in a Microsoft Unified Communications Managed API 4.0 Preview conversation. The UCMA 4.0 Preview application hosts the conversation and starts the context channel, and the Lync 2013 Preview client responds to the INVITE event from UCMA 4.0 Preview to join the conversation.

  • On the UCMA 4.0 Preview computer, create and establish a UserEndPoint endpoint, and then add a remote endpoint to represent the Lync 2013 Preview conversation endpoint.

  • On the Lync 2013 Preview client, use the Conversation.GetApplicationData method to receive data, and the Conversation.BeginSendContextData method to send data.

The following steps describe how to create and manage a conversation on the UCMA 4.0 Preview computer.

  1. Create a CollaborationPlatform instance.

  2. Create and establish an endpoint by using a previously created CollaborationPlatform instance and endpoint settings.

  3. Create a Conversation instance.

  4. Create a call, typically by using an instance of the InstantMessagingCall or AudioVideoCall class.

  5. Place a call to the remote endpoint by using the BeginEstablish method on the call. Specify the SIP URI. An INVITE is sent to the Lync SDK application, and the first toast starts to run on the Lync 2013 Preview computer.

  6. Create a new ConversationContextChannel instance, passing the conversation and remote endpoint as parameters.

  7. Create a ConversationContextChannelEstablishOptions instance, and set the appropriate property values. The properties in the next example identify the application.

    channelOptions.ApplicationInstallerPath = "http://www.msn.com";
    channelOptions.ApplicationName = "Blue Yonder Airlines";
    channelOptions.ContextualData = "Contextual data from UCMA";
    channelOptions.RemoteConversationId = "1234";
    channelOptions.SimpleLink = "";
    channelOptions.Toast = "Some contextual data is coming in this call.";
    
  8. Establish the ConversationContextChannel instance by calling the BeginEstablish method. Pass the GUID in the ConversationContextChannelEstablishOptions instance. Another INVITE is sent and the second toast starts to run on the Lync 2013 Preview computer.

  9. When the ConversationContextChannel instance is in the Established state, call BeginSendContextData to send contextual data to the remote endpoint.

  10. When the remote endpoint responds through the context channel, the DataReceived event on the UCMA 4.0 Preview side is raised. This event contains contextual data in the event arguments.

  11. The channel is now open and you can exchange data. When no more data will be sent, call BeginTerminate on the channel.

Lync 2013 Preview gets the application invite from UCMA 4.0 Preview, sets up the conversation window and opens the Conversation Window Extension with a Microsoft Silverlight application that contains information about the caller. Once the SIP conversation is established the conversation window appears, and then UCMA 4.0 Preview and Lync 2013 Preview can exchange data over the channel both ways.

The following example shows how to use Conversation object methods to send and receive context as soon as the conversation session starts. For more information, see Send and Update Context in an Existing Conversation.

Receiving Content

On the Lync 2013 Preview client, the following example shows how to use the Conversation.GetApplicationData method to receive data. A GetAppData_Click event is sent to the Lync 2013 Preview client.

Sending Content

The following example also shows how to use the Conversation.BeginSendContextData method to send data. A SendData_Click event is sent to the Lync 2013 Preview client.

Example

Use Conversation object methods appearing in the next example to send and receive contextual data in a conversation with a UCMA 4.0 Preview application.


private void Logger(string text)
{
    LoggerTextBox.Text += text + "\n";
}

private void Initialize()
{
    try
    {
        _conversation = (Conversation)Microsoft.Lync.Model.LyncClient.GetHostingConversation();
        _conversation.InitialContextReceived += OnInitialContextReceived;
        _conversation.InitialContextSent += OnInitialContextSent;
        _conversation.ContextDataReceived += OnContextDataReceived;
        _conversation.ContextDataSent += OnContextDataSent;
    }
    catch (Exception ex)
    {
        Logger("Exception: " + ex);
    }
}

// Occurs when an application receives context data after the initial receipt of data.
// Useful to avoid having to poll to see if more data arrived.
public void OnContextDataReceived(object sender, ContextEventArgs args)
{
    try
    {
        Logger("OnContextDataReceived: AppId = " + args.ApplicationId + " DataType = " + args.ContextDataType + " Data = " + args.ContextData);
    }
    catch (Exception ex)
    {
        Logger("Exception: " + ex);
    }
}

// Occurs when an application sends context data after the initial transmission of data.
public void OnContextDataSent(object sender, ContextEventArgs args)
{
    try
    {
        Logger("OnContextDataSent: AppId = " + args.ApplicationId + " DataType = " + args.ContextDataType + " Data ++oncontextSent++ = " + args.ContextData);
    }
    catch (Exception ex)
    {
        Logger("Exception: " + ex);
    }
}

// Occurs when an application initially sends context data.
public void OnInitialContextSent(object sender, InitialContextEventArgs args)
{
    try
    {
        Logger("OnInitialContextSent: AppId = " + args.ApplicationId + " AppData ++oncontextSent++ = " + args.ApplicationData);
    }
    catch (Exception ex)
    {
        Logger("Exception: " + ex);
    }
}

// Occurs when an application initially receives context data.
public void OnInitialContextReceived(object sender, InitialContextEventArgs args)
{
    try
    {
        Logger("OnInitialContextReceived: AppId = " + args.ApplicationId + " AppData = " + args.ApplicationData);
    }
    catch (Exception ex)
    {
        Logger("Exception: " + ex);
    }
}

private void GetAppData_Click(object sender, RoutedEventArgs e)
{
    try
    {
        // Receive data from the UCMA application.
        string appData = _conversation.GetApplicationData(AppId);
        Logger("AppData = " + appData);
    }
    catch (Exception ex)
    {
        Logger("Exception: " + ex);
    }
}

private void SendData_Click(object sender, RoutedEventArgs e)
{
    try
    {
        Logger("Sending additional context: DataType = " + DataTypeBox.Text + " Data = " + AppDataBox.Text);

        // Send data to the UCMA application.
        // AppId parameter is the application GUID.
        // The next two parameters are text box entries from the application UI.
        // The fourth parameter is the name of the callback method.
        _conversation.BeginSendContextData(AppId, DataTypeBox.Text, AppDataBox.Text, SendAdditionalDataCallBack, null);
    }
    catch (Exception ex)
    {
        Logger("Exception: " + ex);
    }
}

private void SendAdditionalDataCallBack(IAsyncResult asyncResult)
{
    if (asyncResult.IsCompleted)
    {
        _conversation.EndSendContextData(asyncResult);
        Logger("Additional Context Sent successfully.");
    }
    else
    {
        Logger("Additional Context Sent Failed : " + asyncResult.AsyncState);
    }
}

Community Additions

Show:
© 2014 Microsoft