Challenge

Enable an application to process real-time streaming session data generated using Microsoft's real-time communication (RTC) API. 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

For each type of RTC event, obtain and respond to the appropriate information, as outlined below. Note that this item is part of a series about the Microsoft RTC API, which is introduced in the separate item  How to Integrate Real-Time Communications in Windows* XP.

Depending on the session type, there can be RTC media events, audio intensity events, instant-messaging events, or session-state changes. Handling media events requires getting the media type, then getting the event type and reason, and then delivering that message to the session window.

	CAVDConfDlg::OnRTCMediaEvent(IRTCMediaEvent *pEvent)
	{
	... 
	hr = pEvent->get_MediaType(&lMediaType); 
	hr = pEvent->get_EventType(&enType); 
	hr = pEvent->get_EventReason(&enReason); 
	if ((m_AVDlg) && (m_AVDlg.GetState () != RTCSS_IDLE)) 
	{ 
	// Deliver the media state to the session window 
	m_AVDlg.DeliverMedia(lMediaType, enType, enReason); 
	} 
	} 

Intensity events are handled in a fashion similar to media events. Once an intensity event occurs, the application must get the audio device for which the intensity has changed. The application then needs to acquire the level of intensity and the maximum and minimum intensity levels. Once that information is retrieved, intensity level can be readjusted to an appropriate level.

	CAVDConfDlg::OnRTCIntensityEvent(IRTCIntensityEvent *pEvent) 
	{
	...
	hr = pEvent->get_Direction(&enDevice);
	hr = pEvent->get_Level(&lLevel); 
	hr = pEvent->get_Min(&lMin); 
	hr = pEvent->get_Max(&lMax); 
	if (m_AVDlg.GetState () != RTCSS_IDLE) 
	{ 
	// Deliver the intensity state to the session window 
	m_AVDlg.DeliverIntensity(enDevice, lLevel); 
	} 
	} 

Instant messaging information is passed between session participants through the IRTCMessagingEvent interface. When a messaging event occurs, like the media event, the application must acquire the session and event type. It is also necessary to get the participant associated with the session so that the messages can be delivered to the appropriate party. Also handled during the processing of this event are any changes in the participant session state.

	HRESULT CAVDConfDlg::OnRTCMessagingEvent(IRTCMessagingEvent *pEvent) 
	{ 
	... 
	hr = pEvent->get_Session(&pSession); 
	hr = pEvent->get_EventType(&enType); 
	hr = pEvent->get_Participant(&pParticipant); 
	if (enType == RTCMSET_MESSAGE) 
	{ 
	hr = pEvent->get_MessageHeader(&bstrContentType); 
	hr = pEvent->get_Message(&bstrMessage); 
	// Deliver the message to the session window 
	if (m_cMessageDlg) 
	m_cMessageDlg.DeliverMessage(pParticipant, bstrContentType, bstrMessage); 

	}
	else if (enType == RTCMSET_STATUS) 
	{
	hr = pEvent->get_UserStatus(&enStatus); 
	// Deliver the user status to the session window 
	m_cMessageDlg.DeliverUserStatus(pParticipant, enStatus); 
	} 
	return S_OK; 
	} 

Handling session-state changes follows the same process as the other RTC events. The state and session of the RTC client are required to process the state changes. Session-state changes can include setting up a new audio/video session or notifying the client of incoming instant message. In this example, if an incoming request for a communication session is received, the client is notified of the request by a ring, the request is answered, and a communication session is started.

	Void CAVDConfDlg::OnRTCSessionStateChangeEvent(IRTCSessionStateChangeEvent *pEvent) 
	{ 
	... 
	
	hr = pEvent->get_State(&enState); 
	hr = pEvent->get_Session(&pSession); 
	switch ( enState ) 
	{ 
	case RTCSS_INCOMING: 
	{ 
	... 
	
	// This event is called when an incoming call occurs 
	RTC_SESSION_TYPE enType; 
	
	hr = pSession->get_Type(&enType); 
	} 
	} 
	... 
	} 

Starting T120 application sharing is as easy as invoking the StartT120Applet method associated with the IRTCClient interface.

hr = m_pClient->StartT120Applet ( RTCTA_APPSHARING );

Whiteboard support can be added to the application by invoking the StartT120Applet method using the RTCTA_WHITEBOARD enumeration:

hr = m_pClient->StartT120Applet ( RTCTA_WHITEBOARD );

Source

Integrating Rich Client Communications with Microsoft Real-Time Communications API