IBM Lotus Sametime has focused on real-time collaboration in the IBM Lotus collaborative software portfolio for 10 years. It was first released in 1998 as a scalable and secured, real-time communication environment, which was required for enterprise business collaboration.

Lotus Sametime 7.5 was the first commercial product that deployed real-time collaboration technologies on the Eclipse rich client platform (RCP). Because Lotus Sametime 7.5 is based on Eclipse RCP, you can add new features easily through the Eclipse plug-in framework and can extend the Lotus Sametime client beyond what was possible in previous releases of the product.

Lotus Sametime 7.5 and 7.5.1 have other new enhancements in audio-visual communications. Voice chat is a new function in Lotus Sametime 7.5; users can have voice communications with other Lotus Sametime Connect users. Video chat, new in Lotus Sametime 7.5.1, provides visual communication with a Lotus Sametime Connect user. Lotus Sametime users can use these audio-visual communications on Lotus Sametime Connect client as standard functions. You also can use them in their applications which run on Lotus Sametime Connect client and IBM Lotus Expeditor client. With these enhancements, Lotus Sametime is a core product of IBM Unified Communication and Collaboration (UC2) strategy.

Now, Lotus Sametime 8.0, the latest version of the product, released in November 2007, offers additional enhancements to its product features and extensibility. This article describes the Lotus Sametime telephony API and SPI, together with sample programs that use the Lotus Sametime telephony API, which can help you to develop your own audio-visual application over the Lotus Sametime Connect client. The sample program in this article is developed on Lotus Sametime 8.0, and is expected to run on Lotus Sametime 7.5.1 as well.

Overview of the Lotus Sametime telephony service

The Lotus Sametime telephony service includes voice and video chat functions and the click-to-call function.

The voice chat and video chat functions are available as standard functions. The Lotus Sametime Connect client includes a voice and video engine licensed from GIPS (Global IP Solution) and establishes a peer-to-peer voice and video session between the Lotus Sametime Connect clients. The voice and video communication engine can be replaced with other engines provided by other service providers using the Telephony Service Provider Interface (Telephony SPI).

The click-to-call function provides the telephone control capability with an integration with an enterprise PBX or teleconference system on the Lotus Sametime server. The Lotus Sametime Connect user can make a call or start a conference with an operation on the Sametime Connect client. This function also notifies the Sametime Connect client user of an incoming call and displays the caller's information in a new window.

The click-to-call function is provided by a server-side integration module between the Lotus Sametime server and the enterprise PBX and teleconference system. The Lotus Sametime server publishes the Telephony Conference Service Provider Interface (TCSPI), which is used by a service provider, such as the PBX vendor, to develop the integration module (the service provider module). The service provider module connects the Lotus Sametime server and the PBX or teleconference system.

Along with these new features of voice and video chat and the click-to-call functions, Lotus Sametime Client Telephony application programming interface (API) was added to the Lotus Sametime Connect Toolkit. You can develop new applications using the Lotus Sametime voice and video communication capabilities on the Lotus Sametime Connect client and the Lotus Expeditor client.

Figure 1 shows a video chat user interface.

Back to top

Architecture of Lotus Sametime telephony

Figure 2 shows the architecture of the Lotus Sametime telephony service on the Lotus Sametime Connect client and Lotus Sametime server. The click-to-call service consists of both a client-side plug-in and a server-side service provider module. The client-side remote TCSPI plug-in is a component included in the Lotus Sametime product and deals with specific tasks concerning the user interface (UI) on the client. On the server side, the server telephony service provides the click-to-call service on the Lotus Sametime server and accepts the click-to-call request from the client-side plug-in. According to the requests from the client, the telephony service calls the service provider module with TCSPI and controls the PBX or teleconference system.

