WindowsDevCenter.com

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

Sample Application and Conduit

The sample code for this chapter includes an AppForge application project, Ch4a.vbp, and an ActiveX conduit project, Ch4aCond.vbp.

You can use the application to create, edit and delete records on the Palm device. This application creates a database that consists of text records with a single field. Figure 4-6 shows the application's user interface on the Palm PDA. The application has a Creator ID of Ch4a, and the database is named Ch4aDB.

**Figure 4-6.** **Main screen for sample application Ch4a**

There is no corresponding Windows application for this example. Instead, we represent desktop records using text files in a desktop folder. We will use the record identifier from the Palm database as the filename--this will guarantee uniqueness in our naming system. Synchronized desktop records have the extension .REC. Newly added desktop records will have the extension .NEW, deleted records will have the extension .DEL, and changed desktop records will have the extension .CHG.

By following this scheme, we can implement all the synchronization possibilities shown previuosly in Table 4-2. Note that to simplify this example, we aren't going to support archived records or database categories.

Let's outline what this conduit example is going to demonstrate:

How to implement all required COM interfaces

How to support user customization

How to read and write data on the Palm device (FastSync and HHtoPC sync)

Log activity and errors

Ways to demonstrate interactive debugging

Configure the VB Conduit Project

We start building the conduit by creating a new VB project. Using the New Project Wizard, choose ActiveX EXE. This will create the conduit as an out-of-process COM server. Normally, this is inefficient due to the marshaling of data between processes during method calls. But it gives us the ability to debug by running the conduit as a standalone process, and intercepting HotSync manager calls.

After creating the project, add in the references to two Palm COM Sync Suite type libraries used by all conduits: ComStandard.dll and ComDirect.dll (see Figure 4-7). As usual, you do this from the VB IDE by choosing the References option from the Project menu.

**Figure 4-7.** **Sync Suite COM references**

Save your project after renaming the default Class1 component and file to something more appropriate; we use SyncNotify and Ch4aNotify.cls in the example. We set the project name as Ch4aCond; note that you should use the default Thread Pool threading model.

Support IPDClientNotify

The HotSync manager expects COM conduits to support the IPDClientNotify public interface. It calls this interface to get information about your conduit, to allow the user to change settings for your conduit, and to synchronize your Palm application with its desktop data.

IPDClientNotify has four member routines that must be supported; these are summarized in Table 4-5.

**Table 4-5:** **IPDNotifyClient public interface**
Interface method	Functionality
GetConduitInfo	Return conduit name, version, and default synchronization type to HotSync manager
CfgConduit	Allow user customization of sync type and return new settings to HotSync manager
ConfigureConduit	Same as CfgConduit, but called by earlier versions of HotSync manager
BeginProcess	Perform synchronization

To support a COM interface in VB, use the Implements keyword. We put this right at the top of our class module:

Implements IPDClientNotify

Any conduits registered with the HotSync manager as ActiveX or COM clients that do not respond to these calls are dropped from the list of active conduits. This happens if you don't implement some part of the interface, or if you throw a runtime error during processing.

You should review the VB documentation if you have never implemented multiple COM interfaces in your class objects before.

GetConduitInfo

When the HotSync manager is initialized, it looks at all the conduits that have been installed on the desktop. The HotSync manager calls the function GetConduitInfo for all registered conduits several times, each time requesting different information. Table 4-6 details the parameters to GetConduitInfo.

**Table 4-6:** **Parameters to GetConduitInfo**
Parameter	Direction/Type	Purpose
InfoType	[IN] EgetConduitInfo	Type of HotSync request
CreatorId	[IN] Long	Creator ID of current application
UserId	[IN] Long	Numeric ID of current user
UserName	[IN] String	String ID of current user

The HotSync manager passes the Creator ID of the application your conduit is registered to handle. This is not redundant, as nothing prevents the registration of your conduit for more than one application.

The HotSync manager also passes the identity of the current desktop user in UserId and UserName. Again, your application might be required to support more than one user. Note that the username is not the Windows login name; instead, it is whatever name the Palm device user chose when installing the HotSync software.

