ONDotNet.com    
 Published on ONDotNet.com (http://www.ondotnet.com/)
 See this if you're having trouble printing code examples


O'Reilly Book Excerpts: Programming Visual Basic for the Palm OS

Building Palm Conduits, Part 1

Related Reading

Programming Visual Basic for the Palm OS
By Matthew Holmes, Patrick Burton, Roger Knoell

by Roger Knoell and Matthew Holmes, Patrick Burton

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. 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.


Figure 4-1. Overview of HotSync COM architecture

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.

Applications and Conduits

In This Series

Building Palm Conduits, Part 4
This final book excerpt in this series from Programming Palm OS with Visual Basic covers data formats, and packing and unpacking record data in a Palm application.

Building Palm Conduits, Part 3
Learn about synchronization logic in building Palm conduits, in this excerpt from 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.

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.)

Conduit Types

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:

Fast
Performs a fast synchronization

Slow
Performs a slow synchronization

HHtoPC
Copies handheld database to the desktop and overwrites all old records

PCtoHH
Copies desktop database to the handheld and overwrites all old records

Install
Installs new application to the handheld (system function)

Backup
Backs up handheld database to the desktop (system function)

DoNothing
Doesn't perform any synchronization

ProfileInstall
Performs a profile download (system function)

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.


Figure 4-2. User dialog for HotSync preferences

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.

TIP:   Conduits should always have a UI. Otherwise, your user will click the Change button in the Custom dialog and nothing will happen. Not only is this rude, it will leave your user wondering if something is broken.

Mirror Synchronization

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:

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.

Categories

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:

  1. 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.
  2. 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.
  3. 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.

Other Types of Conduits

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.

Roger Knoell s a software developer with 10 years experience leveraging high-level language development tools and environments.

Patrick Burton has been programming in C/C++ for most of his career. His experience inlcludes algorithm development for embedded satellite receivers, Linux system programming, and Windows programming using the Win32 API and Microsoft Found Classes (MFC).

Matthew Holmes has been developing computer software for 15 years. He cherishs his liberal arts degree in Foreign Affairs from the University of Virginia, and he holds a graduate degree in Computer Science from George Mason University.

In the next installment, learn Palm OS conduit design using VB.NET.

Programming Visual Basic for the Palm OS

Related Reading

Programming Visual Basic for the Palm OS
By Matthew Holmes, Patrick Burton, Roger Knoell

Return to the .NET DevCenter

Copyright © 2009 O'Reilly Media, Inc.