Palm OS 3.5 开发 -- 第二部分，HotSync 事务通道

• 下载 Palm 测试应用程序及源代码 - 9.09 Kb
• 下载示例事务通道项目 - 16 Kb

Palm 测试应用程序

引言

在本系列的上一篇文章中，我介绍了如何开始开发 Palm 手持设备应用程序。这次，我将向您展示 HotSync 事务通道平台的一瞥。

HotSync 是 Palm 手持设备与 PC 之间的主要接口。通常，您将手持设备放入底座，按下 HotSync 按钮，PC 和手持设备就会开始同步所有日历、待办事项列表、通讯录等记录。在此过程中，PC 通过 HotSync 事务通道应用程序处理所有数据。手持设备仅处于 HotSync 模式，处理任何数据库请求，直到 HotSync 完成。PC 上的 HotSync Conduit API 支持轻松地从手持设备迭代数据库和记录。虽然通常认为 HotSync 事务通道用于同步，但实际上它可以对数据执行任何操作。

事务通道的结构

Palm Desktop 在 PC 上维护事务通道。它会维护一个 Palm Home，其中包含桌面可执行文件以及相关的工具和任何包含的事务通道。CDK 是 Palm Desktop 工具的基础实现，但不包含实际的 Palm Desktop 应用程序。

事务通道是一个安装在 PC 端（作为 DLL）的应用程序，它实现了支持的函数调用。它通常设计用于响应具有特定 Creator ID 的数据库的存在，例如，“addr”用于通讯录应用程序。在大多数情况下，事务通道会将数据库的 PC 版本保存下来。如果 PC 数据库已存在，它会比较记录以进行双向同步，并相应地更新手持设备和 PC 的记录。

事务通道 DLL 必须包含以下由 HotSync Manager 调用导出的函数：

• SInt32 OpenConduit(PROGRESSFN pFn, CSyncProperties &syncProps)

  用于启动此事务通道的 HotSync。

• SInt32 GetConduitInfo(ConduitInfoEnum infoType, void *pInArgs, void *pOut, UInt32 *pdwOutSize)
• SInt32 GetConduitName(char *name, UInt16 nLen)
• UInt32 GetConduitVersion(void)

  用于在 HotSync Manager 启动期间检索有关事务通道的信息。

• SInt32 CfgConduit(ConduitCfgEnum cfgType, void *pArgs, UInt32 *pdwArgsSize)

  当用户右键单击 HotSync Manager 并为事务通道选择“自定义”->“更改”时调用。此函数必需弹出对话框，允许用户查看/更改同步类型。

• SInt32 ConfigureConduit(CSyncPreference &syncPrefs)

  此函数对于 HotSync Manager 3.0 之前的版本（非常旧）是必需的。在 ConfigureConduit() 失败的情况下也会调用。CfgConduit() 包含 Creator ID、用户名和临时同步首选项的附加字段。

事务通道注册

为了让 HotSync Manager 知道哪些事务通道可用，必须注册它们。您可以使用 CondMgr.dll 中的事务通道注册 API 来完成此操作。

事务通道开发要求

• Windows C/C++ 编译器（通用事务通道项目向导需要 MS Visual C++.NET 2002+）。
• CDK，用于其 C 头文件、DLL 导入库、框架、工具和参考资料。
• POSE 用于调试（可选）。

事务通道工具

参考文档

请务必查看 CDK 安装目录中 Common\Docs 文件夹下的帮助文件。这些文件将包含您所需的所有参考信息。

HotSync Manager

HotSync Manager 协调 HotSync 进程的执行。它将图标放置在系统托盘中，并等待来自手持设备的 HotSync 请求。收到 HotSync 请求后，它将首先读取手持设备的用户帐户，然后遍历事务通道，最后备份手持设备数据库。

已注册的事务通道将包含数据，例如：文件和路径（基于用户的主目录）、Creator ID、远程数据库名称和优先级。这些参数将作为事务通道存储其 PC 文件、从手持设备获取具有哪些 Creator ID 的数据库以及事务通道的处理顺序的指南。

备份过程会将 PDB 文件从手持设备直接复制到用户的备份目录，用于所有标记为备份的数据库。您可以使用 Filez 来修改备份标志。如果您丢失 Palm 的电池电量导致所有数据丢失，这将非常有用。下次 HotSync 将自动恢复备份的 PDB 和 PRC 文件。如果默认未设置，请务必为您的应用程序生成的任何 PDB 文件启用此标志。

HotSync Manager 还可以使用 Notifier。这些是 DLL，在 HotSync 开始和结束时会收到通知。但这将是另一篇文章的主题。

事务通道配置

事务通道配置工具 CondCfg.exe 允许开发人员手动维护用户和系统事务通道的注册表。

事务通道检查器

事务通道检查器允许您在事务通道执行期间查看实时日志生成。它通过“hotsync.exe -ic”启动。

