How to: Hold and retrieve a Lync audio conversation
Learn how to programmatically hold and retrieve a Microsoft Lync 2013 audio call by using Microsoft Lync 2013 SDK.
Applies to: Lync 2013 | Lync Server 2013
In this article |
Audio conversation overview
To hold or retrieve an audio conversation, you call methods on the audio/video modality from the Conversation class. If a conversation includes both the IM modality and audio/video modality, the conversation can still be held, forwarded, or transferred. These actions must be performed on the AVModality instance of the conversation.
Prerequisites
The prerequisites for holding and retrieving a call are as follows:
Microsoft Lync 2013 must be installed and running on the development computer.
You must have sign-in credentials for Microsoft Lync Server 2013.
Microsoft Lync 2013 SDK must be installed on the development computer.
Core concepts to know
Topic |
Description |
|---|---|
Describes how the Microsoft.Lync.Model.Conversation.Modality class represents a mode of communication in a conversation. |
|
Describes how users are represented in conversations as participants. |
Hold or retrieve an audio conversation
To hold and retrieve an audio conversation
Get a connected instance of Conversation.
For information about starting an audio conversation, see How to: Start a Lync audio conversation.
Register for the StateChanged event on the Conversation instance.
Get the AVModality instance from the collection of modalities on the Conversation instance.
Read the Modalities property and use the ModalityTypes.AudioVideo enumerator as an index to specify which modality to get.
Register for the ModalityStateChanged and ActionAvailabilityChanged events on the AVModality instance.
To hold a conversation, call into the BeginHold method on the AVModality instance.
To catch the asynchronous result of the hold operation, pass a callback method in the first argument and a state object in the second argument. Otherwise, pass null values in both arguments.
Retrieve a conversation. If the state of the AVModality instance is ModalityState.Hold, call Retrieve on the AVModality instance using the same arguments.
To catch the asynchronous result of the retrieve operation, pass a callback method in the first argument and a state object in the second argument. Otherwise, pass null values in both arguments.
Handle the StateChanged event raised by the Conversation instance when the state of the conversation changes to ConversationState.Inactive.
Handle the ModalityStateChanged event raised by the AVModality instance when the state of the modality changes to ModalityState.OnHold.
Code examples: Lync audio conversations
The examples in this section hold or retrieve a call and handle all related events.
Hold or retrieve a call
The following example holds or retrieves a call.
.gif "Note") Note |
|---|
The example only illustrates the tasks needed to hold or retrieve a call. For an example of a complete event handler, see How to: Start a Lync audio conversation. |
/// <summary>
/// Hold or retrieve a conversation
/// </summary>
private void HoldConversation(Conversation pConversation)
{
if (pConversation.Modalities[ModalityTypes.AudioVideo].State == ModalityState.OnHold)
{
object[] asyncState = { pConversation.Modalities[ModalityTypes.AudioVideo], "RETRIEVE" };
pConversation.Modalities[ModalityTypes.AudioVideo].BeginRetrieve(ModalityCallback, asyncState);
}
else if (pConversation.Modalities[ModalityTypes.AudioVideo].State == ModalityState.Connected)
{
object[] asyncState = { pConversation.Modalities[ModalityTypes.AudioVideo], "HOLD" };
IAsyncResult ar = pConversation.Modalities[ModalityTypes.AudioVideo].BeginHold(ModalityCallback, asyncState);
}
}
ConversationStateChange event
The following example is invoked by a Conversation instance when the state of the conversation changes.
/// <summary>
/// Handles event raised when the state of an active conversation has changed.
/// </summary>
/// <param name="source">Conversation. The active conversation that raised the state change event.</param>
/// <param name="data">ConversationStateChangedEventArgs. Event data containing state change data.</param>
void Conversation_ConversationChangedEvent(object source, ConversationStateChangedEventArgs data)
{
if (data.NewState == ConversationState.Inactive)
{
MessageBox.Show("Conversation is on hold");
//Enable a hold retrieve button.
}
if (data.NewState == ConversationState.Active)
{
MessageBox.Show("Conversation is active");
//Enable a hold button.
}
}
Modality operation callback method
The following example is invoked by an instance of AVModality when a modality operation is complete.
/// <summary>
/// Called on the LyncClient worker thread when an audio/video modality action completes.
/// </summary>
/// <param name="ar">IAsyncResult. The state of the asynchronous operation.</param>
private void ModalityCallback(IAsyncResult ar)
{
Object[] asyncState = (Object[])ar.AsyncState;
try
{
if (ar.IsCompleted == true)
{
if (asyncState[1].ToString() == "RETRIEVE")
{
((AVModality)asyncState[0]).EndRetrieve(ar);
}
if (asyncState[1].ToString() == "HOLD")
{
((AVModality)asyncState[0]).EndHold(ar);
}
if (asyncState[1].ToString() == "CONNECT")
{
((AVModality)asyncState[0]).EndConnect(ar);
}
if (asyncState[1].ToString() == "FORWARD")
{
((AVModality)asyncState[0]).EndForward(ar);
}
}
}
catch (LyncPlatformException)
{ }
}
Audio/video modality ActionAvailabilityChanged event
void myAVModality_ActionAvailabilityChanged(object sender, ModalityActionAvailabilityChangedEventArgs e)
{
switch (e.Action)
{
case ModalityAction.Hold:
if (e.IsAvailable == true)
{
MessageBox.Show("Call can be placed on hold.");
}
break;
case ModalityAction.Retrieve:
if (e.IsAvailable == true)
{
MessageBox.Show("Call is on hold and can be retrieved");
}
break;
}
}
ModalityStateChanged event
The following example handles the ModalityStateChanged event raised by the audio/video modality when a call is placed on hold or retrieved from hold.
/// <summary>
/// Handles the Modality state changed event for a Conversation
/// </summary>
/// <param name="source">Modality. Modality whose state has changed.</param>
/// <param name="data">ModalityStateChangedEventArgs. Old and new modality states.</param>
void _AVModality_ModalityStateChanged(object sender, ModalityStateChangedEventArgs e)
{
switch (e.NewState)
{
case ModalityState.OnHold:
//Enable a call transfer button.
break;
case ModalityState.Connecting:
//Update connecting status string on UI.
break;
case ModalityState.Forwarding:
//Update connecting status string on UI.
break;
case ModalityState.Transferring:
//Update connecting status string on UI.
break;
case ModalityState.Connected:
//Update connecting status string on UI.
//Enable a call hold button.
break;
}
}