Initiate a Microsoft RTC Session in Windows XP

Product Index
Search

Intel® Software Network

Language:
- English

	November 24, 2008 11:00 PM PST

Challenge

Use Microsoft's real-time communication (RTC) API to enable an application to initiate a communication session with another participant. The RTC API enables developers to enhance the communication capabilities of any Microsoft Windows* XP-based application. It provides the developer with the building blocks to add instant messaging, voice and video-conferencing, and application sharing/collaboration capabilities to applications.

Solution

Enable the application to handle RTC events, including processing the WM_RTC_EVENT event, and implement the IRTCSession interface. Note that certain preparations are necessary before using the contents of this item; this item is part of a series that is introduced in the separate item "How to Integrate Real-Time Communications in Windows* XP".

Before the application can connect to other participants, the application needs to be able to process the events that RTC fires off during the session. Since the focus of this series of items is on PC-to-PC communications, the application traps events for instant messaging, volume intensity, media, client messages, and session-state changes. This is accomplished by creating an event filter mask that includes all the client session communication types the application utilizes.

// Set the event filter to listen for RTC events

// Using RTCEF_ALL will set for all events 

// For the sample application, we will demonstrate how to set the 

// event listener for a limited set of events

long lEventMask = RTCEF_SESSION_STATE_CHANGE | 

RTCEF_MESSAGING | 

RTCEF_MEDIA | 

RTCEF_INTENSITY |

RTCEF_CLIENT; 


		
hr = m_pClient->put_EventFilter( lEventMask );
 


// Create the event sink object 

m_pEvents = new CRTCEvents;

// initialize the event handler 

hr = m_pEvents->Advise( m_pClient, m_hWnd );

// Set the listen mode for RTC client 

// RTCLM_BOTH opens the standard SIP port 5060, as well as

// a dynamic port

hr = m_pClient->put_ListenForIncomingSessions(RTCLM_BOTH);

It is important to understand that the audio and video codec types can change during a session, so the client always must watch for these types of events.

To handle RTC events sent between session participants, the application must process the WM_RTC_EVENT event. In this example, the application listens for the WM_RTC_EVENT event and forwards the message to the function OnRTCEvent() whenever it occurs. Handling the event requires the application to create the appropriate interface for each RTC interface used.

For example, if an RTCMediaEvent is processed, an IRTCMediaEvent interface needs to be created. This is done by calling QueryInterface using the IID_IRTCMediaEvent GUID. After the interface is created, it is used to further process the event. The code below illustrates this point:

OnRTCEvent(UINT message, WPARAM wParam, LPARAM lParam)

// Based on the RTC_EVENT type, query for the 

// appropriate event interface and call a helper 

// method to handle the event 

switch ( wParam )

.... 

.... 

.... 

case RTCE

MEDIA:
 
{ 

IRTCMediaEvent * pEvent = NULL;

hr = pDisp->QueryInterface( IID_IRTCMediaEvent,

(void *)&pEvent ); 

if (SUCCEEDED(hr)) 

{ 

OnRTCMediaEvent(pEvent); 

SAFE_RELEASE(pEvent);
 
} 

} 

break; 

.... 

.... 

.... 

}

Once the events processing is enabled, the functionality for placing a call needs to be implemented. To place a call with RTC, the application must create and initialize a communication session. Then a call may be placed by entering the IP address of the participant. It is also possible to activate a communication session by entering an email address or a telephone number. However, this functionality requires a SIP registrar sever, which is outside the scope of this item.

Currently, RTC does not support multi-party video conferencing sessions. Due to this limitation, the application needs to verify that a video-conferencing session is not already underway prior to a new session being initiated. In this release, the Windows RTC client does provide support for multi-party voice communication sessions.

To make a call to another PC, identify the RTC session type and create a session of that type using the IRTCSession interface. The code below illustrates how to create the session:

HRESULT CAVDConfDlg::MakeCall(RTC_SESSION_TYPE enType, BSTR bstrURI) 

{

...

// Create the session 

IRTCSession * pSession = NULL;

hr = m_pClient->CreateSession(enType, NULL, NULL, 0, &pSession);

// Add the participant to the session

hr = pSession->AddParticipant(bstrURI, NULL, &m_Participant); 

// Add the session to the session list & create the session window 

hr = AddSession(pSession, enType);

return S_OK;

}