On the other hand, voice and video chat services consist of client plug-ins that are used only by the Lotus Sametime Connect client. Such plug-ins are shown in Figure 2 as “Voice Chat” and “Voice Chat”. Although the voice and video chat implementations are included in the Lotus Sametime product, you can provide your own implementation for the voice and video chat engine and can replace the existing one. The client-side SPI is available if you choose to develop your own implementation. After the new implementation of the voice and video chat plug-in is provided, the existing plug-in included in Lotus Sametime is disabled automatically.

For all the telephony features, including click-to-call, voice chat, and video chat, the Lotus Sametime Connect Toolkit exposes the client telephony API that you can use to develop your own UI application. This article describes the steps you follow to develop your own video chat application based on the built-in video chat services of the Lotus Sametime product and to add a new user interface.

Back to top

Creating your video chat application

This article describes typical steps to develop a new plug-in application on the Lotus Sametime Connect client by using the Lotus Sametime video chat function. The sample application in this article is a prototype that implements certain interactive applications, such as online games and remote customer support systems, in which two or more people share data and talk using audio-visual communication. Figure 3 shows an example of a customer support application in which a life insurance agent talks to his customer and sees the Web application page on the single Lotus Expeditor client window.

For these types of applications, special UI design might be required, such as the automatic launch of video chat as soon as the application starts up and embedding of the video chat screen side-by-side with the data display in a single application window. The sample application in this article implements these requirements.

The sample application in this article contains a sample implementation for video chat handling in the Lotus Sametime telephony API. You can use this sample to develop an application by combining it with other applications according to your business requirements.

The sample application described in this article is considered to be the first step to developing a real-time collaborative application based on Lotus Sametime.

You can download all the sample program code, which is packaged as single archive file for an Eclipse project; see the link in the Download section of this article. Before importing the archived project, configure to develop the Lotus Sametime Connect plug-in. For the steps to set up the Lotus Sametime Connect plug-in development environment, refer to “Lotus Sametime 8.0 Integration Guide,” which is included in Lotus Sametime 8.0 Software Development Kit.

To test the video chat application in your own environment, you need at least two Lotus Sametime user IDs. If you have your own Lotus Sametime server, you can register as many users as you like for test purposes. Otherwise, you can also have the option to use the Lotus Sametime demonstration server available at the IBM Lotus Sametime 8.0 demo site.

Overview of the sample application

In this article, you develop a simple video chat application, which provides the following features:

• An application that displays as a rectangle area in Lotus Sametime Connect client UI
• Video chat caller, which can specify a recipient and start a video chat on the application UI
• Video chat recipient, which can automatically accept the incoming video chat request
• Embedding of both the local screen and the remote screen in the application UI

Figure 4 shows the application. There are four buttons on the application UI. Using the two buttons in the lower row, you can start a new video chat with the recipient specified in the User ID text field and stop the existing video chat session. The two buttons in the upper row let you start and stop a preview of the local video screen without connecting to the video chat session.

Two video screens for the remote video and local video are shown on canvases at the bottom of the application UI. When you are communicating with the other party, images of you and your video chat partner are displayed on the screens (see figure 4). When you are previewing the local video, you can see only your image, and the remote screen is disabled as shown in figure 5.

Because this article focuses on the steps you take to develop an application over the telephony API, the fundamentals for creating plug-ins and adding SWT components such as buttons and canvases are not described. Refer to the basic articles about extending Lotus Sametime Connect client that are listed in the Resources section.

Back to top

Initiating the video chat

Preparation before starting the video chat

Before you start a video chat session, you need to follow a verification process to make sure that you are ready to start a video chat session and that your recipient is ready to accept the video chat session.

The Lotus Sametime community function included in the Lotus Sametime Connect Toolkit takes care of this verification process. To use the Lotus Sametime community, retrieve the Community class instance from the CommunityService class instance. The sample code in listing 1 shows how you can implement this instance in the constructor of the MainView class of the sample application. The code adheres to the programming standard of the Lotus Sametime Connect Toolkit. See the “Lotus Sametime 8.0 Integration Guide” for more detail. It is included in Lotus Sametime V8.0 Software Development Kit.

/*
 * variables for Sametime
 */
private CommunityService commSrv = null;

