oreilly.comSafari Books Online.Conferences.


AddThis Social Bookmark Button O'Reilly Book Excerpts: Programming Visual Basic for the Palm OS

Building Palm Conduits, Part 3

Related Reading

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

by Roger Knoell and Matthew Holmes, Patrick Burton

In this excerpt from Programming Visual Basic for Palm OS, learn about synchronization logic. Part 3 of 4.

Synchronization Logic

The SyncLogic object created in the BeginProcess routine encapsulates all of our synchronization logic. In our example, the class instancing property is set to Private, and the class file is saved as Ch4aLogic.cls. By partitioning a conduit in this fashion, between the public interface and the internal synchronization logic, we ensure that the interface code can be reused in other conduits.

Let's look at the Synchronize method, which is called to handle all of the synchronization requests made of this conduit. The code for Synchronize is shown in Example 4-8.

Example 4-8: Listing for SyncLogic.Synchronize

Public Sub Synchronize(  )

    ' Get the HotSync information object for this conduit
    Dim pdSys As New PDSystemAdapter
    Dim pdHSInfo As PDHotsyncInfo
    Set pdHSInfo = pdSys.PDHotsyncInfo

    ' Route the requested synchronization to the local handler
    Select Case pdHSInfo.SyncType
        Case eFast
            FastSync pdSys, pdHSInfo
        Case eSlow
            SlowSync pdSys, pdHSInfo
        Case eHHtoPC
            HHtoPC pdSys, pdHSInfo
        Case Else
            LogSync pdSys, pdHSInfo.SyncType
    End Select

End Sub

The first thing the method does is to declare and initialize a Palm Sync Suite COM object:

Dim pdSys As New PDSystemAdapter

The PDSystemAdapter class represents the Palm device. This powerful class provides access to most features of the device (except databases, which are handled by a separate class). The PDSystemAdapter class has the methods and properties shown in Table 4-10.

Table 4-10: Properties and methods of PDSystemAdapter

Property or method name



Makes a local or device HotSync log entry


Runs a program on the device


Retrieves the date/time on the device


Retrieves the device operating system version


Retrieves the device localization setting


Object representing current HotSync


Object representing device memory


Object representing current user


Retrieves the device product ID


Retrieves a device application setting


Retrieves device feature memory


Performs a device soft-reset


Retrieves the device ROM version


Retrieves HotSync API Version


Stores an application setting on device

The PDSystemAdapter and its subobjects exist only when synchronization is actually occurring. You cannot create this object, or its subobjects, outside the scope of BeginProcess. Our example conduit uses only a fraction of PDSystemAdapter's features; you can explore the CDK samples to see how to use the other features.

If you look at the Sync Suite class hierarchy shown earlier in Figure 4-5, you see that one of the subobjects of the system adapter is PDHSInfo. This object represents the current HotSync session. From it, we can get the synchronization type that the HotSync manager wants our conduit to run:

Dim pdHSInfo As PDHotsyncInfo
Set pdHSInfo = pdSys.PDHotsyncInfo

Note that the PDHSInfo class is not a publicly creatable object. You must use the system adapter to get one, as shown. The PDHSInfo class has the methods and properties shown in Table 4-11.

Table 4-11: Properties and methods of PDHSInfo

Property or method name



Memory card on device for this application


Indicator of local, modem, or network connection


Application Creator ID for this conduit


Database type for this conduit


Indicator of first synchronization for device or desktop


Application name on device


Database(s) for this Creator ID on device


Path for user area in HotSync directory


Registry key for this conduit


Registry path for this conduit


Number of databases for this Creator ID on device


Type of synchronization to perform


Username on device for this conduit

As with PDSystemAdapter, we use only a couple of features from the PDHSInfo object. While our sample conduit only has one database, the HotSync manager provides your conduit with a list of all remote databases that belong to your application. (Even though a conduit might be responsible for synchronizing more than one database, it can only have one open at a time. This complicates the design if the conduit needs to enforce relationships between the databases (tables)).

We use the SyncType object property to route program flow to the function that handles the requested synchronization type, supplying the newly created COM objects as reference parameters:

Select Case pdHSInfo.SyncType
    Case eFast
        FastSync pdSys, pdHSInfo
    Case eSlow
        SlowSync pdSys, pdHSInfo
    Case eHHtoPC
        HHtoPC pdSys, pdHSInfo
    Case ePCtoHH
        PCtoHH pdSys, pdHSInfo

Because this conduit only supports Fast, Slow, HHtoPC and PCtoHH synchronization, we direct all other synchronization types to a function that simply logs the request:

    Case Else
        LogSync pdSys, pdHSInfo.SyncType
End Select

We won't spend any time looking at the code for LogSync; it consists of a large select statement that builds a string identifying the conduit and synchronization type, and then uses the pdSystemAdapater.AddLogEntry method to write the entry to the HotSync log:

pdSys.AddLogEntry "Ch4a - " + strType, eText, False, False

Calling AddLogEntry with an option other than eText, such as eWarning, causes the HotSync manager to alert the user after all conduits have finished executing, as shown in Figure 4-8. See the enumeration type ElogActivitity for the supported log types.

Figure 4-8. HotSync warning dialog

The AddLogEntry method supports writing to either the desktop or the device HotSync log. Set the optional fourth parameter to True to write to the device. Take care when writing to the device log to keep the amount of information to a minimum.

That wraps up the high-level presentation of the Synchronize object: we've seen how it is created, how it routes HotSync commands to the correct internal functions, and how it logs information to the HotSync log. Next, we are going to look at the low-level synchronization functions HHtoPC and FastSync.

Pages: 1, 2, 3, 4

Next Pagearrow