ONDotNet.com    
 Published on ONDotNet.com (http://www.ondotnet.com/)
 See this if you're having trouble printing code examples


O'Reilly Book Excerpts: Programming Visual Basic for the Palm OS

Building Palm Conduits, Part 2

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 the Palm OS, learn how to design conduits using VB for the Palm OS.

Conduit Design

There are several major design principles for a conduit. The first, and most important, is that the conduit runs as quickly as possible. No one wants to wait while synchronization grinds on and on. Honoring the fast and slow sync flags will help you to optimize performance. A fast conduit also minimizes the use of the Palm device's serial port. This is important, because serial port use can drain the PDA's batteries very quickly.

The second principle is that a conduit must always move application data in a natural way between the Palm device and the desktop. Your user relies completely on this behavior. She also relies on the conduit to restore all data in case of a disaster. If your conduit is not correctly implemented, or has bugs, user acceptance of your application will suffer greatly.

A third principle is that your conduit must be able to run without attention from the user. While this is a good design principle for software in general, it is especially important for a conduit. This is because the user might be synchronizing from a remote location, communicating with the HotSync manager over a modem or network connection. The user will not be able to respond to any prompts or dialog boxes that a conduit might display on the desktop. This will cause the entire HotSync session to hang.

Palm provides some more design guidelines in the C/C++ Conduit Companion; you should certainly study those before implementing your own conduit.

If you are building a mirror-image conduit, then follow the logic diagrammed earlier in Tables 4-2, 4-3, and 4-4, as they apply to your application. If you don't allow desktop editing of data in your application, for example, then your conduit doesn't have to support it, either.

Having a user interface and allowing the user to override the conduit's default behavior will help you achieve acceptance. If at all possible, support uploading or downloading all records from your user interface.

Note that if your Palm database design maps into a relational database, and you used the AppForge database tools described in Chapter 4, then you can likely use the Universal Conduit. We discuss the pros and cons of the Universal Conduit in Chapter 5, and show you how to use it to integrate SQL Server data into your applications.

When Not to Use a Conduit

Not all synchronization situations require you to implement a conduit. It is perfectly appropriate to make a new database from scratch and download it to the device, if you know that all or most of your application's data has changed.

Simply generate your database from the new data, and put it in the HotSync installation directory.[2] The database will be automatically deployed to the device with the next synchronization, overwriting any existing PDA data in the process. If your application has a database that is read-only, and that is periodically refreshed, you can use this technique. If your sales department produces a list of prices that changes monthly, then you don't need to execute a conduit every day.

In This Series

Building Palm Conduits, Part 4
This final book excerpt in this series from Programming Palm OS with Visual Basic covers data formats, and packing and unpacking record data in a Palm application.

Building Palm Conduits, Part 3
Learn about synchronization logic in building Palm conduits, in this excerpt from Programming Visual Basic for the Palm OS.

Building Palm Conduits, Part 1
This excerpt from Programming VB for PalmOS, offers an introduction to building conduits, synchronization software that connects Palm apps and data stores.

Not having a conduit can greatly simplify the distribution of your application. You don't have to worry about developing an installation script for your conduit and its associated runtime objects.

If the Palm Desktop is configured properly, the Windows default shell action for PRC and PDB files is to call the Palm Instapp.exe program, which will copy the file into the Palm desktop installation directory.

This means that you can post your database files on the Web or in ZIP archives. When your user downloads or extracts your file and double-clicks it, it is queued for installation at the next HotSync.

Installing the CDK

The Conduit Development Kit (CDK) is freely downloadable from the Palm web site.[3] The CDK contains libraries and runtime bindings for VB and COM, as well as the C/C++ language. The InstallShield wizard puts everything into the directory you select (see Figure 4-3).

Figure 4-3. CDK directory structure

You can choose to install only the COM libraries, samples, and documentation by using the custom installation procedure and deselecting the C/API. We recommend performing a full installation, because the C/API contains some additional documentation you will find useful.

The Com folder contains the VB tutorial and sample projects, an installation tool, and another directory that simply contains links to the documents mentioned above. Most of the sample projects in the CDK are primers that focus on explaining at most one or two parts of the CDK. There is also a longer example, SyncSamp, which replaces the default Memo conduit and illustrates a complete conduit.

The Common folder contains the CDK programs and libraries used when developing conduits. This folder also contains the documentation, in both Adobe PDF and Microsoft Help formats. Earlier releases of the CDK runtime are supplied for backward compatibility; these won't help you, because only the most recent release supports VB development.

If you have the Palm desktop software installed on your development machine, as is required to run AppForge, there are some issues you should be aware of when you install the CDK. By default, your system uses the HotSync manager that was installed with the Palm desktop software. Unfortunately, the ActiveX objects needed to develop and debug conduits are not installed with earlier releases of the Palm desktop.

If you have the luxury of developing your applications and software on separate computers, the following step is unnecessary. Otherwise, you will have to alter the desktop configuration so that the new HotSync manager runs during the synchronization process. Use the Microsoft RegEdit.exe tool, and alter the two registry keys as shown in Example 4-1. Note that the location of the updated HotSync manager depends on where you installed the CDK on your filesystem.

Example 4-1: Registry settings for HotSync manager

HKEY_CURRENT_USER\Software\U.S. Robotics\Pilot Desktop\Core
    HotSyncPath = C:\CDK401\Common\Bin\C4.01\Hotsync.exe
    Path = C:\CDK401\Common\Bin\C4.01

This is a good time to run the CDK tutorial SimpleDB, which shows how to run and debug a program under the control of the HotSync manager. This is how all conduits are executed, and it is important that you get comfortable with this environment. Running the tutorial also ensures that all of the CDK components are properly installed, and that the new HotSync manager is running correctly.

To run the tutorial, use the CondCfg.exe program to register the VB development environment as a conduit. Once the HotSync manager calls the VB IDE, you are in control and can test and debug your conduits with all the powerful VB features to which you are accustomed.

Let's walk through the steps required to configure the tutorial. Start the CondCfg.exe tool to show all the currently registered conduits, and to add, edit, and delete conduits. If you are developing on your own Palm desktop, be careful not to disturb the settings for the native Palm applications! We disable all conduits except those actually under development; this both increases the speed of the synchronization process and provides some security from data corruption. Press the Add button to bring up the Conduit Information dialog, into which you enter the settings for your conduit (see Figure 4-4). First, you must enter ComConduit.dll in the name field. The HotSync manager uses this DLL to locate and instantiate COM conduits.

Figure 4-4. CondCfg.exe registration screen

Because each conduit handles exactly one application on the Palm device, you must enter the unique Creator ID of your application. (There must be only one conduit registered for any Palm application. CondCfig.exe will not allow you to register a second conduit for the same application, or, more precisely, an application with the same Creator ID).

TIP:   If there is no application on the Palm device with this ID, then the conduit will not run. You must install your Palm application first.

For our sample conduit, we entered Ch4a as the Creator ID. In addition, we entered Ch4aDB in the optional remote database field. As we'll see later, the HotSync manager provides the conduit with a more accurate list of databases during an actual synchronization session.

In the extra information group box at the bottom of the dialog, select the COM Conduit radio option button. Enter the full path to the VB IDE in the COM client field.

Leave all the other fields blank or with the default values. These settings were shown earlier in Figure 4-4. Press the OK button to register the new settings, and restart the HotSync manager. Then exit the configuration tool.

Now put the Palm device into the cradle and press the HotSync button. Although the synchronization process runs normally, the VB IDE doesn't activate. That is because the HotSync manager could not find an application on the Palm device with a Creator ID of Ch4a.

You will need to download our sample application for this chapter and install the application file Ch4a.prc. After the application is installed, perform a HotSync one more time. This time, the HotSync manager on the desktop displays the message Status: Synchronizing COMConduit, and the VB IDE pops up.

Now you can test your environment by opening SimpleDB.vbp in the CDK Tutorial folder. This VB project opens the native Memo application, and reads all the records that match a search term. Set a breakpoint in the button click event, and press F8 to step through the program. Note that Palm device displays Synchronizing Memo Pad, because the Memo database has been opened during a HotSync session. You are now communicating as a conduit with the Palm device from VB!

If the VB IDE doesn't appear, put the HotSync manager into its verbose mode. First, stop the HotSync manager by right-clicking on its icon in the Windows system tray, and select Exit. Next, restart the HotSync manager with the -v option from the command line. After synchronizing, you can review the diagnostic log for errors. To do this, right-click on the icon and select View Log.

If the SimpleDB project doesn't connect to the Palm, or exhibits other errors, check that the Palm conduit references are set correctly (these are shown later in this chapter in Figure 4-7). You do this from the VB IDE by choosing the References option from the Project menu. If these references are missing, try registering those ActiveX libraries by hand and restarting VB.

Nuts and Bolts

If you stepped through the SimpleDB CDK sample project, you saw that the VB code manipulated the Palm device's databases and records using COM objects. Let's dig a little deeper into the HotSync architecture to see how a conduit communicates with the Palm device.

Recall from Figure 4-1 that the COM Sync Suite provides the interface to the HotSync manager and the Palm device.

The Sync Suite itself has several layers to isolate its interface from the underlying details of the HotSync application and to support both VB/COM and C/C++ conduits. This layered approach frees the VB programmer from worrying about messy details such as which serial port the HotSync manager is using to communicate with the Palm device.

To simplify conduit development, the Sync Suite provides COM objects and classes that encapsulate the HotSync manager, the user, and databases on the Palm device. A utility class is provided to handle things like Motorola byte ordering and unique record identifiers.[4] These classes and their relationships are shown in Figure 4-5.

Figure 4-5. Sync Suite class hierarchy

There are VB projects in the CDK that cover these objects and interfaces. Rather than enumerate all of them here, we will discuss the major ones we encounter as we develop our simple conduit. Once you understand the framework, you can use the VB Object Browser and the Conduit Reference manual to find the special properties you need for your conduit.

The HotSync manager expects your ActiveX conduit to implement the IPDClientNotify interface, which it calls when it needs your services, either to synchronize or to access configuration settings and preferences.

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:

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.

Let's look at our implementation of this interface function; it is really quite simple. Example 4-3 shows the code for CfgConduit.

Example 4-3: Listing for SyncNotify.CfgConduit

Private Sub IPDClientNotify_CfgConduit(ByVal nCreatorId As Long, _
                                       ByVal nUserId As Long, _
                                       ByVal bstrUserName As String, _
                                       ByVal bstrPathName As String, _
                                       ByVal nSyncPerm As ESyncTypes, _
                                       ByRef nSyncTemp As ESyncTypes, _
                                       ByRef nSyncNew As ESyncTypes, _
                                       ByRef nSyncPref As ESyncPref)
 
    ' Set up the form: type of sync to perform, user directory
    SyncForm.SetFields nSyncNew
    
    ' Let the user make choices, then retrieve them from the form. The
    ' form must be modal, this is required by COM.
    SyncForm.Show vbModal
    SyncForm.GetFields nSyncNew, nSyncTemp, nSyncPerm, nSyncPref
 
End Sub

The project includes a form called SyncForm, through which the user makes changes. The first thing we do is to call SetFields, a public function in the form module. It sets private form variables that are used in the Load event to initialize the controls. Without it, we'd have to interact with the form elements directly. This is risky because accessing a form element usually causes the form to be shown before you are ready.

Next, we show the form and let the user interact with the dialog. Note that the form must be shown modally: a COM object cannot display a non-modal form without a lot of extra steps. The form will fail to load if you do not supply the VBModal parameter:

SyncForm.Show vbModal

SyncForm

Since this is a mirror-image conduit, our custom user interface is designed to look just like the Palm native applications.

The form is simple, consisting of a group of radio buttons for the sync types, a checkbox for making the selected sync preference the default, and OK and Cancel buttons. We added an image control, to depict graphically what each type of synchronization does. The control's bitmap is taken from a screen shot of the Palm Address conduit.

The form user interface was shown earlier, in Figure 4-2. In our example, the form name is SyncForm, and it is saved as Ch4aForm.frm.

Your conduit might not need to support all these synchronization types, so feel free to remove choices. For example, we have disabled the PCtoHH option in our sample conduit (see Figure 4-2). But you should always include an option for your conduit to do nothing. We guarantee that this option will be used more often than you think!

And if your conduit has special requirements or extra configuration options, this is the place to expose them.

Here is the implementation of SetFields, which was discussed earlier:

Public Sub SetFields(ByVal nSyncPerm As Long)
    m_nSyncType = nSyncPerm
End Sub

The code for the form Load event is shown in Example 4-4. Load assumes that the private form variables have already been set to appropriate values--so be sure to call SetFields before loading the form. In Load, we set the radio buttons and checkbox to the states indicated by the public form variable values.

Example 4-4: Listing for SyncForm.Load

Private Sub Form_Load(  )
 
    ' Set the radio buttons based on the HotSync information
    optSync.Value = False
    optHHToPC.Value = False
    optPCToHH.Value = False
    optDoNothing.Value = False
    
    Select Case m_nSyncType
    Case eHHtoPC
        optHHToPC.Value = True
    Case ePCtoHH
        optPCToHH.Value = True
    Case eDoNothing
        optDoNothing.Value = True
    Case Else
        optSync.Value = True
    End Select
    
    ' Set the preference check box - default to temporary by convention
    m_nSyncPref = eTemporaryPreference
    chkDefault.Value = Unchecked
 
    ' Assume the user will cancel
    m_bCancel = True
    
End Sub

The only remarkable thing about Load is that it assumes any user changes will be temporary, unless explicitly made permanent. This is the conventional behavior for the Palm native conduits, and it is a good idea for your user interface to follow suit:

m_nSyncPref = eTemporaryPreference
chkDefault.Value = Unchecked

The user can exit the form a variety of ways. For this reason, the values in the form controls are only transferred to the form variables in the OK button's Click event (see Example 4-5). At this time, the cancellation flag is set to false, the form is unloaded, and control returns to CfgConduit.

Example 4-5: Listing for SyncForm.btn_OK.Click

Private Sub btnOk_Click(  )
 
    ' Transfer form variables to
    If optSync.Value Then
        m_nSyncType = ESyncTypes.eFast
    ElseIf optPCToHH.Value Then
        m_nSyncType = ESyncTypes.ePCtoHH
    ElseIf optHHToPC.Value Then
        m_nSyncType = ESyncTypes.eHHtoPC
    ElseIf optDoNothing.Value Then
        m_nSyncType = ESyncTypes.eDoNothing
    End If
 
    If chkDefault.Value = Checked Then m_nSyncPref = ePermanentPreference
 
    ' Flag used in GetFields(  ) to see if the variables are valid
    m_bCancel = False
    Unload Me
 
End Sub

If the user exits the form, either by pushing the Cancel button directly or pressing the ESC key, control is transferred to the Cancel button's Click event. We don't show that routine here, but in it, the cancellation flag is set to true, the form is unloaded, and control is returned to CfgConduit.

At this point, the user has dismissed the form. Now we retrieve the new variable settings using the GetFields routine (which is smart enough not to overwrite any values if the user canceled rather than applied the changes). The code for GetFields is shown in Example 4-6.

Example 4-6: Listing for SyncForm.GetFields

Public Sub GetFields(ByRef nSyncNew As Long, _
                     ByRef nSyncTemp As Long, _
                     ByRef nSyncPerm As Long, _
                     ByRef nSyncPref As Long)
 
    If m_bCancel Then Exit Sub
 
    ' Retrieve the "default" setting from the check box
    nSyncPref = m_nSyncPref
 
    ' Retrieve the action setting from the radio buttons
    nSyncNew = m_nSyncType
    nSyncTemp = m_nSyncType
    nSyncPerm = m_nSyncType
 
End Sub

If the user has canceled, then none of the form variables are transferred in GetFields. And note that all three sync-type parameters are set to the same user-configured value, despite the Conduit Reference documentation, for the reasons discussed earlier.

ConfigureConduit

This interface function is used by versions of the HotSync manager prior to release 3.0.1. For later releases of the HotSync manager, this function is only called if your conduit doesn't implement the CfgConduit interface. Table 4-9 lists the parameters for SyncNotify.ConfigureConduit.

Table 4-9: Parameters for SyncNotify.ConfigureConduit

Parameter

Type/direction

Purpose

PathName

[IN] String

User folder in HotSync directory

Registry

[IN] String

Numeric ID of current user

SyncPref

[IN/OUT] EsyncPref

Tell HotSync manager that changes are permanent or temporary

SyncType

[IN/OUT] EsyncTypes

The kind of synchronization to perform

The code for ConfigureConduit simply returns default values for the two output parameters:

Private Sub IPDClientNotify_ConfigureConduit(ByVal bstrPathName As String, _
                                             ByVal bstrRegistry As String, _
                                             ByRef nSyncPref As ESyncPref, _
                                             ByRef nSyncType As ESyncTypes)
 
    nSyncType = PDdirectlib.eFast
    nSyncPref = PDdirectlib.ePermanentPreference
 
End Sub

BeginProcess

The HotSync manager calls the interface function BeginProcess when an actual synchronization should occur. At this point, you can assume that the Palm device is in the cradle and the user has pressed the HotSync button.

Our implementation of BeginProcess is intentionally minimal; we delegate all the real work of synchronization to a private class. The code for BeginProcess is shown in Example 4-7.

Example 4-7: Listing for SyncNotify.BeginProcess

Private Function IPDClientNotify_BeginProcess(  ) As Boolean
 
    ' Create our sync object and do the work
    Dim Worker As New SyncLogic
    Worker.Synchronize
    
    ' Return false to signal completion!
    IPDClientNotify_BeginProcess = False
 
End Function

BeginProcess should return False when it has completed. That signals the HotSync manager that it can skip to the next conduit. Returning False doesn't indicate that your conduit was successful; instead, it means that it is finished executing. Later, we will see how to return status information to the user in the HotSync log.

The real work of synchronization occurs in these lines:

Dim Worker As New SyncLogic
Worker.Synchronize

Right away, you should notice that the Worker.Synchronize method doesn't take any arguments. It gets all the information it needs to synchronize from publicly creatable COM objects supplied by the Sync Suite API.

We have finished implementing the IPDClientNotify interface, including the user interface required to support configuring the conduit. The conduit is complete from the perspective of the HotSync manager: the conduit can identify itself and its properties, it can be configured, and it responds to synchronization requests.

Roger Knoell s a software developer with 10 years experience leveraging high-level language development tools and environments.

Patrick Burton has been programming in C/C++ for most of his career. His experience inlcludes algorithm development for embedded satellite receivers, Linux system programming, and Windows programming using the Win32 API and Microsoft Found Classes (MFC).

Matthew Holmes has been developing computer software for 15 years. He cherishs his liberal arts degree in Foreign Affairs from the University of Virginia, and he holds a graduate degree in Computer Science from George Mason University.

In the next installment, learn about synchronization logic.

Programming Visual Basic for the Palm OS

Related Reading

Programming Visual Basic for the Palm OS
By Matthew Holmes, Patrick Burton, Roger Knoell

Return to the .NET DevCenter

Copyright © 2009 O'Reilly Media, Inc.