private Community community = null;

private LiveNameService lnSrv = null;

private PeopleService ppSrv = null;

Listing 2 provides the code you use to instantiate the community service object.

/*
 * get Sametime CommunityService
 */
try {
	commSrv = (CommunityService) ServiceHub
			.getService(CommunityService.SERVICE_TYPE);
} catch (ServiceException e) {
	e.printStackTrace();

	MessageDialog.openError(PlatformUI.getWorkbench().getDisplay()
			.getShells()[0], "Video Start Listener Exception", e
			.getMessage()
			+ "\nAT: " + this.getClass().toString());

	return;
}

/*
 * get Sametime Community instance
 */
community = commSrv.getDefaultCommunity();

When the user clicks the Start Video Chat button, the sample application starts a video chat with the recipient specified in the User ID field. At the same time, event handling is implemented in the widgetSelected() method of the Listener inner class of MainView.

At first, you must check to be sure you have logged in to the Lotus Sametime community. If you have not logged in, you cannot use any Lotus Sametime services. The code shown in listing 3 calls the isLoggedIn() method of the Community class and checks to make sure that you have logged into the Lotus Sametime community. It displays an error window if you are not logged in.

/*
 * Check if the caller has logged in.
 */
if (! community.isLoggedIn()) {
	MessageDialog.openError(comp.getShell(), 
				"Lotus Sametime error", 
				"Need to login Lotus Sametime");	
	return;
}

Next, check to be sure that the recipient of the video chat call exists and is active in the Lotus Sametime community. Otherwise, your call invitation is not received by the call recipient.

To make these verifications, get the LiveName class object resolved by the LiveNameResolver class instance, and get the LiveName class instance representing the call recipient. If the recipient exists in the Lotus Sametime community and logs in to it, a non-null instance object for LiveName class is returned. Then, get the Person class instance from both the resolved contact ID and the community ID, and check that the user's status is STATUS_AVAILABLE. The status means that the recipient has logged in to the Lotus Sametime community and has active status.

/*
 * check if the participant is available on Sametime
 */
try {	/*
	 * The participant must be resolved with LiveNameResolver to
	 * start video chat
		 */
	lnSrv = (LiveNameService) ServiceHub
			.getService(LiveNameService.SERVICE_TYPE);
	LiveNameResolver lnRes = lnSrv.getLiveNameResolver();
	lnRes.resolve(targetUserId);

	LiveName ln = lnSrv.getResolvedLiveName(targetUserId);
	if (null == ln) {
		MessageDialog.openError(comp.getShell(),
			"Sametime error",
			"LiveName object is null for " + targetUserId);
		return;
	}

	/*
	 * get contact Id and community Id for the user
	 */
	String contactId = ln.getContactId();
	String communityId = ln.getCommunityId();

	/*
	 * get user online status. the participant must be available
	 * to start video chat
	 */
	ppSrv = (PeopleService) ServiceHub
			.getService(PeopleService.SERVICE_TYPE);
	person = ppSrv.getPerson(contactId, communityId, false);

	if (person.getStatus() != LiveName.STATUS_AVAILABLE) {
		MessageDialog.openError(comp.getShell(),
			"Sametime error", "Participant " + targetUserId
				+ " is not active.");
		return;
	}
} catch (Exception e) { ... }

Starting a video chat

Now that you have completed the preparation for video chat, you can start a video chat session and send an invitation to the recipient by using the startVideoChat() method of the VideoCallHandler class as shown in listing 5.

public static void startVideoChat(String placeId, 
					Person targetPerson,
					Canvas remoteCanvas, Canvas localCanvas)
			throws VideoCallHandlerException {
	try {
		/*
		 * create option for video call
		 */
		 .....

		/*
		 * initiates a call using the specified options.
		 */
		 .....

		/*
		 * create address for the participant and
		 * add it to call participant 
		 */
		 .....

		/*
		 * start displaying local and 
		 * remote video for this call on canvases
		 */
		 .....
	
	} catch (TelephonyServiceException e) {
		throw new VideoCallHandlerException(e.getMessage(), e);
	}
}

