WindowsDevCenter.com
oreilly.comSafari Books Online.Conferences.

advertisement


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

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 Pagearrow