The original concept of the Palm was of a device tethered to data on the desktop. The PDA is an extension of the desktop, not its replacement. 3Com (the Palm PDA manufacturer) has expanded this design concept; it now calls the Palm device the “connected organizer.” Palm wants you to build applications that function in today’s mobile and connected world.
In this chapter, we look at
building
conduits using Microsoft Visual Basic (VB).
Conceptually, a conduit is the tether that moves data back and forth,
connecting your Palm application and its data store. A conduit is a
piece of software that runs on the desktop when the PDA is
synchronizing,
under the
control of the Palm HotSync manager.[27] In this book, we are going to build conduits
using VB and ActiveX.
By design, a conduit is dedicated to a single Palm application, which will have one or more associated Palm databases. Keep in mind that, even though the conduit is a piece of desktop software, the application data may be located anywhere—on the desktop, in a relational database, or even on the Internet. Once you have decided where your application’s data resides, it is then your responsibility to build a conduit capable of delivering that data to the Palm device. The Palm Conduit Development Kit provides a framework for ActiveX conduit development, which we’ll explain in detail later in this chapter.
Note that conduits developed in VB can be used with any application and database on the PDA, not only those created with AppForge. The high-level HotSync architecture is shown in Figure 4-1.
The Palm HotSync manager is in control of the synchronization process. It maintains a list of configured conduits in the system registry, and it handles the interface with the Palm PDA. The HotSync manager uses a set of COM objects—the Sync Suite API—to communicate with ActiveX conduits. The conduit manages application-specific data and supplies a userinterface if appropriate.
This chapter covers how to compile and register an ActiveX conduit with the HotSync manager, how to use the Sync Suite API to synchronize Palm PDA data with the desktop, and how to handle the user interface.
Before we get to the mechanics of conduit development, let’s review the concept of data synchronization as it applies to Palm applications and databases. If the handheld is an extension of the desktop, then it is natural to ask: How should the data flow between the handheld and the desktop? This is going to depend in great deal on the design and purpose of your application and its databases.
Entertainment or utility programs
rarely have a conduit—they
don’t have data worth moving to the desktop. These
applications usually save any data in the system
Preferences database, which is automatically
backed up and restored by the HotSync manager. We covered application
preferences in Chapter 3.
More typical is the unidirectional conduit, in which the data flows from the Palm device to the desktop, or the other way around. This type of conduit is useful in applications like questionnaires, where the Palm is used primarily as a remote data collection tool.
The Palm PDA’s native applications, like Address and To-Do, use a mirror-image conduit, where changes on the desktop and the device are replicated in both directions. This type of synchronization is so important that Palm has documented exactly how a mirror-image conduit should behave. We will cover mirror-image synchronization in detail later in this chapter.
A transactional conduit processes data to produce intermediate results, which are written back to the Palm device. The data flow in a transactional conduit can be in one or both directions. You could implement this sort of conduit for an application that uploads orders to a SQL database for fulfillment processing and then downloads invoices to the Palm. We discuss this type of conduit in Chapter 5.
Finally, there are system
functions
such as installation and backup that use
special- purpose conduits to perform their functions. The default
backup
conduit synchronizes databases whose applications
don’t have a custom conduit, or databases that have
a conduit but whose type is not DATA. The backup
conduit, which is supplied by the Palm desktop installation, simply
makes an exact copy of your application’s database
or databases on the desktop. (Technically, to be backed up by the
default conduit, a Palm database must have the backup bit set.)
Palm had to design the HotSync manager and conduit interface to support a wide variety of data synchronization and replication needs. Each conduit registers its unique creator identifier and synchronization type with the HotSync manager. Note that your conduit might support more than one type of synchronization; in that case, you should provide a user interface to allow the user to customize the behavior of your conduit. We’ll show you how to do this later in the chapter.
Here are the types of conduits supported by the Palm Conduit Development Kit, as documented in the Conduit Reference manual:
The HotSync manager on the desktop keeps track of when the user last synchronized his or her Palm device with this desktop. It uses this information to determine which conduits to call, and the type of synchronization each conduit is to perform.
Tip
The HotSync manager supports multiple users on the desktop. It also supports a single user with multiple Palm devices. The HotSync API provides identifiers during a HotSync session to enable a conduit to determine which user and/or device is synchronizing. We don’t discuss this capability further in this book, but it is covered in the Palm Windows Conduit Companion and Reference.
Of course, the user may set the type of synchronization manually, as illustrated in Figure 4-2.
If a conduit does not support a user interface, the HotSync manager uses the conduit’s default synchronization type. We show how to implement a custom user interface for your conduit later in this chapter.
As we mentioned earlier, mirror-image synchronization requires that a conduit replicate changes between the desktop and the Palm device. Mirror-image conduits should support both fast and slow synchronization. When your conduit is called to do a FastSync, it only needs to look for new or dirty records in your application’s Palm database and on the desktop. If your conduit is called for a slow sync, it must look at every record on the PDA and the desktop. The HotSync manager requests a slow sync whenever it determines that the last sync was not with this desktop. Otherwise, it requests a FastSync.
The Palm database manager supports per-record flags that track any changes to records in the database. These flags are listed in Table 4-1. In order to successfully implement a mirror-image conduit, your desktop database must support some or all of these flags on a per-record basis.
Table 4-1. Palm database record flags
|
Flag |
Meaning |
|---|---|
|
Changed |
Either create a new record or edit an existing record |
|
Deleted |
Delete the record |
|
Archived |
Make an archive copy, then delete the record |
|
Secret |
Mark record as private |
The Windows CDK Companion has a section on design decisions and tradeoffs that you can use to evaluate the kind of conduit your application can support. We’ll summarize a few key questions here:
Do you have unique record identifiers that can be mapped into Palm record identifiers?
Do you support per-record attributes, such as dirty, deleted, and archived?
Is it easy to detect changes to desktop records?
Are the desktop records categorized?
Is it simple to map database records to desktop records or entities?
Is it possible to partition the application and conduit to minimize synchronization times?
Unfortunately, there are no generic answers to these design questions. We will address these questions as they apply to a sample application and conduit that we will present later in this chapter. You’ll have to consider them from the context of your own application.
If your user has experience with any of the Palm native applications, then he’ll expect your conduit to replicate changes in the same manner. Palm has gone to great lengths to document this behavior, as it pertains to the native applications. (The synchronization logic is spelled out in the Palm Conduit Programmer’s Companion for Windows, which is part of the CDK.) Your conduit should emulate as much of this behavior as makes sense for your application.
Table 4-2 shows the possible states for each record in an application. The desktop record states run along the top of the table and the Palm record states run down the left side.
Table 4-2. Mirror conduit record states
|
No record |
No change |
Change |
New |
Delete | |
|---|---|---|---|---|---|
|
No record |
D → P | ||||
|
No change |
D → P |
Remove DP | |||
|
Change |
P → D |
Conflict |
P → D | ||
|
New |
P → D | ||||
|
Delete |
Remove DP |
D → P |
The action that your conduit should take is found in the intersection of each of the possible states, and is spelled out in the following list:
- D → P
Desktop record replaces Palm record
- P → D
Palm record replaces desktop record
- Remove (DP)
Delete the record from the desktop and/or the Palm
- Conflict
Follow application rule to resolve synchronization conflict
After the conduit takes the indicated action, the record on the desktop is in the same state as the record on the Palm.
A conflict arises when a record is changed simultaneously on the Palm device and on the desktop. Palm recommends that this conflict be resolved by migrating the change in both directions. The user can then edit or delete the data on either the Palm or the desktop. At the next synchronization, the conduit will clean up all the changes.
Tip
Note that the blank cells in Table 4-2 correspond to conditions that Palm considers logically impossible or irrelevant to conduit design. Palm derived these conditions from the behavior of its native applications. Your conduit and application might not need to support all these conditions, or they might need to support different possibilities.
The situation is slightly more complicated if your application
supports archive records. A Palm application such as
Address offers to archive a record when it is
deleted. This is an offer to preserve the data somewhere on the
desktop; presumably, the desktop provides the corresponding restore
operation.
The ability to archive older records, instead of deleting them forever, was crucial to the early Palm devices, which sported 128 KB of memory. Users were forever shuffling data between the device and the desktop. While it is less critical now, memory is still a scarce resource. So if you can support the archive option in your application, you certainly should.
In general, when a Palm record is marked for archival, the conduit archives the record in an application-specific fashion, and then deletes the record from both the Palm and the desktop.
Table 4-3 shows how to handle Palm database records that are marked for archiving. In this table, the desktop record states appear along the top of the table and the Palm record archive states appear on the left side.
Table 4-3. Mirror sync actions with Palm archive request
|
Delete |
No change |
No record |
Change | |
|---|---|---|---|---|
|
Archive |
Archive, Remove DP |
Archive, Remove DP |
Archive, Remove DP | |
|
Archive, Change |
Conflict | |||
|
Archive, No Change |
D → P |
A conflict arises if a record has changed in both databases as the same time. In such a case, the conflict is deepened because the user has also requested that the record be archived—this means that she doesn’t want to see it again any time soon. Here’s how the Palm CDK Companion says you should handle the conflict:
If the changes are identical, archive both the device record and the desktop record. If the changes are not identical, do not archive the device record; instead, add the desktop record to the device database, and add the device record to the desktop database.
Table 4-4 shows what to do when a desktop record has been marked for archival. The most common case, in which the Palm device record has not changed, is handled by archiving the record and then removing it from both the device and the desktop.
Table 4-4. Mirror sync actions with desktop archive request
|
Archive |
Archive, change |
Archive, no change | |
|---|---|---|---|
|
Delete | |||
|
No change |
Archive, Remove DP | ||
|
No record | |||
|
Change |
Conflict |
P → D |
Not surprisingly, a conflict occurs when the record to be archived has been changed in both databases. According to the Palm CDK Companion:
If the changes are identical, archive the device record and then delete the records from both the device and desktop databases. If the changes are not identical, do not archive the desktop record; instead, add the desktop record to the device database and add the device record to the desktop database.
A mirror-image conduit should also
support the HHtoPC
and PCtoHH synchronization types. Recall that
these sync types cause the handheld data to overwrite the desktop or
vice versa. At first it might seem counter-intuitive that your
conduit could be called to blindly overwrite user data, on either the
desktop or the Palm device. But keep in mind that your conduit is
almost always called this way as a result of user intervention.
For example, your user might accidentally delete an entire category of data records on the Palm device. Instead of then synchronizing these changes, and thereby deleting the data from the desktop as well, the user can direct the conduit to overwrite all the Palm data, effectively restoring the deleted records.
A conduit must synchronize changes in category data as well as record data. Because a category is actually a compound data type—it has both a name and a numeric ID—the synchronization logic is a little harder. Palm addresses the default logic for the native conduits in the CDK documentation.We summarize it here:
If the category ID has changed on either the desktop or the PDA, but the name is the same, update all desktop records to use the PDA category ID.
If the desktop category name has changed, but the category ID is the same, then update the PDA category name. Note that this only holds true if the new desktop category name is not already in use on the PDA.
If there is a category with a new name and ID on the desktop, and neither is in use on the PDA, then create a new category on the PDA. If the index is already in use, then assign a new index from the PDA, and update all the desktop records with it.
If your application supports categories, give careful consideration to the mapping between category names and identifiers on the Palm PDA and the desktop. And be aware that there is native support in the Palm operating system for only 15 active categories.
Your conduit will never be called for Install,
Backup, or ProfileInstall
synchronization. These are reserved to the HotSync manager to perform
special system functions. Your conduit can be called for
DoNothing synchronization, always at the
user’s request.
If you have a transactional conduit, you will have to masquerade as a mirror-image conduit. We don’t discuss transactional conduits in this book. These conduits have the same structure and logic as the conduits we have already described, but they must handle distributed transactions and error rollback and recovery as well. We do cover the use of conduits to manage SQL data in Chapter 7.
[27] There are other HotSync managers for enterprise use that allow remote connections. Conduits can also be built using C/C++ or Java, but we won’t discuss either of those languages in this book.
Get Programming Visual Basic for the Palm OS 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.