Some call options are required to create a new Call object, which takes property values for the call. The Community ID property specifies the Lotus Sametime community in which the new video chat call session is created. In this sample program, it is retrieved from the default Lotus Sametime community into which the user has logged.

For any type of collaboration in the Lotus Sametime community, including the video chat, a virtual place is created where users can meet and collaborate. To start a new video chat call, create a new virtual place with a unique place ID, which distinguishes the place from other places. In this sample program, a place ID property value for a video chat is generated from the concatenation of fixed string and random number in the generatePlaceId() method of the MainView class.

A flag representing the video chat session is also set in the call option. See listing 6.

/*
 * create option for video call
 */
String communityId = CommunityUtil.getDefaultCommunity().getId();
Properties properties = new Properties();
properties.setProperty("placeId", placeId);
properties.setProperty("communityId", communityId);
CallOptions options = CallFactory.getInstance().createCallOptions();
options.setProperties(properties);
options.setVideoCall(true);

After you specify these options, the program creates the Call object from the CallManager class instance that has been defined and the instance created in advance. See listing 7.

/*
 * create CallManager for Video Chat.
 */
private static CallManager manager = CallFactory.getInstance()
		.createCallManager(CallManager.SERVICE_TYPE_VIDEO_CHAT);
		 .....

/*
 * initiates a call using the specified options.
 */
Call call = manager.startCall(new Vector(), options, 
				CallListenerImpl.getInstance());

To add the call recipient into the video chat session, you must create an Address object for the recipient and add it to the Call object. In this sample program, the createVideoAddress() method is used to create the Address object from the Person object. Then, you call the addParticipant() method to add the recipient into the call session. See listing 8.

/*
 * create address for the participant and 
 * add it to call participant 
 */
Address address = createVideoAddress(targetPerson);
call.addParticipant(address);

The createVideoAddress() method creates a new Address object and sets the required values for the object. The URL for the recipient that is set by the setAddressUri() method needs to have the prefix video: to adhere to the Lotus Sametime client telephony API specification. See listing 9.

private static Address createVideoAddress(Person person) {

	Address address = CallFactory.getInstance().createAddress();
	address.setAddressUri("video:" + person.getContactId());
	address.setParticipantId(person.getContactId());
	address.setParticipantName(person.getName());
	address.setCommunityId(person.getCommunityId());

	return address;
}

The sample program then calls the startVideo() method to display both the local and the remote video screen for this call on the specified SWT canvases. See listing 10.

/*
 * Start displaying local and 
 * remote video for this call on canvases
 */
call.startVideo(remoteCanvas, localCanvas);

You have completed all the steps for initiating a video chat call. Your call participant should receive a video call invitation from your program now.

Back to top

Attending an incoming video chat

Preparing to receive an invitation

The video chat application is required to implement a function for accepting an incoming video chat invitation. The sample application described in this article provides the simplest steps for the incoming call handling, which means that it accepts any and all incoming video chat invitations.

The incoming video chat invitation is raised as one of the Lotus Sametime call events, so the application has to listen to all such call events. To do so, the CallListenerImpl class is defined as the implementation of the CallListener interface, and it is set to the CallManager class as a listener. It is implemented in the startListening() method of the VideoCallHandler class in the sample program. See listing 11.

public static void startListening() throws VideoCallHandlerException
{
	if(!isListening)
		try {
			manager.addListener(CallListenerImpl.getInstance());
			isListening = true;
		} catch(TelephonyServiceException e) {
			throw new VideoCallHandlerException(e.getMessage(), e);
		}
}

The sample program calls the startListening() of the VideoCallHandler class method in the constructor of the MainView class, if it has already logged in to the Lotus Sametime community. See listing 12.

/*
 * test login status and set CallListener to detect IncomingCallEvent
 */
