Share via

IUccIncomingSessionEvent.TargetReplaceSession Property

  • Article

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.

Gets an existing session to be replaced by the incoming session applicable to consultative transfer. TargetReplaceSession is only supported by Audio/Video sessions.

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

Syntax

'Declaration
ReadOnly Property TargetReplaceSession As IUccSession

IUccSession TargetReplaceSession { get; }

property IUccSession^ TargetReplaceSession {
    IUccSession^ get ();
}

/** @property */
IUccSession get_TargetReplaceSession ()

function get TargetReplaceSession () : IUccSession

Property Value

A value of the IUccSession** (IUccSession, for a .NET application) type.

Remarks

This property is applicable to consultative transfer. Its use can be explained as follows. A user (A) calls another user (B) in a session (AB). B wants to transfer the call to a third user (C) and consults with C in another session (BC). With C's permission, B transfers A to C and provides A with a pointer to session BC. (This involves B calling IUccSessionCallControl.ConsultativeTransfer on session AB.) After receiving the _IUccSessionCallControlEvents::OnIncomingTransfer event, user A calls C supplying the information about BC. C then receives the invitation from A. The event data has TargetReplaceSession set and the property value is session BC. C can then terminate session BC if C accepts the invitation from A. Terminating session BC involves getting the session object by reading this property and calling the Terminate method on the resultant session object.

An audio/video, remote call control, or instant messaging session can be transfered.

Win32 COM/C++ Syntax

HRESULT get_TargetReplaceSession
(
   IUccSession** ppTargetReplaceSession
);

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

In the following example scenario, User A and User B are connected in a session (AB). At the same time, User B and User C are connected in a different session (BC).

The three clients are:

  • Client A. User A has one active session (AB).

  • Client B. User B is hosting two sessions, (AB) and (BC).

  • Client C. User C is hosting one session (BC).

User B transfers User A to User C and leaves the conversation. The following steps are taken to accomplish the consultative transfer. Assume the consultation between User B and User C has taken place.

User B Calls ConsultativeTransfer

User B uses session AB to transfer user A to user C and provides user A with a pointer to session BC.

/// <summary>
/// transfers this call to another telephone session after consult with user on
/// other session
/// </summary>
/// <param name="currentSession">IUccAudioVideoSession the current session (AB)</param>
/// <param name="activeSession">telephone session user C is to terminate (BC)</param>
/// <param name="iOperationId">Int Operation context value</param>
/// <returns>error code</returns>
public void ConsultTransfer(
    IUccAudioVideoSession currentSession,
    IUccSession activeSession, 
    int iOperationId)
{
    //user B casts the current session (AB) to session call control
    IUccSessionCallControl SessionCC = currentSession as IUccSessionCallControl;

    //user B advises for session call control events
    UCC_Advise<_IUccSessionCallControlEvents>(SessionCC, this);

    UccOperationContext pOperationContext = new UccOperationContext();
    UccContext newContext = new UccContext();
    if (sContextKey.Length > 0 && sContextValue.Length > 0)
    {
        newContext.AddNamedProperty(
            sContextKey, 
            sContextValue);
    }
    pOperationContext.Initialize(
       iOperationId, 
       newContext);

    //User B calls ConsultativeTransfer on the current session (AB)
    SessionCC.ConsultativeTransfer(
        activeSession, //session (BC)
        pOperationContext);

}

User C Receives Invitation from User A, Accepts AC and Terminates BC.

User C receives the incoming transferred (AB) session and accepts. Session AB becomes AC when the session is accepted. Session BC must be terminated. The BC session is terminated with a call into Terminate on the IUccSession value of the TargetReplaceSession property

/// <summary>
/// handles telephone 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">IUccEndpoint Local endpoint</param>
/// <param name="pEventData">UccIncomingSessionEvent incoming session</param>
void _IUccSessionManagerEvents.OnIncomingSession (
    IUccEndpoint pEventSource,
    UccIncomingSessionEvent pEventData)
{
    if (pEventData.Session.Type == UCC_SESSION_TYPE.UCCST_AUDIO_VIDEO)
    {
        DialogResult result;
        // The user agreed to accept the invitation.

        IUccSessionParticipant invitingParticipant = pEventData.Inviter;
        string invitingUser = invitingParticipant.Uri.UserAtHost;
        result = MessageBox.Show(
             "Accept incoming Telephone Call from " + invitingUser + "?",
             "Incoming Call",
             MessageBoxButtons.YesNo);

        if (result == DialogResult.Yes)
        {
            pEventData.Accept();

            //if there is a target replace session, terminate
            //the replaced session after accepting the new session-(pEventData.Session)
            if (pEventData.TargetReplaceSession != null)
            {
                pEventData.TargetReplaceSession.Terminate(
                    UCC_REJECT_OR_TERMINATE_REASON.UCCROTR_UNAVAILABLE,
                    null);
            }
        }

    }
}

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

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