POSE 中的 HotSync

您可能希望设置 POSE 与主机 PC 进行 HotSync，以便您可以同步一些可用的数据，或者您可能正在开发一个 HotSync 事务通道。要做到这一点，需要进行一些配置。

配置 PC 上的 HotSync

• 确保 HotSync Manager 正在运行。
• 右键单击系统托盘中的 HotSync Manager 图标，然后在弹出菜单中启用“网络”。

配置 POSE

• 右键单击 POSE，然后单击“设置”->“属性...”
• 选中“将 NetLib 调用重定向到 TCP/IP”复选框。单击“确定”。

配置 POSE 中的手持设备 HotSync

• 在“系统”类别中打开“HotSync”应用程序。
• 转到菜单“选项”->“调制解调器同步首选项”。设置为“网络”。
• 返回菜单“选项”->“主要 PC 设置”。在“主要 PC 地址”中输入“127.0.0.1”。
• 在 HotSync 应用程序中，选择“调制解调器”。点击“选择服务”，然后只需点击“完成”。服务本身并不重要，但必须选择一个。

现在，您将能够使用 POSE 与主机 PC 的 HotSync Manager 进行 HotSync。

事务通道 API

Palm 在 Palm Home 目录中提供了几个 DLL，用于各种 API 调用。这在 C++SyncReference.chm 帮助文件中得到了最好的介绍。

绑定到 Palm DLL

设计理念是使用用户已安装的 DLL。通常不建议将 Palm DLL 打包到您的项目中，以避免版本冲突。不同版本的 Palm DLL 可能行为不同，或以不同格式或位置存储数据。

如果您的项目将安装在 Palm Home 目录以外的独立目录中，则 DLL 将不在导入库加载的路径中。在这种情况下，有两种解决方案：使用 LoadLibrary() 和 GetProcAddress() 进行晚期绑定，或者通过在任何 Palm API 调用之前设置工作目录来使用 VC++ 的延迟加载。要使用这些方法，您需要知道 Palm 的 bin 路径。为此，尽管我最初警告过，但可以打包 CondMgr.dll，以便您可以调用 CmGetSystemHotSyncExecPath() 来检索 HotSync.exe 的路径名。去掉 HotSync.exe，即可显示 Palm 的 bin 路径。然后，释放已加载的 CondMgr.dll，并从获得的路径重新加载必要的 DLL。如果您使用的是延迟加载，则可以执行 SetCurrentDirectory()，然后尝试像使用普通 DLL 导入库一样进行 Palm API 调用。

调试事务通道

HotSync Manager 在 HotSync 后会有一个日志供您阅读。只需右键单击系统托盘图标，然后单击“查看日志”。

但是，如果您想在 HotSync 期间实时查看日志，可以使用事务通道检查器。要做到这一点，您必须使用 CDK 版本的 HotSync Manager，并使用命令行“hotsync.exe -ic”启动它。HotSync Manager 和事务通道检查器将一起启动。在下一次 HotSync 中，事务通道检查器将开始滚动生成的日志输出。

与任何 DLL 一样，您也可以在代码中放置断点，以便在 HotSync 期间单步执行事务通道代码。配置项目，使调试命令和工作目录指向 hotsync.exe 的目录。包含“-ic”作为命令行参数，以便也能看到事务通道检查器。请注意，手持设备上的 HotSync 进程将在 30 秒后超时，因此您在单步执行代码时必须迅速。提示：可以通过频繁调用 SyncYieldCycles() 来续订此超时。

CDK 4.0.3 通用事务通道框架

CDK 提供了一个相当不错的 C++ 框架来构建事务通道。如果使用 Visual C++.NET 2002 或更高版本，您将获得一个新建项目向导来创建 Palm OS 事务通道项目。我将概述使用此框架的过程。

让我们创建一个事务通道，该通道与本文开头展示的、包含在本文中的手持测试应用程序进行交互。该手持应用程序允许用户创建文本行，每行最多 31 个字符，并在文本字段旁边显示记录索引和记录 ID 的低 16 位值。将此应用程序安装在您的手持设备（或 POSE）上并创建一些记录。手持应用程序使用一个名为“Test database”的数据库，其 CreatorID 为“Test”。

使用新建项目向导创建事务通道项目

以下是通用事务通道框架中需要了解的重要基类：

• CSynchronizer：封装了整个事务通道同步过程。
• CHHMgr：手持设备数据库的接口。
• CPcMgr：PC 数据库的接口。

HotSync 操作将按以下顺序进行：

• gencond.cpp，OpenConduit()：HotSync Manager 调用以启动同步的导出 DLL 函数。它实例化 CSynchronizer，然后调用 Perform() 方法。
• CSynchronizer::Perform()：开始同步。实例化 HHMgr 和 PCMgr 类。确定要执行的同步类型，并根据同步类型调用相应的方法。
  • CSynchronizer::CopyHHtoPC()：单向复制到 PC。
  • CSynchronizer::CopyPCtoHH()：单向复制到手持设备。
  • CSynchronizer::PerformFastSync()：仅同步已修改记录的快速同步。
  • CSynchronizer::PerformSlowSync()：同步所有记录的慢速同步。