if (community.isLoggedIn()) {
	try {
		VideoCallHandler.startListening();
	} catch (VideoCallHandlerException e) {
		e.printStackTrace();

		MessageDialog.openError(PlatformUI.getWorkbench().getDisplay()
				.getShells()[0], "Video Start Listener Exception", e
				.getMessage()
				+ "\nAT: " + this.getClass().toString());
	}
}

/*
 * in any case, set community listener to detect logged-in event
 */
commSrv.addCommunityListener(new CommunityListenerImpl());

Because of the internal operational timing, the constructor of the view class can be called before you log in to the Lotus Sametime community. Considering this case, the sample program declares a community listener class to receive a logged-in event and calls the startListening() method.

When the Lotus Sametime Connect client has logged in, the handleCommunityLoginEvent() method is called, which eventually calls the startListening() method to add the call listener.

public void handleCommunityLoginEvent(CommunityLoginEvent ev) {
		
	int type = ev.getType();

	if (CommunityLoginEvent.TYPE_LOGGED_IN == type) {
			
		/*
		 * set call listener
		 */
		try {
			VideoCallHandler.startListening();
		} catch (VideoCallHandlerException e) {
			e.printStackTrace();

			MessageDialog.openError(MainView.getComposite().getShell(),
				"VideoC Start Listening Exception", e.getMessage()
					+ "\nAT: " + this.getClass().toString());
		}
			
	}

		.....
}

Attending the video chat

When a new call event is raised, it is notified using the processCallEvent() method of the CallListener interface. To accept the incoming video chat call, you must implement a proper procedure in the method. The method has to check that this call event is an incoming call event for video chat. In the case of the sample application, it checks if this CallEvent object is an instance of the IncomingCallEvent and if its isVideoCall() flag is true. See listing 14.

public void processCallEvent(CallEvent ev) throws TelephonyServiceException {
		
	if (ev instanceof IncomingCallEvent) {
			
		/*
		 * get IncomingCallEvent object
		 */
		final IncomingCallEvent icEv = (IncomingCallEvent) ev;
		if (! icEv.isVideoCall()) {
			System.out.println("As this is not video call, do nothing");
			return;
		}
			
		/*
		 * get call ID, community Id, and place ID for the incoming call
		 */
		.....
	
		/*
		 * get composite object of main view to show video images on it
		 */
		.....
	
		/*
		 * get local/remote canvases on which video images will be shown
		 */
		.....
			
		/*
		 * call attendVideoChat() to accept the incoming call invitation
		 */
		.....
			
	} else if (CallEvent.EVENT_CALL_TERMINATED == ev.getEventType()) {
		.....
	}
		
}

If the call event is a video chat invitation, the sample gets information from the IncomingCallEvent object such as community ID, place ID, and call ID. See listing 15.

/*
 * get call ID, community Id, and place ID for the incoming call
 */
final String communityId = icEv.getCommunityId();
final String placeId = icEv.getPlaceId();
final String callId = ev.getCallId();

It also gets SWT user interface components from MainView, on which video screens are shown. See listing 16.

/*
 * get composite object of main view to show video images on it
 */
final Composite comp = MainView.getComposite();
			
/*
 * get local/remote canvases on which video images will be shown
 */
final Canvas localCanvas = MainView.getDefault().getLocalCanvas();
final Canvas remoteCanvas = MainView.getDefault().getRemoteCanvas();

Finally, the processCallEvent() method calls the attendVideoChat() method of the VideoCallHandler class to accept the video chat invitation. This operation involves controls on UI components that are not allowed to be executed from threads other than the application's main thread. To solve this problem, this sample program gets the Display object from the main view Composite object and uses the syncExec() method to call the attendVideoChat() method to display video screens on canvases. See listing 17.

/*
 * call attendVideoChat() to accept the incoming call invitation
 */
/*
 * Although the attendVideoChat will call startVideo with Canvas
 * class, it is not allowed for another thread to control a UI
 * component. Therefore, we create another thread to request UI
 * handling in the Composite. Otherwise we will get "ViewPart
 * org.eclipse.swt.SWTException: Invalid thread access"
 */

