Walkthrough: Hold and Retrieve an Audio Conversation (Lync 2010 SDK)
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 instant messaging 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.
Hold or Retrieve an Audio Conversation
Get a connected instance of Conversation.
For information about starting an audio conversation, see Walkthrough: Start an Audio Conversation (Lync 2010 SDK).
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. 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.
To 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.
Examples
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
Note
The example only illustrates the walkthrough tasks need to hold or retrieve a call. For an example of a complete event handler, see Walkthrough: Start an Audio Conversation (Lync 2010 SDK).
/// <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;
}
}
See Also
Concepts
Lync Model API Conversation Walkthroughs (Lync 2010 SDK)