WindowsDevCenter.com
oreilly.comSafari Books Online.Conferences.

advertisement


AddThis Social Bookmark Button

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 Pagearrow