if ((comp != null) && !(comp.isDisposed())) {
	comp.getDisplay().syncExec(new Runnable() {

		public void run() {
			try {
				/*
				 * accept the incoming video chat invitation
				 */
				VideoCallHandler.attendVideoChat(callId,
						communityId, placeId, localCanvas,
						remoteCanvas);

				/*
				 * set place ID for the incoming video chat session
				 */
				MainView.getView().setPlaceId(placeId);

			} catch (VideoCallHandlerException e) {
				e.printStackTrace();

				MessageDialog.openError(comp.getShell(),
					"Video Attending Exception", e.getMessage()
							+ "\nAT: "
							+ this.getClass().toString());
			}
		}
	});

}

The attendVideoChat() method of the VideoCallHandler class in the sample code looks similar to the startVideoChat() method except that the recipient does not need to generate a new call ID or add another participant. See listing 18.

public static void attendVideoChat(String callId, 
					String communityId,
					String placeId, 
		Canvas remoteCanvas, Canvas localCanvas) 
		throws VideoCallHandlerException {
	try {

		/*
		 * create option for video call
		 */
		 Properties properties = new Properties();
		 properties.setProperty("placeId", placeId);
		 properties.setProperty("communityId", communityId);
		 CallOptions options = CallFactory.getInstance().
		 		 		 createCallOptions();
		 options.setProperties(properties);
		 options.setVideoCall(true);

		/*
		 * initiates a call using the specified options.
		 */
		Call call = manager.connectIncomingCall(callId, options, 
			CallListenerImpl.getInstance());
		calls.put(placeId, call);

		/*
		 * Start displaying both local and 
		 * remote video for this call on canvases
		 */
		call.startVideo(localCanvas, remoteCanvas);
			
	} catch (TelephonyServiceException e) {
			throw new VideoCallHandlerException(e.getMessage(), e);
	}			
}

Now this sample application can accept the incoming video chat that is initiated from a caller's sample application.

Back to top

Conclusion

The Lotus Sametime client telephony API provides programmability that lets you build real-time collaborative applications based on the Eclipse plug-in technology.

As the Lotus Sametime product itself provides high-level scalability and security to meet the requirements of enterprise customers, the Lotus Sametime Connect client has high potential as an enterprise application platform for unified communication and collaboration.

The same client telephony functionality described in this article is also available in embedded Lotus Sametime experiences on IBM Lotus Expeditor 6.1.1 and IBM Lotus Notes® 8.0, You can develop a new type of applications on these platforms with the unified communication and collaboration technology of Lotus Sametime.

Back to top

Download

Information about download methods

Resources

Learn

• Read the developerWorks article, " Extending IBM Lotus Sametime Connect V7.5."
  
  
• Read the developerWorks article, " Developing a location awareness plug-in for IBM Lotus Sametime Connect V7.5."
  
  

Get products and technologies

• Download the Lotus Sametime Toolkit, including libraries, documentation, and sample code.
  
  
• Download the Lotus Sametime V8.0 Software Development Kit (SDK).
  
  

Discuss

• Participate in the discussion forum.
  
  

About the author

Comments (Undergoing maintenance)

Back to top

Trademarks  |  My developerWorks terms and conditions

Table of contents

• Overview of the Lotus Sametime telephony service
• Architecture of Lotus Sametime telephony
• Creating your video chat application
• Initiating the video chat
• Attending an incoming video chat
• Conclusion
• Download
• Resources
• About the author
• Comments

Next steps from IBM

• Try: Lotus Sametime
• Demo: Lotus Notes 8 composite applications
• Webcast: A Smart Approach to Core Banking Renovation in a Tough Economic Climate
• Briefing: Smarter collaboration with IBM Lotus solutions
• Buy: Lotus Sametime

My developerWorks community

Dig deeper into Lotus on developerWorks

Calling all developers

Download no charge Lotus Domino Designer

Special offers