WindowsDevCenter.com
oreilly.comSafari Books Online.Conferences.

advertisement


AddThis Social Bookmark Button

Building Palm Conduits, Part 3
Pages: 1, 2, 3, 4

All the iterator functions support a starting index position. In HHtoPC, we use the simple iterator to process all the records in the database, starting at index zero, and reading both the actual data and other record attributes:



pdRecords.IterationIndex = 0
Data = pdRecords.ReadNext(Index, RecordId, Category, Attributes)
Do While Not pdRecords.EOF

All of the PDRecordAdapter read functions return a VB variant, with the record data actually stored in a byte array. The read functions also set an attribute byte indicating the status of the current record. If the record is not marked for deletion, we copy it to the desktop by calling WriteRecContents.

If Not CBool(CByte(Attributes) And CByte(eDelete)) Then
    WriteRecContents DBPath, RecordId, Data
End

If your conduit supports record archival, then you should test for that condition as well, with the eArchive attribute. After we have processed the record, we read the next record, and skip to the top of the loop:

    Data = pdRecords.ReadNext(Index, RecordId, Category, Attributes)
Loop 

Eventually, the read function will cause the record adapter to reach the end-of-file condition and we will exit the loop after all of the database records have been processed. HHtoPC then purges the Palm database of any logically deleted records, and clears the modification flag for all dirty records:

pdRecords.RemoveSet eRemoveAllDeletedRecords
pdRecords.ResetAllModifiedFlags

Now let's look at how the WriteRecContents routine stores the Palm device record data to a desktop file. We aren't going to show all the code in WriteRecContents, but just the highlights. This routine uses a new Sync Suite object, PDUtility, to transform the Palm Record ID into a string:

Dim pdUtil As New PDUtility
Filename = DBPath + "\" + pdUtil.RecordIdToString(RecordId) + ".REC"

The Palm CDK documentation strongly encourages developers to use this function, rather than dissecting the variant data type holding a Record ID. This is because the Record ID format, currently a long integer, may change in the future. The PDUtility class has other methods to convert data between the Palm and desktop formats. We will see some of these as we pack and unpack string data for our records.

This completes the presentation of the HHtoPC synchronization logic for our simple conduit. Although this section presented a great deal of information .ckly, you should now have an appreciation of how to use the Sync Suite COM objects to access features and data on the Palm device.

FastSync

The HHtoPC sync didn't require much of a design--just take the Palm records and write them to the desktop, removing any existing desktop records in the process. Mirror synchronization is much harder.

Before we start into coding the FastSync, let's reexamine what mirror synchronization means for the Ch4a application. In Table 4-14, we've recast our table of possibilities to include the desktop file extensions instead of attribute flags. The code for our conduit has to identify all these possibilities, and then take the action indicated in the table. Preparing a table or state diagram like this when designing your conduit will prove helpful.

Table 4-14: Ch4a conduit actions

 

No record

No change

.CHG

.NEW

.DEL

No record

 

 

 

D P

 

No change

 

 

D P

 

Remove DP

Change

 

P D

Conflict

 

P D

New

P D

 

 

 

 

Delete

 

Remove DP

D P

 

 

In this simple conduit, the change conflict is handled in a straightforward manner: changes to a record on the Palm device take precedence over changes to the same desktop record. This is different from the Palm CDK recommendation of creating two new records, one on each platform that mirrors the changes. Of course, you will have to decide how to resolve any conflict in a fashion that is appropriate for your application.

Now let's look at FastSync, the low-level function that actually moves the data between the Palm device and the Windows desktop. It is shown in Example 4-10.

Example 4-10: Listing for SyncLogic.HHtoPC


Private Sub FastSync(ByRef pdSys As PDSystemAdapter, _
                     ByRef pdHSInfo As PDHotsyncInfo)
        
    Dim Index As Long
    Dim Category As Long
    Dim Data As Variant
    Dim RecordId As Variant
    Dim Attributes As ERecordAttributes

    ' Data is under user's directory in HotSync area.
    Dim DBPath As String
    DBPath = pdHSInfo.PathName + "Ch4a"
    
    ' Get Palm database name from HotSync manager
    Dim DBName As String
    DBName = pdHSInfo.NameList(0)

    ' Open the handheld database, and get the record interface.
    Dim pdQuery As New PDDatabaseQuery
    Dim pdRecords As PDRecordAdapter
    Set pdRecords = pdQuery.OpenRecordDatabase(DBName, "PDDirect.PDRecordAdapter")
    
    ' Iterate over the *modified* records
    pdRecords.IterationIndex = 0
    Data = pdRecords.ReadNextModified(Index, RecordId, Category, Attributes)
    Do While Not pdRecords.EOF
    
        Dim strID As String
        Dim pdUtil As New PDUtility
        strID = pdUtil.RecordIdToString(RecordId)
        
         If CBool(CByte(Attributes) And CByte(eDelete)) Then
            DeletedRec DBPath, strID, Data
        Else
            DirtyRec DBPath, strID, Data
        End If
        
        ' Get the next record
        Data = pdRecords.ReadNext(Index, RecordId, Category, Attributes)
    Loop

    Dim File As File
    Dim Folder As Folder
    Dim FSO As New FileSystemObject
    
    Set Folder = FSO.GetFolder(DBPath)
    For Each File In Folder.Files
        Select Case UCase(FSO.GetExtensionName(File.Name))
        Case "NEW"
            NewFile DBPath, File, pdRecords, pdUtil
        Case "DEL"
            DeletedFile File, pdRecords, pdUtil
        Case "CHG"
            DirtyFile DBPath, File, pdRecords, pdUtil
        End Select
    Next

    pdRecords.RemoveSet eRemoveAllDeletedRecords
    pdRecords.ResetAllModifiedFlags
    
    LogSync pdSys, pdHSInfo.SyncType

End Sub

We won't go over every line, as we have seen a lot of this code already in HHtoPC. The routine consists of some setup code, and then two main loops. The first loop pulls changes from the Palm device, and the second loop writes changes to the Palm device.

One large difference between FastSync and HHtoPC is that with FastSync, we only want to process records that have changed since the last synchronization. Remember, this is the definition of a FastSync. The PDRecordAdapter provides the ReadNextModified iterator that is specially designed for this circumstance. Each call to this iterator skips through the Palm database, returning only the changed records. As a side effect, the index variable will be incremented, not by one, but by however many records the iterator skipped over to find the next changed record.

Data = pdRecords.ReadNextModified(Index, RecordId, Category, Attributes)

In a Palm database, it is possible for a record to be both deleted and dirty at the same time. Actually, it can be archived as well, but remember that we don't support the Palm archive attribute.

A Palm application usually asks the user if the deleted record should be archived or simply removed from the database. Deleted records have no data, but they are still present in the physical database; you test for them using the eDelete attribute.

If CBool(CByte(Attributes) And CByte(eDelete)) Then
    DeletedRec DBPath, strID, Data
Else
    DirtyRec DBPath, strID, Data
End If

Archived records have data in order to support the archive operation; typically, the archived record is also marked for deletion.

TIP:   If your application uses the AppForge database library, call the extended delete function PDBDeleteRecordEx to mark a record as both archived and deleted. You do this by passing afDeleteModeArchive to the function.

For our conduit, there is no difference between a new record and a changed record; both are dirty relative to the desktop. Note that the CDK doesn't provide a method to distinguish the two cases (there is no eNew attribute). You can tell, of course, because a new Palm database record won't have a corresponding desktop file.

Pages: 1, 2, 3, 4

Next Pagearrow