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

HHtoPC

In our simple conduit, the HHtoPC routine is called only at the user's request. The purpose of this routine couldn't be simpler: it deletes all records from the desktop and then copies any records from the Palm device. The code for HHtoPC is shown in Example 4-9.

Example 4-9: Listing for SyncLogic.HHtoPC

Private Sub HHtoPC(ByRef pdSys As PDSystemAdapter, _
                   ByRef pdHSInfo As PDHotsyncInfo)
 
    ' Data is under user's directory in HotSync area.
    Dim DBPath As String
    DBPath = pdHSInfo.PathName + "Ch4a"
    
    ' Purge the PC data - force a new directory if necessary.
    Dim FSO As New FileSystemObject
    On Error Resume Next
    FSO.DeleteFile DBPath + "\*.*", True
    FSO.CreateFolder DBPath
    On Error GoTo 0
    
    ' Get the Palm database from the HotSync manager
    Dim DBName As String
    DBName = pdHSInfo.NameList(0)
    
    Dim pdQuery As New PDDatabaseQuery
    Dim pdRecords As PDRecordAdapter
    Set pdRecords = pdQuery.OpenRecordDatabase(DBName, "PDDirect.PDRecordAdapter")
    
    ' Open the handheld database, and iterate over the records
    Dim Index As Long
    Dim RecordId As Variant
    Dim Category As Long
    Dim Attributes As ERecordAttributes
    Dim Data As Variant
 
    pdRecords.IterationIndex = 0
    Data = pdRecords.ReadNext(Index, RecordId, Category, Attributes)
    Do While Not pdRecords.EOF
    
        ' In a HHtoPC sync, process all but deleted records
        If Not CBool(CByte(Attributes) And CByte(eDelete)) Then
            WriteRecContents DBPath, RecordId, Data
        End If
  
        ' Read the next record and skip to the top of the loop
        Data = pdRecords.ReadNext(Index, RecordId, Category, Attributes)
    Loop
    
    '  Remove any deleted records, clear  flags in Palm database
    pdRecords.RemoveSet eRemoveAllDeletedRecords
    pdRecords.ResetAllModifiedFlags
    
    LogSync pdSys, pdHSInfo.SyncType
 
End Sub

Let's examine the HHtoPC routine a little bit at a time. First, the routine locates the desktop data store, which is located under the user's Palm desktop directory. It is customary for Palm conduits to keep their information in this directory. The directory is available as the PathName method of the PDHSInfo object; the routine tacks on a folder name to create a subdirectory.

Dim DBPath As String
DBPath = pdHSInfo.PathName + "Ch4a"

The routine then deletes any files in that folder. Wrapping the delete operation in an error handler is necessary, because the FileSystemObject throws an error if the folder doesn't exist or if it is empty.

Dim FSO As New FileSystemObject
On Error Resume Next
FSO.DeleteFile DBPath + "\*.*", True
FSO.CreateFolder DBPath

Next, HHtoPC creates an instance of the Sync Suite PDDatabaseQuery class:

Dim pdQuery As New PDDatabaseQuery

This class provides programmatic access to the Palm database manager on the device. Remember, instances of this class are only available when the user is synchronizing the device, not during conduit configuration. This class has methods and properties, as shown in Table 4-12, that allow us to manage Palm databases.

Table 4-12: Properties and methods of PDDatabaseQuery

Property or method name	Description
AddLogEntry	Makes an entry in either the desktop or device HotSync log.
CreateRecordDatabase	Creates a data type database. Records are unstructured.
CreateResourceDatabase	Creates a resource-type database. Each record has a structure, such as an icon or form.
MaxAllowedRecordSize	Retrieves maximum supported record size on the device.
OpenRecordDatabase	Opens an existing data type database.
OpenResourceDatabase	Opens an existing resource-type database.
RamDbCount	Retrieves number of databases in device RAM.
ReadDbInfoByCreatorType	Retrieves statistics and settings for a database.
ReadDbInfoByName	Retrieves statistics and settings for a database.
ReadDbNameList	Retrieves list of databases in RAM or ROM.
RemoveDatabase	Deletes a RAM or ROM database.
RomDbCount	Retrieves number of databases in device ROM.

Again, look at the class hierarchy shown earlier in Figure 4-5. PDDatabaseQuery is a publicly created object. Our main interest in this class is its ability to return objects representing actual databases on the Palm device. We get the name of our database from the PDHSInfo object:

' Get the Palm database from the HotSync manager
Dim DBName As String
DBName = pdHSInfo.NameList(0)

Note that NameList is an array. If your application has more than one database on the Palm PDA, each is listed in the array. The total number of databases is available in the RemoteNameCount property.

The Sync Suite API provides the PDRecordAdapter to access the contents of any one database on the Palm device. This object is created in an unusual way, by passing the programmatic identifier of a class factory into the database query object.

The class factory is responsible for producing an object that satisfies all the interface requirements for an instance of PDRecordAdapter. The CDK provides this unusual construction technique so developers can subclass the record adapter, and supply extra capabilities tailored for a specific application. In our conduit, we use the default record adapter supplied by Palm:

Dim pdRecords As PDRecordAdapter
Set pdRecords = pdQuery.OpenRecordDatabase(DBName, "PDDirect.PDRecordAdapter")

Table 4-13 shows the many methods and properties of PDRecordAdapter. This large class is heavily used in our sample conduit. In the table, two sets of functions have been grouped together: direct record access, denoted in the table by ReadBy*, and iterator access, denoted in the table by ReadNext*. The direct access functions allow the retrieval of a single record, either by index or record identifier. The iterator access functions allow the sequential retrieval of many records, either by index or by category or other attribute.

Table 4-13: Properties and methods of PDRecordAdapter

Property or method name	Description
AccessMode	Retrieves mode(s) used to open database
AddLogEntry	Makes an entry in either the desktop or device HotSync log
ChangeCategory	Changes the Category ID for a group of records
CloseOptions	Sets modification date/time on database prior to close
DbName	Retrieves the database name
EOF	Indicates end-of-file when using an iterator
InputBufferSize	Sets the maximum size for read/write buffers
IterationIndex	Sets the start offset in the database for an iterator
PDCategories	Represents category data for this database
PDDatabaseInfo	Represents database for this record adapter
ReadAppInfoBlock	Reads application-specific data, including categories
ReadBy*	Gets record information by index or identifier
ReadNext*	Gets record information from an iterator
ReadSortInfoBlock	Retrieves application-specific data, notionally used for sorting
ReadUniqueIdList	Retrieves list of record identifiers in database
RecordCount	Retrieves count of records in database
Remove	Permanently erases a record from database
RemoveSet	Permanently erases a group of records from database
ResetAllModifiedFlags	Clears the dirty bit for all records in database
Write	Creates or updates a database record and attributes
WriteAppInfoBlock	Writes application-specific data, including categories
WriteSortInfoBlock	Writes application-specific data, notionally used for sorting

Pages: 1, 2, 3, 4

Next Page