O'Reilly Book Excerpts: Programming Visual Basic for the Palm OS
Building Palm Conduits, Part 2
In this excerpt from Programming Visual Basic for the Palm OS, learn how to design conduits using VB for the Palm OS.
There are several major design principles for a conduit. The first, and most important, is that the conduit runs as quickly as possible. No one wants to wait while synchronization grinds on and on. Honoring the fast and slow sync flags will help you to optimize performance. A fast conduit also minimizes the use of the Palm device's serial port. This is important, because serial port use can drain the PDA's batteries very quickly.
The second principle is that a conduit must always move application data in a natural way between the Palm device and the desktop. Your user relies completely on this behavior. She also relies on the conduit to restore all data in case of a disaster. If your conduit is not correctly implemented, or has bugs, user acceptance of your application will suffer greatly.
A third principle is that your conduit must be able to run without attention from the user. While this is a good design principle for software in general, it is especially important for a conduit. This is because the user might be synchronizing from a remote location, communicating with the HotSync manager over a modem or network connection. The user will not be able to respond to any prompts or dialog boxes that a conduit might display on the desktop. This will cause the entire HotSync session to hang.
Palm provides some more design guidelines in the C/C++ Conduit Companion; you should certainly study those before implementing your own conduit.
If you are building a mirror-image conduit, then follow the logic diagrammed earlier in Tables 4-2, 4-3, and 4-4, as they apply to your application. If you don't allow desktop editing of data in your application, for example, then your conduit doesn't have to support it, either.
Having a user interface and allowing the user to override the conduit's default behavior will help you achieve acceptance. If at all possible, support uploading or downloading all records from your user interface.
Note that if your Palm database design maps into a relational database, and you used the AppForge database tools described in Chapter 4, then you can likely use the Universal Conduit. We discuss the pros and cons of the Universal Conduit in Chapter 5, and show you how to use it to integrate SQL Server data into your applications.
When Not to Use a Conduit
Not all synchronization situations require you to implement a conduit. It is perfectly appropriate to make a new database from scratch and download it to the device, if you know that all or most of your application's data has changed.
Simply generate your database from the new data, and put it in the HotSync installation directory. The database will be automatically deployed to the device with the next synchronization, overwriting any existing PDA data in the process. If your application has a database that is read-only, and that is periodically refreshed, you can use this technique. If your sales department produces a list of prices that changes monthly, then you don't need to execute a conduit every day.
In This Series
Building Palm Conduits, Part 1
Not having a conduit can greatly simplify the distribution of your application. You don't have to worry about developing an installation script for your conduit and its associated runtime objects.
If the Palm Desktop is configured properly, the Windows default shell action for PRC and PDB files is to call the Palm Instapp.exe program, which will copy the file into the Palm desktop installation directory.
This means that you can post your database files on the Web or in ZIP archives. When your user downloads or extracts your file and double-clicks it, it is queued for installation at the next HotSync.
Installing the CDK
The Conduit Development Kit (CDK) is freely downloadable from the Palm web site. The CDK contains libraries and runtime bindings for VB and COM, as well as the C/C++ language. The InstallShield wizard puts everything into the directory you select (see Figure 4-3).
You can choose to install only the COM libraries, samples, and documentation by using the custom installation procedure and deselecting the C/API. We recommend performing a full installation, because the C/API contains some additional documentation you will find useful.
The Com folder contains the VB tutorial and sample projects, an installation tool, and another directory that simply contains links to the documents mentioned above. Most of the sample projects in the CDK are primers that focus on explaining at most one or two parts of the CDK. There is also a longer example, SyncSamp, which replaces the default Memo conduit and illustrates a complete conduit.
The Common folder contains the CDK programs and libraries used when developing conduits. This folder also contains the documentation, in both Adobe PDF and Microsoft Help formats. Earlier releases of the CDK runtime are supplied for backward compatibility; these won't help you, because only the most recent release supports VB development.
If you have the Palm desktop software installed on your development machine, as is required to run AppForge, there are some issues you should be aware of when you install the CDK. By default, your system uses the HotSync manager that was installed with the Palm desktop software. Unfortunately, the ActiveX objects needed to develop and debug conduits are not installed with earlier releases of the Palm desktop.
If you have the luxury of developing your applications and software on separate computers, the following step is unnecessary. Otherwise, you will have to alter the desktop configuration so that the new HotSync manager runs during the synchronization process. Use the Microsoft RegEdit.exe tool, and alter the two registry keys as shown in Example 4-1. Note that the location of the updated HotSync manager depends on where you installed the CDK on your filesystem.
Example 4-1: Registry settings for HotSync manager
HKEY_CURRENT_USER\Software\U.S. Robotics\Pilot Desktop\Core
HotSyncPath = C:\CDK401\Common\Bin\C4.01\Hotsync.exe
Path = C:\CDK401\Common\Bin\C4.01
This is a good time to run the CDK tutorial SimpleDB, which shows how to run and debug a program under the control of the HotSync manager. This is how all conduits are executed, and it is important that you get comfortable with this environment. Running the tutorial also ensures that all of the CDK components are properly installed, and that the new HotSync manager is running correctly.
To run the tutorial, use the CondCfg.exe program to register the VB development environment as a conduit. Once the HotSync manager calls the VB IDE, you are in control and can test and debug your conduits with all the powerful VB features to which you are accustomed.
Let's walk through the steps required to configure the tutorial. Start the CondCfg.exe tool to show all the currently registered conduits, and to add, edit, and delete conduits. If you are developing on your own Palm desktop, be careful not to disturb the settings for the native Palm applications! We disable all conduits except those actually under development; this both increases the speed of the synchronization process and provides some security from data corruption. Press the
Add button to bring up the
Conduit Information dialog, into which you enter the settings for your conduit (see Figure 4-4). First, you must enter
ComConduit.dll in the name field. The HotSync manager uses this DLL to locate and instantiate COM conduits.
Because each conduit handles exactly one application on the Palm device, you must enter the unique Creator ID of your application. (There must be only one conduit registered for any Palm application. CondCfig.exe will not allow you to register a second conduit for the same application, or, more precisely, an application with the same Creator ID).
TIP: If there is no application on the Palm device with this ID, then the conduit will not run. You must install your Palm application first.
For our sample conduit, we entered
Ch4a as the Creator ID. In addition, we entered
Ch4aDB in the optional remote database field. As we'll see later, the HotSync manager provides the conduit with a more accurate list of databases during an actual synchronization session.
In the extra information group box at the bottom of the dialog, select the
Conduit radio option button. Enter the full path to the VB IDE in the COM client field.
Leave all the other fields blank or with the default values. These settings were shown earlier in Figure 4-4. Press the
OK button to register the new settings, and restart the HotSync manager. Then exit the configuration tool.
Now put the Palm device into the cradle and press the HotSync button. Although the synchronization process runs normally, the VB IDE doesn't activate. That is because the HotSync manager could not find an application on the Palm device with a Creator ID of
You will need to download our sample application for this chapter and install the application file Ch4a.prc. After the application is installed, perform a HotSync one more time. This time, the HotSync manager on the desktop displays the message
Status: Synchronizing COMConduit, and the VB IDE pops up.
Now you can test your environment by opening SimpleDB.vbp in the CDK Tutorial folder. This VB project opens the native Memo application, and reads all the records that match a search term. Set a breakpoint in the button click event, and press
F8 to step through the program. Note that Palm device displays
Synchronizing Memo Pad, because the Memo database has been opened during a HotSync session. You are now communicating as a conduit with the Palm device from VB!
If the VB IDE doesn't appear, put the HotSync manager into its verbose mode. First, stop the HotSync manager by right-clicking on its icon in the Windows system tray, and select
Exit. Next, restart the HotSync manager with the
-v option from the command line. After synchronizing, you can review the diagnostic log for errors. To do this, right-click on the icon and select
If the SimpleDB project doesn't connect to the Palm, or exhibits other errors, check that the Palm conduit references are set correctly (these are shown later in this chapter in Figure 4-7). You do this from the VB IDE by choosing the
References option from the
Project menu. If these references are missing, try registering those ActiveX libraries by hand and restarting VB.
Nuts and Bolts
If you stepped through the SimpleDB CDK sample project, you saw that the VB code manipulated the Palm device's databases and records using COM objects. Let's dig a little deeper into the HotSync architecture to see how a conduit communicates with the Palm device.
Recall from Figure 4-1 that the COM Sync Suite provides the interface to the HotSync manager and the Palm device.
The Sync Suite itself has several layers to isolate its interface from the underlying details of the HotSync application and to support both VB/COM and C/C++ conduits. This layered approach frees the VB programmer from worrying about messy details such as which serial port the HotSync manager is using to communicate with the Palm device.
To simplify conduit development, the Sync Suite provides COM objects and classes that encapsulate the HotSync manager, the user, and databases on the Palm device. A utility class is provided to handle things like Motorola byte ordering and unique record identifiers. These classes and their relationships are shown in Figure 4-5.
There are VB projects in the CDK that cover these objects and interfaces. Rather than enumerate all of them here, we will discuss the major ones we encounter as we develop our simple conduit. Once you understand the framework, you can use the VB Object Browser and the Conduit Reference manual to find the special properties you need for your conduit.
The HotSync manager expects your ActiveX conduit to implement the IPDClientNotify interface, which it calls when it needs your services, either to synchronize or to access configuration settings and preferences.