_IUccSessionManagerEvents.OnIncomingSession Method

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.

Raised when the session manager object receives an incoming session.

Namespace: Microsoft.Office.Interop.UccApi
Assembly: Microsoft.Office.Interop.UccApi (in microsoft.office.interop.uccapi.dll)

Syntax

'Declaration
Sub OnIncomingSession ( _
    pEventSource As IUccEndpoint, _
    pEventData As UccIncomingSessionEvent _
)
void OnIncomingSession (
    IUccEndpoint pEventSource,
    UccIncomingSessionEvent pEventData
)
void OnIncomingSession (
    IUccEndpoint^ pEventSource, 
    UccIncomingSessionEvent^ pEventData
)
void OnIncomingSession (
    IUccEndpoint pEventSource, 
    UccIncomingSessionEvent pEventData
)
function OnIncomingSession (
    pEventSource : IUccEndpoint, 
    pEventData : UccIncomingSessionEvent
)

Parameters

  • pEventSource
    A value of the IUccEndpoint* (IUccEndpoint, for a .NET application) type. This identifies the IUccSessionManager instance raising this event. The IUccSessionManager instance is also an IUccEndpoint instance as the interface is queried from the IUccEndpoint instance.
  • pEventData
    A value of the IUccIncomingSessionEvent* (UccIncomingSessionEvent, for a .NET application) type. This specifies the event data about the invitation and the new incoming session. The application can send the data to inform the user of the invitation details and then accepts or rejects the invitation. It can also forward the invitation to a third party.

Remarks

This event is used to notify the user of a pending invitation to join a session with another (remote) participant. The application must catch this event: displaying to the user the information about the invitation (pEventData) and then accepting or rejecting the invitation on the user's behalf. The application can also forward the invitation to a third party.

When rejecting an invitation by calling into Reject, the client should avoid using UCCROTR_NOT_SPECIFIED. All of the other enumerated termination/reject reasons result in the rejecting user's session state (UCC_SESSION_ENTITY_STATE) to change to UCCSES_DISCONNECTED.

Win32 COM/C++ Syntax

HRESULT OnIncomingSession
(
   IUccEndpoint* pEventSource,
   IUccIncomingSessionEvent* pEventData
);

Note

In a Win32 application, the return value of a method or property is always an HRESULT value indicating the status of the call to the interface member. Any result of the operation is returned as a parameter marked with the [out, retval] attribute. In contrast, in a .NET application the HRESULT value indicating an error condition is returned as a COM exception and the [out, retval] parameter becomes the return value. For the UCC API-defined HRESULT values, see Trace and Handle Errors in Unified Communications Client API.

Example

The following example event handler for OnIncomingSession is drawn from an application class that handles events raised by an instance of IUccSessionManager. This example responds to the incoming invitation by displaying a dialog providing information about the incoming session invitation and giving the user a choice to accept or reject the invitation. Upon rejection, the handler terminates. If the session is accepted, the Session property of the pEventData parameter is cast to the appropriate session derived interface.

If an incoming session originated from a Microsoft Office Communicator (MOC) client, you must obtain the conversation ID assigned by the MOC client. The conversation ID is unique and used to identify the session. When a peer-to-peer session is escalated to a conference by the MOC client, you receive an invitation to the new conference in the form of an application session. The incoming application session is obtained by handling the OnIncomingSession event. The application session carries both a conference invitation in XML payload and the original peer-to-peer conversation ID in the session property. Use the conversation ID property to identify and terminate the original peer-to-peer session.

/// <summary>
/// handles session invitations by displaying a dialog for
/// local user advising user of invitation and providing a mechanism
/// for the user to respond to the invitation
/// </summary>
/// <param name="pEventSource"></param>
/// <param name="pEventData"></param>
void _IUccSessionManagerEvents.OnIncomingSession(
    IUccEndpoint pEventSource,
    UccIncomingSessionEvent pEventData)
{
    // First ask the user for permission to accept or decline the
    // pending invitation.
    System.Windows.Forms.DialogResult result = System.Windows.Forms.MessageBox.Show(
        "Accept incoming session from " + 
        pEventData.Inviter.Uri.UserAtHost + "?",
        "Incoming Session",
        System.Windows.Forms.MessageBoxButtons.YesNo);

    if (result != System.Windows.Forms.DialogResult.Yes)
    {
        // The user has said "no" to the invitation. Thus, rejected
        // the incoming session.
        pEventData.Reject(
            UCC_REJECT_OR_TERMINATE_REASON.UCCROTR_NOT_ACCEPTABLE);
        return;
    }

    // Declare a string to hold the conversation ID of the incoming
    // session. If the incoming session is an application session, the 
    // conversation ID is that of a peer-to-peer session to be terminated and
    // replaced by conference session. The property Id value of 10000 MUST be used.
    string conversationID = string.Empty;
    if (pEventData.Session.Context.IsPropertySet(10000) == true)
    {
        conversationID = pEventData.Session.Context.get_Property(10000).StringValue;
    }

    // The user agreed to accept the invitation.
    switch (pEventData.Session.Type)
    {
        case UCC_SESSION_TYPE.UCCST_INSTANT_MESSAGING:
            IUccInstantMessagingSession imSession = pEventData.Session as IUccInstantMessagingSession;
            break;
        case UCC_SESSION_TYPE.UCCST_AUDIO_VIDEO:
            IUccAudioVideoSession avSession = pEventData.Session as IUccAudioVideoSession;
            break;
        case UCC_SESSION_TYPE.UCCST_CONFERENCE:
            IUccConferenceSession confSession = pEventData.Session as IUccConferenceSession;
            break;
       case UCC_SESSION_TYPE.UCCST_APPLICATION:
            break;
    }
    pEventData.Accept();
}

Thread Safety

All public static (Shared in Visual Basic) members of this type are thread-safe. Instance members are not guaranteed to be thread-safe.

Platforms

Development Platforms

Windows XP Professional with Service Pack 2 (SP2), Windows Server 2000 with Service Pack 4, Windows Server 2003, Windows Vista Ultimate Edition, Windows Vista Business Edition, Windows Vista Enterprise Edition

Target Platforms

See Also

Reference

_IUccSessionManagerEvents Interface
_IUccSessionManagerEvents Members
Microsoft.Office.Interop.UccApi Namespace