现在，使用 CondCfg.exe 注册您的事务通道，如下所示：

运行 HotSync.exe -ic 以启动事务通道检查器。现在，从您的 Palm 或 POSE 开始 HotSync。在生成的日志中，您应该能够找到您的事务通道输出。

Current conduit: Name: H:\code\TestConduit\Debug\TestConduit.dll, 
                                                 Creator ID Test
        Found task and attempting to load conduit.
SyncReadSystemInfo()
SyncRegisterConduit()
SyncOpenDB()
SyncCloseDB()
SyncCloseDBEx()
SyncOpenDB()
SyncGetDBRecordCount()
SyncReadRecordByIndex()
SyncReadRecordByIndex()
SyncReadRecordByIndex()
SyncReadRecordByIndex()
SyncResetSyncFlags()
SyncCloseDB()
SyncCloseDBEx()
OK Generic Conduit
SyncUnRegisterConduit()

然后，查看已安装的 CDK 路径。HotSync Manager 会为您的用户帐户创建一个文件夹，其中包含所有同步文件。在其中，您会找到一个“Test Conduit”子文件夹，其中包含来自您的事务通道的同步数据库：Test.dat 和 Test.BAK，分别是 HotSync 的当前和上一个数据库文件。注意：这些文件采用通用事务通道框架确定的专有格式。

如果您在手持设备的“Test database”文件上启用了备份标志，您将在 PDB 格式的 Backup 文件夹中看到其备份。

您可以通过删除手持设备上的“Test database”文件来测试您的事务通道是否真正有效，使用像 Filez 这样的工具，然后再次运行 HotSync。事务通道将自动重新创建数据库，并用其从上次 HotSync 保存的记录填充它。注意：请确保 Backup 文件夹中没有数据库的备份文件，否则您的数据库将在事务通道启动前恢复。

使用本文的示例事务通道项目

由于 CDK 的新建项目向导的特性，它会创建一个 Visual Studio 项目，其中包含对 CDK 安装路径中源文件和头文件的引用。在我的机器上，我将 CDK 安装到了 H:\code\palm\cdk403，因此，示例将包含对该路径的许多引用。由于您可能将 CDK 安装在其他位置，因此您需要使用文本编辑器对 TestConduit.vcproj 文件中的路径进行搜索/替换，然后再打开它。

下一步？

通用事务通道框架可以帮助您开始使用一个功能齐全的事务通道，但您需要对其进行自定义才能执行任何其他操作。以下是一些可能常见的场景：

我需要事务通道保存到不同的文件格式。

重写 CPcMgr::StoreDB() 方法并编写自己的代码。您还需要更新 CPcMgr::RetrieveDB() 以将您的格式加载到内存中。内存存储通过 m_pRecordList 数组进行处理。如果您想以 PDB 格式存储和检索，您需要根据 PDB 文件格式规范 编写自己的代码。

我需要处理同一应用程序的多个数据库的同步。

更新 OpenConduit() 以便为每个数据库创建一个 CSynchronizer 对象。更新或创建 CSyncProperties 对象，就像标准代码所做的那样，为每个 CSynchronizer 实例化。如果数据库名称不是固定的，您将需要使用 SyncFindDbByTypeCreator() 遍历手持设备的数据库目录。

我如何安装事务通道？

首先，阅读 CDK 文档中的“编写安装程序”部分。然后，将您的安装程序代码捆绑到 InstallShield 或 NSIS 等安装程序 SDK 中。

等等！Palm 有 CDK 6.0.1。难道它不更新、更好吗？

是也不是。CDK 6.0.1 对通用事务通道框架进行了小幅更新，将其帮助集成到 MSDN Library 中，支持系统和用户事务通道，并支持 Palm OS 5.0 及更高版本。开发工具向后兼容 Palm OS 3.5，**但是**通用事务通道框架除外。不幸的是，该框架被重新设计以针对扩展数据库 API，而 Palm OS 3.5 不支持该 API（仅支持经典数据库）。这很可能是 Palm 将旧的 4.0.3 版本在线提供下载的原因。

结论

就这样。我希望这个系列文章能为读者提供轻松开始使用 Palm 手持设备平台的背景知识。

参考文献

• Palm CDK（需要免费注册）。
• POSE：Palm OS 模拟器.
• Filez，用于文件管理的 Palm 工具。
• 编写安装程序，来自 CDK 文档。
• Palm OS 技术邮件列表.
• MMCd Tools，一个开源的 HotSync 事务通道和文件导出工具，用于第一部分中提到的 MMCd Datalogger。

历史

• 2005.12.31：已发布。