Using a Third Party Media Stack with RTC (Windows Embedded CE 6.0)

1/5/2010

The RTC Client API includes a SIP stack for signaling. The RTC Client API also includes code to transfer audio data over RTP.

Out of the box, the VoIP Phone Suite sends and receives audio data using the media transport functionality included with the RTC Client API. However, the VoIP Phone Suite is also built to make it relatively easy to plug in alternative media transport code and continue to use the rest of the VoIP Phone Suite in its entirety, without change.

For example, if your company has purchased an RTP stack that transports data using a different RTP implementation or entirely different protocols, you could plug in that RTP stack.

Three Media Stack Scenarios

There are three scenarios for using a different media stack:

1. You also need or want to use a different SIP stack. In this situation, you cannot use the RTC Client API. RTC can only use its own SIP stack implementation.
2. You are using the RTC SIP stack but wish to use a different media stack from the native one used by RTC. In this case, you would disable RTC's media stack and use your own instead.
3. You are using the RTC SIP stack but want to use both the RTC media stack and your own media stack. In this situation, you are being given first look at the SDP information and you then decide whether to handle the media yourself, with your own media stack, or to let RTC handle it. This situation might come up if you accept both audio and video calls and you want to let RTC handle pure audio calls but want to use your own video capable media stack if the incoming call is a videophone call. RTC does not currently implement video support.

In the first scenario, you will not be using RTC and should be following the procedures that your custom SIP and media stack software requires.

In the second, you will be disabling the RTC media stack and creating an "application" session, rather than a "PC-to-PC" session as with the default RTC media stack case. You will need to use IRTCClient2::CreateSessionWithDescription in this situation.

In the third and final scenario, you are not disabling the RTC media stack. Instead, you will be calling IRTCClient2::SetSessionDescriptionManager in order to get RTC to send you the SDP message first so that you can look at it and decide whether or not to handle it yourself. If you do not handle it yourself and it is of a type that RTC does not support, like video, then RTC will reject the call.

Scenario 2: Disabling the RTC media stack and using a custom media stack

The process for setting up a session where you would use a different media stack would look like the following:

THE CALLING PARTY

• After you have co-created your IRTCClient, you would query for the IRTCClient2 interface.
• You would then call the method IRTCClient2::InitializeEx with RTCIF_DISABLE_MEDIA, where RTCIF_DISABLE_MEDIA is one of the flags you pass, along with any other flags you need, during the initialization. For example, you might want to enable early media scenarios or symmetric UDP as well during this time.
• The RTC media stack is now disabled.
• To make an outgoing call, since you have disabled the RTC media stack, you cannot call, as usual, IRTCClient::CreateSession , even using for your session type, RTCST_APPLICATION rather than the typical RTC "PC-to-PC" session, i.e. RTCST_PC_TO_PC. For more information, please see RTC_SESSION_TYPE.
• Instead, to make an outgoing call, you will use IRTCClient2::CreateSessionWithDescription. This method enables your client application to control the session and specify the body and content type of the session INVITE request.
• Using your session object, you would call IRTCSession::AddParticipant or IRTCSession3::AddParticipantEx to begin your call.
• Remember, at some point, you would have had to setup your custom media stack and be ready to respond to events using it.

THE RECEIVING PARTY

• The called party will then receive an IRTCSessionStateChangeEvent indicating that the session state has changed to RTCSS_INCOMING. The called party can obtain the session object from the IRTCSessionStateChangeEvent::Session method. The called party can then query the session object to get the session type, which is always RTCST_APPLICATION for sessions with application-defined media negotiations. They can also call the IRTCSessionStateChangeEvent2::GetRemoteSessionDescription method to obtain the session description.
• The called party can accept the call by calling the IRTCSession2::AnswerWithSessionDescription method, passing the content type and a new session description back to the application that created the call.
• Once the session is connected, the called party can query the session object for the called party's session description by calling the IRTCSessionStateChangeEvent2::GetRemoteSessionDescription method.

