VOIP

We begin this article by answering a few questions. Namely, what is VoIP? What is Skype? And why would you want to integrate these capabilities into your PowerBuilder applications?

We will begin with the latter. Imagine that you are a field service worker armed with a tablet PC with a wireless broadband connection and you want to call your next client from your appointment list. You could just use your cell phone, but that would require you to look up and dial the number independent of your application. However, imagine an integrated solution whereby you could click on the next appointment and have your application automatically dial that contact. This is where Skype and VoIP come in. By integrating VoIP capabilities into our PowerBuilder applications, it's now possible to call someone directly from within our programs. This article will show you how.

For starters, VoIP is an acronym for Voice over Internet Protocol. In a nutshell, it allows you to make a call via your computer through an Internet connection. We won't get into the specifics of how it works but, if you are interested in learning more, I would encourage you to check out http://computer.howstuffworks.com/ip-telephony.htm.

The other component is Skype (see Figure 1), which is a program that enables you to make calls over the Internet to anyone else who has it. It's free and easy to use and works with most computers. It also has the capability of making inbound and outbound calls to and from landlines (although there is a charge of about 2¢ a minute). To try it out, you can download it from www.skype.com/download/.

We'll cover three of the methods to initiate a basic phone call. They are:

1. linkto
2. SkypeX ActiveX control
3. Native Skype API

The first two methods are trivial so we won't spend a lot of time on those. Rather, we will spend the majority of our time examining the core Skype API and how to use it.

To complete this exercise you'll need the following items.

• A wireless broadband Internet connection
• A copy of Skype, downloadable here:
  www.skype.com/download/
• A copy of the SkypeX ActiveX control, downloadable here:
  www.beesync.com/downloads.html
• A copy of Skype API documentation, downloadable here:
  http://share.skype.com/developer_zone/documentation/documentation/
• PowerBuilder 9.x
• Some time to learn!

After reading this article you should be able to make a simple phone call using any of the aforementioned methods. We'll also briefly cover the Microsoft Messaging Service and how it's used as a transport mechanism for the Windows Skype API implementation. In addition, for the Skype API you can learn a little bit about some of the commands available by looking here: http://share.skype.com/sites/devzone/2006/01/ api_reference_for_skype_20_bet.html#COMMANDS.

That being said, let's go step-by-step to see how to create a simple but functional example that will illustrate the basic concepts you'll need to know (see Figure 2).

SETUP
Create a main window and drop the following controls on it: a multi-line edit, a static hyperlink, a single line edit, two command buttons, and a SkypeX ActiveX Control.

METHOD 1
Code for the linkto method by adding the following code to the clicked event of the static hyperlink.

//adjust our url to make an outbound phone call
shl_call.url = 'CALLTO:' + sle_phonenumber.Text

Run your project and click on the link. You have just made your first VoIP call.

METHOD 2
Code for the Active-X method by adding the following code to the clicked event of one of your command buttons.

//another easy way to make a phone call
ole_skype.object.PlaceCall(sle_phonenumber.Text)

You have just made your second VoIP call.

Easy enough, but suppose you wanted to do more than just make a simple phone call? Here is where the Active-X control can help us. This control is loaded with just about anything you would want to do. You can check out the documentation for all its methods and properties. The only thing you may not be used to is the format of the documentation, which may be somewhat intimidating to the non-C++ crowd. It's generated from IDL files and may be a little hard to follow until you get used to it. The nice thing though is they have all their examples in VBScript, which is close enough to PowerScript to get a good grasp on the code examples. This control is free for educational or non-commercial uses. However, if you want to distribute it with your applications, it will set you back about $50. One word of caution: to locate a Skype user, they use a property called Handle. This of course is a problem for us PB folks since that's a reserved word.

In general, I might note, there are also some other downsides to consider when using a third-party Active-X control. They are:

1. It may not be updated in a timely manner when the API changes.
2. You have to pay for it.
3. You have to deploy it.

METHOD 3
Interface directly with the Skype API. For this one, we'll have to do a little work. Before we start though, it might be useful to explain a little bit about how you go about communicating with the API in the first place. There are no DLLs, rather, it's a message-based system that utilizes the Microsoft Messaging Services. If you're not familiar with it, check out this site: http://msdn.microsoft.com/library/default.asp?url=/library/ en-us/winui/winui/WindowsUserInterface/Windowing/MessagesandMessageQueues.asp.

To begin, we'll need to initiate communication with the Skype server by sending out a "discovery" message. This is shown in Listing 1. Here we're using the Win32 API call RegisterWindowMessage(). This tells Windows to return a unique message identifier for the string we pass in. In this case, we are interested in the two messages SkypeControlAPIDiscover and SkypeControlAPIAttach. We'll use the SkypeControlAPIAttach message ID to determine if the Skype Server is ready to process our commands.

To actually send the message use another Win32 API call, SendMessage(). This does the actual work of sending the discovery message. The constant WM_BROADCAST_MESSAGE tells Windows to send the message to all open windows. Why send the message to all windows? If you look at the prototype of SendMessage(), it takes a handle to a window as one of its parameters. However, since we don't know the handle of the Skype server yet, we'll need to send a message to all windows. Later on, Skype will return its handle back in the Message.WordParm. Save this value and use it for subsequent calls to SendMessage().

The prototypes for the API calls are listed below:

• Function long RegisterWindowMessage(string msg) library "user32.dll" Alias for "RegisterWindowMessageA"
• Function long SendMessage( long hWnd, ulong Msg, ulong wParam, long lParam ) Library "user32" Alias For "SendMessageA"

The next question is: How do we receive messages from Skype? The answer is in the PowerBuilder "other" event. The "other" event is used to capture any Windows messages that are not already caught by PowerBuilder. A little-appreciated fact about this event is that it slows down all processing for that window. Say you used an application window, that would definitely have a performance impact since it would be busy processing every Windows message not already caught by PowerBuilder. Thus an improvement might be to have the Skype handler in a dedicated window that's kept invisible. That would have the least effect on the overall application performance.

Perhaps a look at the code in the "other" event used to process the discovery message sent back by Skype would be useful at this point. For that, refer to Listing 2. Note, for simplicity sake, we are not using an invisible window as suggested earlier. This may become apparent in your testing in that Skype may occasionally not respond to your commands. This is particularly true if you try to run your project within the IDE. This is because if Skype does not receive a reply within one second, it times out.

Given that Skype is ready to start receiving commands, we need a way to send them. For that see Listing 3. Note that we have written a generic function that can send any Skype command. Two points are important here: we are using SendMessage() to communicate with Skype and the message we are sending is defined as WM_COPY_DATA_MESSAGE. Both are defined in the MSDN library. If you look at the code, you can see that we are populating the copy data structure with the message we wish to send. There are two important parameters: the size of the data as well as a pointer to the data. Note: when taking the size of the data, we must add one because the Len() function does not take into account the required null terminating character. What about that pointer? That's a little tricky. PowerBuilder manages application memory like Java and C#, which hides the complexities of pointers from us. Thus, we have this code:

//trick for getting ptr to string
ll_StringPointer = LocalAlloc( 0, Len( ls_Buffer))
lStrCpy( ll_StringPointer, ls_Buffer )

Here you can see we are using two Win32 API calls for getting a pointer to the command string we are going to send. Their prototypes are shown below:

• Function long LocalAlloc(long Flags, long Bytes) library "kernel32.dll"
• Function long lstrcpy(long Destination, string Source) library "kernel32.dll"