Inviting a New Participant

Microsoft Unified Communications Managed API (UCMA) 3.0 has revised the way conference invitations are sent to simplify the task of inviting a participant to a conference. In addition the revisions allow more flexibility in tracking the state of the invitation sent to each recipient.

The basic steps for inviting a new participant to a conference are as follows.

• Create a ConferenceInvitation instance.

• Use one of the BeginDeliver() methods to deliver the invitation to a recipient.

The State property and the StateChanged event on the ConferenceInvitation class can be used to monitor changes in state of the invitation.

When an application receives an invitation, it is normally expected to accept the invitation and join the conference so that it shows up in the list of participants. Different applications have different capabilities, so not all of them will be able to join a given conference. In some cases, the BeginDeliver method can detect that a remote application is unable to join the conference on its own, so BeginDeliver requests the MCU to make a call to the remote application. In this way, an application that is unable to join the conference as a participant can still take part in the conference. If this happens, even though the invitation succeeded and the remote application has joined the conference, the application might not appear in the list of participants. Some applications might not support conferencing at all, in which case the EndDeliver(IAsyncResult) method throws an exception.

For most applications that send invitations, being able to detect whether the invitation was accepted is of utmost importance. The following example demonstrates how this can be done.

public void InviteToConference()
{
  ConferenceInvitation invitation = new ConferenceInvitation(m_conversation);

  invitation.StateChanged += this.InvitationStateChanged;

  ConferenceInvitationDeliverOptions deliverOptions = 
      new ConferenceInvitationDeliverOptions();
  deliverOptions.ToastMessage = new ToastMessage("This is the popup message or toast.");

  try
  {
    invitation.BeginDeliver(
      "sip:mary@contoso.com",
      deliverOptions,
      this.DeliverCompleted,
      invitation);
  }
  catch (InvalidOperationException)
  {
    // Conversation was terminated while trying to add participant.
  }
}

private void DeliverCompleted(IAsyncResult result)
{
  RealTimeException ex = null;
  ConferenceInvitation invitation = result.AsyncState as ConferenceInvitation;
  
  try
  {
    invitation.EndDeliver(result);

    // Invitation was accepted
  }
  catch (RealTimeException exception)
  {
    // Invitation was not accepted.
    ex = exception;
  }
  finally
  {
    .
    . 
    .
  }
}

Migrating ConferenceInvitation Code from UCMA 2.0

Because the BeginInviteRemoteParticipants method on the Conversation class is now obsolete, it is important to update code to use the new model. The following example shows typical Microsoft Unified Communications Managed API (UCMA) 2.0 usage.

List<string> myTargets = new List<string>();
myTargets.Add("sip:john@contoso.com");
myTargets.Add("sip:cathy@contoso.com");

ToastMessage toastMessage = new ToastMessage("Please join this team meeting.");

try
{
  m_conversation.BeginInviteRemoteParticipants(
    myTargets,
    toastMessage,
    this.InviteRemoteParticipantsCompleted,
    null /*state*/);
}
catch (InvalidOperationException)
{
  // Conversation was terminated while adding participants.
}

The preceding code should be updated to invite the participants individually. The following example shows how this can be done.

List<string> myTargets = new List<string>();
myTargets.Add("sip:john@contoso.com");
myTargets.Add("sip:cathy@contoso.com");

ToastMessage toastMessage = new ToastMessage("Please join this team meeting.");

try
{
  foreach (string target in myTargets)
  {
    ConferenceInvitation invitation = new ConferenceInvitation(m_conversation);

    ConferenceInvitationDeliverOptions deliverOptions = new ConferenceInvitationDeliverOptions();

    deliverOptions.ToastMessage = toastMessage;

    invitation.BeginDeliver(
      target,
      deliverOptions,
      this.DeliverCompleted,
      invitation /*state*/);

  }
}
catch (InvalidOperationException)
{
  // Conversation is likely terminated. No participants can be added.
}

The following members previously used to track status of individual invitations are now obsolete.

• InviteRemoteParticipantUpdate event on the Conversation class (and the corresponding InviteParticipantUpdateEventArgs class)

• Status property on the ConferenceInvitationResponse class(and the corresponding ConferenceInvitationStatus enumeration)

Individual status for each recipient can now be determined by carrying out the following actions.

• Check the EndDeliver return value.

• Check the exception thrown by EndDeliver.

• Inspect the changes in the State property and the transition reasons given in TransitionReason property in the ConferenceInvitationStateChangedEventArgs instance associated with the StateChanged event.

Another change is that the Outgoing value in the ConferenceInvitationState enumeration is now obsolete. In its place use the Delivering value.