Handling Session Invitations

Article
06/14/2014

This content is no longer actively maintained. It is provided as is, for anyone who may still be using these technologies, with no warranties or claims of accuracy with regard to the most recent product version or service release.

An incoming session invitation is exposed as an event raised by the session manager. The session manager is an instance of IUccSessionManager and provides the session event monitoring functionality for a local client. To respond to incoming session invitations, a client must obtain this interface and register for _IUccSessionManagerEvents. To learn about creating a session manager and advising for session manager events, see Performing Essential Session Tasks.

When a remote client originates a session and invites the local client, the local client is responsible for accepting or rejecting the invitation. Upon acceptance of a session invitation, the local client is connected to the incoming session and the remote client is notified of the acceptance via the OnStateChanged event.

The OnIncomingSession Event

The OnIncomingSession callback function is raised when the local client has received a session invitation. A local client can reject an invitation by either ignoring the invitation or actively rejecting it with a call into Reject. Upon rejection, the remote client is informed through an OnStateChanged event that the local client has rejected the invitation. This callback function is the first and only chance a client has to respond to any type of session invitation. The following programming pattern and example code demonstrates the handling of IM and audio/video session invitations.

Programming Pattern

Ask User to Accept or Reject Invitation.

DialogResult result = MessageBox.Show(
     "Accept incoming session from " + pEventData.Inviter.Uri + "?",
     "Incoming Session",
     MessageBoxButtons.YesNo);

Process user choice.
If user rejects invitation, call Reject. Unified Communications Client API provides a set of enumeration values indicating rejection reasons. The remote user is notified of the rejection with the chosen reason. Note that UCC_REJECT_OR_TERMINATE_REASON.UCCROTR_NOT_SPECIFIED must not be supplied as the reason for rejecting an invitation. The inviting client is not informed of the rejection if this value is used.
```
pEventData.Reject(
          UCC_REJECT_OR_TERMINATE_REASON.UCCROTR_DECLINE);
      return;
```
After calling into Reject, the client can return from the callback method as no further processing needs to be done.

If the invitation is accepted, determine the incoming session type. Read the Type property on the session object passed to the callback function as pEventData. The example calls custom application classes that wrap the functionality specific to each session type.
Before accepting the incoming session, a client can verify whether the session is established by checking the participant state of the remote participant. The remote participant connection state can change in the course of a session. A remote client should be prepared to handle these events. See Handling Session Participant Events for more information.

Important

Microsoft Office Communicator (MOC) provides a unique conversation identifier that you must capture and cache with an incoming session. If a peer-to-peer session is escalated to a conference session by a MOC client, this identifier allows you to find the original peer-to-peer session being replaced by a new conference session.
If your client is to interoperate with a MOC client, you must assign a conversation identifier to be added as operation context when you create a session whose participants include MOC clients. For information about creating and assigning conversation identifiers for outgoing sessions, see Performing Essential Session Tasks

 //Verify that the remote user is still connected to the session.
 if (pEventData.Inviter.State != UCC_SESSION_ENTITY_STATE.UCCSES_CONNECTED)
 {
    return;
 }
 // Declare string to hold the unique conversation ID assigned by the session originator.
 string conversationID = string.Empty;

 // Determine if session originator assigned a conversation ID to the session
 if (pEventData.Session.Context.IsPropertySet(10000) == true)
 {
     // If conversation ID was assigned, obtain the property using the
     // reserved value of 10000.
     conversationID = pEventData.Session.Context.get_Property(10000).StringValue;
 }

 //If the session is still valid, check the modality type of the session and
 //create application class appropriate for session modality
 switch (pEventData.Session.Type)
 {
     case UCC_SESSION_TYPE.UCCST_AUDIO_VIDEO:
        //instantiate application A/V session class wrapper,
        //passing the received session as param
        // CustomAVSession myNewAVSession = new CustomAVSession(pEventData.Session);
        break;
     case UCC_SESSION_TYPE.UCCST_INSTANT_MESSAGING:
        //instantiate application IM session class wrapper,
        //passing the received session as param
        // CustomIMSession myNewIMSession = new CustomIMSession(pEventData.Session);
        break;
     case UCC_SESSION_TYPE.UCCST_CONFERENCE:
        //instantiate application Conference session class wrapper,
        //passing the received session as param
        // CustomConfSession myNewConfSession = new CustomConfSession (pEventData.Session);
        break;
     case UCC_SESSION_TYPE.UCCST_APPLICATION:
        //instantiate application Application session class wrapper,
        //passing the received session as param
        // CustomAppSession myNewAppSession = new CustomAppSession (pEventData.Session);
        break;
 }

Accept the incoming session. Call the Accept method to activate the session.

   pEventData.Accept();

Example

The following example is a complete code listing for an OnIncomingSession callback function.

IUccSession session;
void _IUccSessionManagerEvents.OnIncomingSession(
            IUccEndpoint pEventSource,
            IUccIncomingSessionEvent pEventData)
{
   // First ask the user for permission to accept or decline the
   // pending invitation.
   DialogResult result = MessageBox.Show(
        "Accept incoming session from " + pEventData.Inviter.Uri.Value + "?",
        "Incoming Session",
        MessageBoxButtons.YesNo);

   if (result != DialogResult.Yes)
   {
      // The user has said "no" to the invitation. Thus, reject
      // the incoming session.
      pEventData.Reject(
          UCC_REJECT_OR_TERMINATE_REASON.UCCROTR_DECLINE);
      return;
   }
   // The user agreed to accept the invitation.


    switch (pEventData.Session.Type)
    {
        case UCC_SESSION_TYPE.UCCST_AUDIO_VIDEO:
           //instantiate application A/V session class wrapper,
           //passing the received session as param
           // CustomAVSession myNewAVSession = new CustomAVSession(pEventData.Session);
           break;
        case UCC_SESSION_TYPE.UCCST_INSTANT_MESSAGING:
           //instantiate application IM session class wrapper,
           //passing the received session as param
           // CustomIMSession myNewIMSession = new CustomIMSession(pEventData.Session);
           break;
        case UCC_SESSION_TYPE.UCCST_CONFERENCE:
           //instantiate application Conference session class wrapper,
           //passing the received session as param
           // CustomConfSession myNewConfSession = new CustomConfSession (pEventData.Session);
           break;
        case UCC_SESSION_TYPE.UCCST_APPLICATION:
           //instantiate application Application session class wrapper,
           //passing the received session as param
           // CustomAppSession myNewAppSession = new CustomAppSession (pEventData.Session);
           break;
    }
    pEventData.Accept();
}

Handling Session Invitations

The OnIncomingSession Event

Programming Pattern

Example

See Also

Concepts

Additional resources