Developing Palm OS network applications is hardly different from standalone applications. Debugging network applications is a different story. The majority of standalone applications can be debugged directly on the device using either the CodeWarrior or PRC tools debugger. The debugger uses the Palm Serial Link protocol to communicate with the device over the serial port. Network applications need the same serial port to access the network.
Fortunately there are solutions that allow you to debug and test your network application. The Palm OS Emulator (POSE) provides a virtual device that runs on a desktop and allows developers using either CodeWarrior or PRC tools to debug their network applications at the source level. Mochasoft’s MochaPPP simplifies testing by letting the device share the host desktop’s network protocol stack. We will discuss each of these tools in turn.
POSE emulates a Palm device at the hardware level. In fact, it emulates a wide range of Palm and Palm-compatible devices, using images of the actual device ROMs. POSE enables source-level debugging of all Palm applications, especially network ones.
Palm, Inc. provides versions of the Palm OS Emulator for Windows and Mac OS; it has also been ported to Linux. This tool is available on both the Windows and Macintosh platforms. The source code is available for Unix developers; they must build the tool themselves. POSE can be used with either CodeWarrior or the PRC tools. You should be sure to use either the most recent version, or the second-most recent version. At the time of this writing, the current version is 3.2. POSE is available for download from the Palm OS web site at http://www.palmos.com/dev/tech/tools.
Tip
It’s a good idea to wait until the newest version of POSE has been out for a few months before using it to test your code in case something really important breaks. This is our policy for all debugging tools, and we never change any tools once a project enters Beta testing.
If all POSE did was emulate the device and allow you to debug your application without recourse to the device, it would be an incredibly useful tool. But wait, there’s more. POSE allows you to easily capture screenshots of your application; all the screenshots in this book were captured with POSE. Also, it provides warnings of commonly missed programming bugs—invalid memory access, use of null pointers, and a host of other easily missed mistakes. And it also provides sophisticated profiling tools.
It is hard to imagine developing Palm OS software without the emulator; all the examples in this book were tested and debugged on it. Although POSE provides a remarkably accurate emulation of Palm devices, it is essential that you test your application on the target device with the expected network connectivity. The example applications underwent final testing on a Palm III, with a Palm Modem providing dial-up connectivity to the Internet.
There are ROM images available for every Palm device from the Pilot 1000 through the latest devices. In fact, there are at least two ROM images available for each of these devices, a debug and a nondebug version. The debug version traps many common errors, such as NULL pointer access, invalid operations, and memory access violations.
Members of the Palm Developers Alliance can obtain these ROM images from the Palm Computing web site, http://www.palmos.com.[1] Alternatively, developers can download ROM images directly from Palm OS devices using the ROM transfer utility included with POSE releases. This is recommended as a short-term solution only.
It is best to develop your application against the most current debug ROM available. Once your application has entered the testing phase, it should be exercised against as many debug and nondebug ROMs as possible. It is also important that you test your application on an actual device; the emulator does an excellent job, but it is not an exact replica of a device. Testing your application across as wide a range of actual devices as possible will save you tech support headaches in the future.
There are two options for debugging network applications with the emulator. The developer can redirect Net Library function calls to use the host’s TCP/IP stack instead of the devices, or it can use the devices. The simpler of these approaches is to redirect the calls. Figure 4-1 shows how to configure POSE to redirect Net Library calls to the underlying TCP/IP stack.
There are problems with this approach. The biggest problem when using redirected calls is the host’s TCP/IP stack is used rather than the device’s. For example, the emulator ignores timeouts, which may break your application. Other differences are sure to arise. These differences mean that your application may run fine on POSE but not on the device. It is essential that you test your application using the Palm OS TCP/IP stack.
Turning off Net Library redirection provides a better environment for developing and testing network applications. It, too, has downsides. Configuring POSE to support this is not trivial. For dial-up connections, POSE tends to respond more quickly than the device itself, especially with regard to acknowledging packets. This approach means that the emulator must connect to the network every time you run your application, which is a long process. If the target network is faster than the dial-up access (such as the 802.11 networking support provided by some Symbol devices), your application may work fine under the emulator, only to fail on the device itself.
There are two aspects to configuring POSE to use the host’s modem for network connectivity. You must first configure the emulator application itself. Then you must configure the Palm session that runs on the emulator.
Configuring POSE’s application settings is simple, but there are slight differences between the Macintosh and Windows platforms. I explain each separately:
- Macintosh
Select the Preferences menu item from the Edit menu on the POSE menu bar. Figure 4-2 shows the POSE preferences dialog.
Select the “Internal Modem” from the “Serial port” drop down list and clear the “Redirect NetLib calls to Host TCP/IP” check box. POSE will now use the computer’s internal modem for dial-up networking, as well as the network protocol stack included with the ROM file.
- Windows
Determine the communications port used by the modem before you configure POSE to use it on Windows. We determine this port by examining the Modem settings from the Control Panel. This is illustrated in Figure 4-3.
In this example, the internal modem is on COM2. We right-click anywhere on POSE to invoke a pop-up menu and select the Properties menu item from the Settings menu. This launches the dialog shown in Figure 4-4.
Select the COM port of the internal modem from the “Serial Port” drop down list and clear the “Redirect NetLib calls to host TCP/IP” check box.
Once we’ve configured the emulator preferences, we can set up the session to dial into either a remote access server (RAS) on a local area network, or into an Internet Service Provider (ISP):
Set the connection information.
From the application screen on the emulator, select the Prefs application. On the top right of the Prefs form is a drop down containing a list of preferences you can set. Select the “Network” item. The resulting screen is shown in Figure 4-5.
The service name is not important; you can put any name here. Enter the username you use to log in to the network provider from the host.
Set the Connection option.
Click on the pop-up list next to the “Connection” label. You are presented with a list of modems and other connection mechanisms. Figure 4-6 shows this list.
Select “-Current-”. This option, which is only available on the emulator, tells POSE to use the connectivity configured earlier.
Set the connection details.
Click on the “Details” button. This brings up the Network Details screen. This screen is illustrated in Figure 4-7.
Set the Connection Type to PPP. Uncheck Query DNS and enter the Primary and Secondary DNS from the host’s network configuration. On the Macintosh, you can find this information in the TCP/IP control panel. Under Windows, it is available from the Dial-up networking TCP/IP properties dialog box. Select OK when you are done to return to the Network Preferences form.
On the Network Preferences form, the Password will say “-Prompt-”. Click on this to enter the password. The Password form is shown in Figure 4-8.
Enter the password for your network account, then select OK to return to the Network Preferences form. The password field now says “-Assigned-”. Unlike what happens with your host, you can see the password as you type it. Because of the challenge of entering text with graffiti, passwords on Palm devices are visible as you enter them. But if you were to click on “-Assigned-”, it would not show you the password, and the field would be blank.
Set the phone number.
The phone number is originally set to “Tap to enter phone.” Click on this to launch the Phone Setup form. Figure 4-9 shows this form.
Setting up the emulator for dialing a server is straightforward. Enter the server’s phone number in the Phone # field. If you need to dial a number to access an outside line (usually an 8 or 9), check the Dial Prefix checkbox and enter the number in the Dial Prefix field. If your phone has call waiting, you will want to disable it before connecting to the network; otherwise an incoming call will cause your connection to drop. Check the “Disable call waiting” check box and enter the appropriate code in the associated field. The Palm OS even supports credit card calls. Simply check the “Use calling card” check box and enter the appropriate numbers. You might need to play with this string a few times to get the timing right.
Test the connection.
From the Network Preferences panel, select “Connect.” The emulator will open the host’s modem and dial in to the network. Figure 4-10 shows this connection in progress.
If the connection fails, the OS displays an error, indicating the cause of the failure; correct the problem and try again. If the connection succeeds, the label on the “Connect” button changes to “Disconnect.” Select this button to close the connection.
Test the networking application.
Once you have connected successfully to the network, the last step is to verify the settings entered in the Details screen in step 3. Load and run a commercial network application. There are a variety of free and shareware applications that will work for this. I use MochaSoft’s Telnet client for Palm.
You are ready to debug your network application on POSE. The only challenge to this approach is that each time you debug, you will need to reconnect to the network, which will cause some delay. However, the source-level debugging capabilities and faithful emulation provided by this setup are more than worth this delay.
There are some circumstances where using POSE is not appropriate. Fortunately, MochaSoft provides the tremendously useful utility MochaPPP.
Tip
MochaSoft provides a wide variety of networking programs and utilities. These are available for download from their web site, at http://www.mochasoft.dk.
MochaPPP runs on a Windows computer and provides connectivity from the Palm to the network via the HotSync cradle. MochaPPP acts as a PPP server to the device, routing network calls to the hosts’ network connection. This allows the device and the host to share a single connection. This is especially useful where you don’t have a separate dial-up connection or you are unable to configure POSE for dial-up networking. Figure 4-11 illustrates the MochaPPP architecture. With this configuration, you can access the Internet and run a web browser, POP mail client, WAP browser, or TCP/IP application.
There are two limitations to MochaPPP. Because the device connects to MochaPPP through the HotSync cradle, you cannot debug the application on the device. You must use alerts and log entries to track what happens in your application. This is less efficient and takes far more effort than the source level debugging provided by POSE. You must frequently edit, recompile, and download your application as you track down bugs.
Because MochaPPP uses the same IP address for both the host and the device, other computers on the network cannot distinguish the Palm device from the host through which it connects. This means that some applications, such as the FTP client application developed in this book, cannot be supported.
Within these limitations, MochaPPP is useful, especially for testing applications. Because it uses the host’s network stack, you do not have to dial into the network each time you run the application; the hosts connection remains valid independent of the device.
[1] Assuming they have signed the appropriate license applications and live in the U.S. or Canada. Developers from other countries can have the ROM image files sent to them.
Get Palm OS Network Programming now with the O’Reilly learning platform.
O’Reilly members experience books, live events, courses curated by job role, and more from O’Reilly and nearly 200 top publishers.