The HotSync manager passes a request for information in the infoType parameter. The request is one of the constants in the public enumeration EGetConduitInfo; GetConduitInfo returns a variant appropriate to the type of request made by the HotSync manager, as shown in Table 4-7.

**Table 4-7:** **Return data types for GetConduitInfo**
Request type	Function return value
`EgetConduitName`	String
`EgetConduitVersion`	Double
`EgetDefaultAction`	Value from enumeration `ESyncType`
`EgetMfcVersion`	Value from enumeration `EMfcVersion`

We have coded GetConduitInfo using a simple Select Case ... End Case statement, with a case for each possible request type. The code for GetConduitInfo is shown in Example 4-2.

Example 4-2: Listing for SyncNotify.GetConduitInfo

Private Function _
IPDClientNotify_GetConduitInfo(ByVal infoType As EGetConduitInfo, _
                               ByVal dwCreatorId As Long, _
                               ByVal dwUserId As Long, _
                               ByVal bstrUserName As String) As Variant
 
    Select Case infoType
    Case eGetConduitName
        IPDClientNotify_GetConduitInfo = "Ch4a Conduit"
    Case eGetConduitVersion
        IPDClientNotify_GetConduitInfo = 3#
    Case eGetDefaultAction
        IPDClientNotify_GetConduitInfo = ESyncTypes.eFast
    Case eGetMfcVersion
        IPDClientNotify_GetConduitInfo = EMfcVersion.ePDMFC_NOT_USED
    End Select
 
End Function

The conduit name is displayed when the user selects the Custom option from the HotSync icon in the system tray, so this should be a string that is meaningful to your users. Palm does not document how the HotSync manager uses your conduit version, so it appears that a conduit can supply any double value.

The HotSync manager uses your conduit's default action when synchronizing, unless the user sets a new default type (see the following section). As with most conduits, we specify fast synchronization as the default:

Case eGetDefaultAction
    IPDClientNotify_GetConduitInfo = PDDirectlib.eFast

The HotSync manager supports multiple conduit architectures, among them conduits implemented using the Microsoft Foundation Class framework. ActiveX conduits should return ePDMFC_NOT_USED when asked for the MFC version, to avoid confusing the HotSync manager.

CfgConduit

When the user needs to change your conduit's behavior, the HotSync manager calls the interface function CfgConduit. This call is always in response to user interaction with a dialog similar to that shown in Figure 4-2. Table 4-8 details the parameters to CfgConduit.

**Table 4-8:** **Parameters to CfgConduit**
Parameter	Type/direction	Purpose
CreatorId	[IN] Long	Creator ID of current application
UserId	[IN] Long	Numeric ID of current user
UserId	[IN] String	String ID of current user
PathName	[IN] String	User folder in HotSync directory
SyncPerm	[IN/OUT] `EsyncTypes`	See text
SyncTemp	[IN/OUT] `EsyncTypes`	See text
SyncNew	[IN/OUT] `EsyncTypes`	See text
SyncPref	[OUT] `ESyncPref`	Tell HotSync manager that changes are permanent or temporary

Just like GetConduitInfo, the HotSync manager passes CfgConduit the application's Creator ID and the identity of the current desktop user. In addition, the HotSync manager passes the location of a folder on the desktop for this user. The folder location is usually relative to the HotSync manager; with our configuration, this looks something like:

C:\CDK401\Common\Bin\C4.01\HolmesM

Here's what the Palm Windows Conduit Reference says about the three sync-type parameters:

SyncNew: The type of synchronization to perform for a new device
SyncTemp: The type of synchronization to perform on a onetime (temporary) basis
SyncPerm: The type of synchronization to perform on an ongoing (permanent) basis

The implication is that you set these variables to tell the HotSync manager how to run your conduit under different circumstances. Unfortunately, reading and setting these variables from a COM conduit does not work exactly as documented.

WARNING: On entry, you will find that all the variables have the same value, usually the default synchronization type for your conduit. On exit, you must set all three variables to the same value.

The HotSync manager uses the SyncPref variable to determine if the synchronization choice is to be made permanent, or if it is for the next synchronization session only. Set this value to either ePermanentPreference or eTemporaryPreference as appropriate.

Pages: 1, 2, 3