Comparing UCMA 3.0 Call Transfers
Summary: The Microsoft Unified Communications Managed API (UCMA) 3.0 Core SDK provides three kinds of call transfers. This article discusses the details of each call transfer in terms of the SIP messages that are sent and received.
Applies to: Microsoft Unified Communications Managed API (UCMA) 3.0
Published: February 2012 | Provided by: Mark Parker, Microsoft | About the Author
Contents
Call Transfer Terminology
Call Transfers
Additional Resources
Call Transfer Terminology
In a typical call transfer scenario, Adam places a telephone call to Bill, to find the answer to a technical question. Bill is unfamiliar with the area of the question, and transfers the call to Carol, who has more expertise in the matter. The following list defines the terms that are used for the three parties involved in this call transfer.
Transferee—the party whose call is transferred (Adam).
Transferor—the party who performs the transfer (Bill).
Transfer target—the party to whom the call is transferred (Carol).
Call Transfers
UCMA provides three kinds of call transfer: unattended transfer, attended transfer, and supervised transfer.
Unattended transfer
In an unattended transfer (also known as a blind transfer), the platform completes the transfer and terminates the call between the transferor and transferee immediately after it receives notification (a 202 Accepted response code) that the REFER message was accepted.
Attended transfer
In an attended transfer, the platform monitors the progress of the transfer and finishes the transfer after it receives a notification of success.
Supervised transfer
A supervised transfer is an attended transfer in which a call is provided. The call typically is an instance of the InstantMessagingCall or AudioVideoCall class.
All three transfer types use one of the overloaded BeginTransfer methods on the Call class or on the classes that inherit from the Call class, the InstantMessagingCall and AudioVideoCall classes.
At the SIP message level, to start the transfer, the transferor sends a REFER message to the transferee. The different behavior of the three transfer types are described in the following sections.
Unattended Call Transfer
An unattended transfer is performed by using the BeginTransfer method. The TransferType property on the CallTransferOptions object that is the second parameter is set to CallTransferType.Unattended for an unattended transfer.
Note
In the following example, the definition for a callback method named transferCallback is not shown.
CallTransferOptions transferOptions = new CallTransferOptions(CallTransferType.Unattended);
String transferUserURI =″sip:adam@contoso.com″;
call.BeginTransfer(transferUserURI, transferOptions, transferCallback, state);
Figure 1 shows the SIP message flow for an unattended call transfer. To simplify the illustration, SIP messages that are unrelated to call transfer are omitted. The call between the transferor and transferee is assumed to be already established and in progress, and only the SIP messages from the REFER message onward are shown. The numbers in parentheses match the numbers in the list that follows.
Figure 1. SIP message flow in an unattended call transfer
The SIP message flow that is shown in figure 1 starts when the transferor sends a REFER message to the transferee. The Refer-To header field in the NOTIFY message contains the SIP URI of the transfer target, and the Referred-By header field in the NOTIFY message contains the SIP URI of the transferor.
After the transferee accepts the REFER message, it responds by sending a 202 Accepted response code to the transferor.
The transferee sends an INVITE message to the transferor. Inside the Session Description Protocol (SDP) content is a line that contains “a=inactive”. The effect of this line is to put the transferor on hold.
The transferor sends a SUBSCRIBE message to the transferee. The transferee responds with a 200 OK response code. Other response codes are possible.
The transferee sends a NOTIFY message to the transferor. The NOTIFY message contains a message/sipfrag part whose content is “SIP/2.0 100”, which indicates that the REFER message of step 1 is pending. The transferor responds by sending a 200 OK response code. Other response codes are possible, such as 481 Call Leg Terminated.
The transferee uses the URI that is contained in the Refer-To header field of the REFER message (step 1) to determine the transfer target. The transferee then sends an INVITE message to the transfer target. The INVITE message contains the Session Description Protocol (SDP) offer to the transfer target. The transfer target responds with several response codes in succession:
100 Trying
180 Ringing
183 Session Progress
The transferor sends a BYE message to the transferee. The transferee responds by sending a 200 OK response code. The BYE message and the 200 OK response code indicate that the transferor’s role in the call transfer is finished.
The transferee sends a PRACK message (provisional acknowledgement) to the transfer target. The transfer target responds by sending a 200 OK response code.
The transfer target responds with an SDP answer to the previous INVITE message by sending a 200 OK response code back to the transferee.
The transferee sends an ACK message to the transfer target.
After the offer-answer negotiation of media capabilities in the first INVITE call sequence, the transferee sends a second INVITE to the transfer target. The transfer target responds by sending 100 Trying and 200 OK response codes. At this point the transferee and transfer target can start talking to one another.
Attended Call Transfer
Attended transfers and unattended transfers are performed by using the same method: BeginTransfer. The difference between the two transfers is in the value of the TransferType property on the CallTransferOptions object that is the second parameter. A value of CallTransferType.Attended is used in an attended transfer, and a value of CallTransferType.Unattended is used in an unattended transfer.
Figure 2 shows the SIP message flow for an attended call transfer. To simplify the illustration, SIP messages that are unrelated to call transfer are omitted. The call between the transferor and transferee is assumed to be already established and in progress, and only the SIP messages from the REFER message onward are shown. The numbers in parentheses match the numbers in the list that follows.
Figure 2. SIP message flow in an attended call transfer
The SIP message flow that is shown in figure 2 starts with the REFER message that the transferor sends to the transferee.
The call transfer begins with the REFER message that the transferor sends to the transferee. This message contains a Refer-To header that specifies the destination of the transfer, and a Referred-By header, that specifies the transferor.
The SIP message flow that is shown in figure 2 starts when the transferor sends a REFER message. The Refer-To header field in the NOTIFY message contains the SIP URI of the transfer target, and the Referred-By header field in the NOTIFY message contains the SIP URI of the transferor.
After the transferee accepts the REFER message, it responds by sending a 202 Accepted response code to the transferor.
The transferee sends an INVITE message to the transferor. Inside the Session Description Protocol (SDP) content is a line that contains “a=inactive”. The effect of this line is to put the transferor on hold.
The transferor responds to the INVITE message of step 3 by sending the transferee a 100 Trying response code, followed by a 200 OK response code.
The transferee sends an ACK message to the transferor.
The transferee sends a NOTIFY message to the transferor. The NOTIFY message contains a message/sipfrag part whose content is “SIP/2.0 100”, which indicates that the REFER message of step 1 is pending. The transferor responds by sending a 200 OK response code. Other response codes are possible, such as 481 Call Leg Terminated.
The transferee uses the URI that is contained in the Refer-To header field of the REFER message (step 1) to determine the transfer target. The transferee then sends an INVITE message to the transfer target. The INVITE message contains the Session Description Protocol (SDP) offer. After receiving the INVITE message, the transfer target responds with several response codes in succession:
100 Trying
180 Ringing
183 Session Progress
The transferee sends a PRACK message to the transfer target, after which the transfer target responds by sending a 200 OK response code to the transferee.
The transfer target responds with an SDP answer to the previous INVITE message by sending a 200 OK response code back to the transferee.
The transferee sends an ACK message to the transfer target.
The transferee sends a NOTIFY message to the transferor. The Subscription-State header field contains “terminated”. The message/sipfrag part contains a 200 OK response code and other information. A short while later, the transferor responds to the transferee by sending a 200 OK response code.
The transferee sends a BYE message to the transferor. The transferor responds to the transferee by sending a 200 OK response code.
After the offer-answer negotiation of media capabilities in the first INVITE call sequence, the transferee sends a second INVITE to the transfer target. The transfer target responds by sending 100 Trying and 200 OK response codes. At this point the transferee and transfer target can start talking to one another.
Supervised Call Transfer
A supervised transfer is performed by using the BeginTransfer method. The second parameter in the call to the BeginTransfer method is a value in the CallTransferType enumerated type. The default value is CallTransferType.Attended, which means that the two calls to the BeginTransfer method in the following sample are equivalent.
Note
In the following example, it is assumed that callToTransfer is a call instance in the Established state. The definition for the callback method named transferCallback is not shown.
CallTransferOptions transferOptions = new CallTransferOptions(CallTransferType.Attended);
call.BeginTransfer(callToTransfer, transferOptions, transferCallback, state);
call.BeginTransfer(callToTransfer, null, transferCallback, state);
Note
The BeginTransfer method throws ArgumentException if the second parameter is CallTransferType.Unattended.
Figure 3 shows the SIP message flow for a supervised call transfer. For the sake of simplicity, SIP messages that are unrelated to call transfer are omitted. The SIP message flow for a supervised transfer is identical to that for an attended transfer. The principal difference is in the REFER message, which is discussed later.
Figure 3. SIP message flow in a supervised call transfer
In a supervised transfer the Refer-To header in the REFER message specifies a REPLACES parameter.
REFER-TO: <sip:carol@contoso.com;opaque=user:epid:ffYY9pMqvVuykPrZ3LufkwAA;gruu?REPLACES=40226f39-bf1c-4432-afe7-a20b34a71c34%3Bfrom-tag%3D61b438ec2e%3Bto-tag%3D28700f7b9a>
The Referred-By header in the REFER message specifies the transferor.
REFERRED-BY: <sip:bill@contoso.com>
The INVITE message that the transferor sends to the transfer target has a Replaces header field that contains the same information.
Replaces: 40226f39-bf1c-4432-afe7-a20b34a71c34;from-tag=61b438ec2e;to-tag=28700f7b9a
Additional Resources
For more information, see the following resources:
About the Author
Mark Parker is a programming writer at Microsoft Corporation. His principal responsibility is the UCMA SDK documentation.