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	Description
AddLogEntry	Makes a local or device HotSync log entry
CallRemoteModule	Runs a program on the device
DateTime	Retrieves the date/time on the device
HHOsVersion	Retrieves the device operating system version
LocalizationID	Retrieves the device localization setting
PDHotSyncInfo	Object representing current HotSync
PDMemoryCardInfo	Object representing device memory
PDUserInfo	Object representing current user
ProductId	Retrieves the device product ID
ReadAppPreference	Retrieves a device application setting
ReadFeature	Retrieves device feature memory
RebootSystem	Performs a device soft-reset
RomSoftwareVersion	Retrieves the device ROM version
SyncManagerAPIVersion	Retrieves HotSync API Version
WriteAppPreference	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	Description
CardNum	Memory card on device for this application
ConnectionType	Indicator of local, modem, or network connection
Creator	Application Creator ID for this conduit
DbType	Database type for this conduit
FirstSync	Indicator of first synchronization for device or desktop
LocalName	Application name on device
NameList	Database(s) for this Creator ID on device
PathName	Path for user area in HotSync directory
RegistryKey	Registry key for this conduit
RegistryPath	Registry path for this conduit
RemoteNameCount	Number of databases for this Creator ID on device
SyncType	Type of synchronization to perform
UserName	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 Page