DURING THE SESSION (EVENT HANDLING FOR BOTH CALLING AND RECEIVING PARTIES)

• You would respond to incoming events as usual. The events may be different than the ones under a "PC-to-PC" session. For more information, please see RTC_EVENT and RTC Events.

For more information on RTCIF_DISABLE_MEDIA, please see RTCIF_.

Scenario 3: Using the RTC media stack as well as a custom media stack

The process for setting up a session where you would use a different media stack would look like the following:

THE CALLING PARTY

• After you have co-created your IRTCClient, you would query for the IRTCClient2 interface.
• You would then call the method IRTCClient2::InitializeEx but not disable the media stack. You would include any flags you need here, for the initialization. For example, you might want to enable early media scenarios or symmetric UDP as well during this time.
• The RTC media stack is still enabled. It is not disabled, nor will it be in this situation.
• You would also call IRTCClient2::SetSessionDescriptionManager with a pointer to the your application's implementation of the IRTCSessionDescriptionManager interface. The interface allows the RTC Client API to supply your application with the session description protocol (SDP) session information, such as the content type and body of an incoming INVITE request. You can then decide to handle the SDP negotiation for the session or let the RTC Client API handle the negotiation.

INCOMING CALLS

• The interface method, IRTCSessionDescriptionManager::EvaluateSessionDescription will be called by RTC on an incoming call. If you set the incoming variable, pfApplicationSession, to TRUE and return S_OK, then that means that your application will handle the session using your custom media stack and the session type will change to RTCST_APPLICATION. If you set it to FALSE and return S_OK, then that means that RTC will handle the session as normal using its own media stack.
• You will then receive an IRTCSessionStateChangeEvent indicating that the session state has changed to RTCSS_INCOMING. You can obtain the session object from the IRTCSessionStateChangeEvent::Session method. You can then query the session object to get the session type, which is always RTCST_APPLICATION for sessions with application-defined media negotiations. You can also call the IRTCSessionStateChangeEvent2::GetRemoteSessionDescription method to obtain the session description.
• You can accept the call by calling the IRTCSession2::AnswerWithSessionDescription method, passing the content type and a new session description back to the application that created the call.
• Once the session is connected, you can query the session object for the called party's session description by calling the IRTCSessionStateChangeEvent2::GetRemoteSessionDescription method.

OUTGOING CALLS

• To make an outgoing call using the RTC media stack, you would use, as normal, IRTCClient::CreateSession.
• To make an outgoing call when you want to use your own media stack (not RTC's), you would call, not as in the previous usual way, IRTCClient2::CreateSessionWithDescription. This method enables your client application to control the session and specify the body and content type of the session INVITE request. In this case, for your session type, you are by default, using session type, RTCST_APPLICATION. There is no parameter that you set for this in the API call, as there is with IRTCClient::CreateSession. For more information, please see RTC_SESSION_TYPE.
• Using your session object, you would call IRTCSession::AddParticipant or IRTCSession3::AddParticipantEx to begin your call.
• The called party is now responding as you would on an incoming call, determining whether to handle the media with a custom stack or use RTC, if the called party has setup that capability. See the RECEIVING PARTY section of Scenario 2, above, as well.

DURING THE SESSION (EVENT HANDLING)

• You would respond to incoming events as usual. The events may be different than the ones under a "PC-to-PC" session. For more information, please see RTC_EVENT and RTC Events.

A complete, detailed description of the procedure to use a custom media stack with RTC can be found on this Microsoft Web Site.

More Information

For more information about scenarios involving a different SIP stack or for using RTC for presence, including links to other sources of information, please see the related article, Configuration Scenarios for the RTC SIP Stack.

For additional information, see Customizing Non-UI IP Phone Functionality.

See Also

Tasks

How to Develop a VoIP Phone

Other Resources

Common VoIP Phone Customization Tasks
Real-time Communications (RTC) Client API