Accepting a Transferred Session

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.

Telephone calls can be transferred from person to person using a Unified Communications (UC) server together with an organization PBX hardware if an involved endpoint is a PSTN telephone. UC-enabled phone to UC-enabled phone session transfers are handled entirely by a Unified Communications server. The Unified Communications Client API exposes methods that enable a UC telephone and a PSTN telephone to emulate a PBX call transfer. An audio or audio/video session can be transferred from user to user in one of two ways:

• Blind Transfer. The transfer target does not receive prior notification that a session is to be transferred. The transferring user simply names the user receiving the transfer by specifying the target telephone number and initiates the transfer.
  The blind transfer operation raises an OnIncomingTransfer event on the local client. This incoming transfer event provides the identity of the transferring user and the user being transferred.
• Consultative Transfer. The intended recipient receives a session from the transferring user to allow a consultation prior to the transfer operation. If a transfer is agreed to, the transferring user is dropped out of the session and replaced by a different remote user. In this way, the transferring user connects one remote user with the other.
  The consultative transfer operation involves the OnIncomingSession, OnAddParticipant, and OnRemoveParticipant events.

Blind Transfer

Accepting a blind transfer session from a remote Unified Communications Client API client amounts to processing the OnIncomingTransfer event raised when the blind transfer is received. Like the OnIncomingSession event raised on the initial receipt of a call, the incoming call transfer event provides a session (IUccSession) representing the audio/video or audio call transferred to the local client. The event source parameter is the incoming session and the event data parameter is an interface that exposes the SIP URI of the referring user and the SIP URI of the user being transferred to the local client.

After a transfer is accepted, application code should determine the session type and execute logic accordingly.

The event data interface, IUccIncomingSessionTransferEvent, is derived from the IUccIncomingRequestEvent interface and as such, exposes accept/reject functionality. The local client can choose to accept a transfer by calling the Accept method. A transfer can be rejected with a call to the Reject method.

Example

The following example demonstrates the acceptance of a transferred call and examination of the event argument properties identifying the transferring and transferred users. It is possible to transfer a call that has been conferenced and has multiple participants. For this reason, the example callback function iterates on the participant collection to extract the Uri property of each transferred user. One of the session participants is the local user himself. The IsLocal property is examined to determine the local participant. The session is transferred when the Accept method is called and the local user begins to receive an audio or audio/video media stream from the transferred user.

void _IUccSessionCallControlEvents.OnIncomingTransfer(
    IUccSession pEventSource, 
    UccIncomingSessionTransferEvent pEventData)
{
    string transferringUser = pEventData.ReferredBy;
    StringBuilder sb = new StringBuilder();
    foreach (IUccSessionParticipant sp in pEventSource.Participants)
    {
        if (sp.IsLocal == false)
            sb.Append( sb.Length == 0 ? sp.Uri: ", " + sp.Uri.Value);
    }
    string transferredUser = sb.ToString();
    DialogResult result = MessageBox.Show(
        "Incoming call transfer from " 
        + transferringUser.Trim()
        +". Transferred user is  "
        + transferredUser.Trim()
        + " Accept? ",
        "transferred Session",
        MessageBoxButtons.YesNo);

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

Consultative Transfer

Accepting a consultative transfer from a remote user amounts to handling the OnIncomingSession event generated by a remote user initiating the consultation, the OnRemoveParticipant that is raised when the transferring user is removed from the session, and the OnAddParticipant raised for each session participant added to the session. If a conferenced session is transferred to the local user, the OnAddParticipant event is raised for each member of the conference session.

Example

The following example demonstrates handling the participant events. These events are raised on the session received from the transferring user. The local user must advise for the session events to receive these events. It is not necessary for the local user to handle these events to complete the transfer. To review an example of a callback function that handles OnIncomingSession, see Handling Session Invitations.

void _IUccSessionEvents.OnAddParticipant(
    IUccSession pEventSource,
    IUccOperationProgressEvent pEventData)
{
    StringBuilder sb = new StringBuilder();
    foreach (IUccSessionParticipant sp in pEventSource.Participants)
    {
        if (sp.IsLocal == false)
           sb.Append( sb.Length == 0 ? sp.Uri: ", " + sp.Uri.Value);
    }
    if (sb.Length > 0)
        MessageBox.Show(sb.ToString() + " has been transferred");
}

void _IUccSessionEvents.OnRemoveParticipant(
    IUccSession pEventSource,
    IUccOperationProgressEvent pEventData)
{
    if (pEventSource.Participants.Count <= 1)
    {
        if (pEventSource == this._session)
            this._session.Terminate(UCC_REJECT_OR_TERMINATE_REASON.UCCTR_NORMAL, null);
    }
    else
    {
         MessageBox.Show("A participant has been removed from the sesion");
    }
}

See Also

Concepts

Holding and Transferring Sessions
Handling Session Invitations
Session Creation