iAnywhere.com - 第 5 课：浏览 TestMessage 客户端源代码

QAnywhere 用户指南

教程：QAnywhere 示例应用程序

第 5 课：浏览 TestMessage 客户端源代码

背景

本节教程引导您简要地浏览 TestMessage 客户端应用程序的源代码。

大量代码实现了可用于发送、接收和查看消息的 Windows 界面。不过，教程的这一部分侧重于提供给 QAnywhere 的这部分代码。

您可以在 SQL Anywhere Studio 安装目录的 Samples\QAnywhere 子目录中找到 TestMessage 源代码。

提供了多个版本的 TestMessage 源代码。以下版本用于 Windows 2000 和 Windows XP：

使用 Microsoft 基础类构建的 C++ 版本是以 Samples\QAnywhere\Desktop\MFC\TestMessage\TestMessage.sln 的形式提供的。
基于 .NET Framework 构建的 Visual Basic .NET 版本是以 Samples\QAnywhere\Desktop\.NET\VB\TestMessage\TestMessage.sln 的形式提供的。
基于 .NET Framework 构建的 C# 版本是以 Samples\QAnywhere\Desktop\.NET\CS\TestMessage\TestMessage.sln 的形式提供的。
基于 .NET Framework 构建的 C++ 版本是以 Samples\QAnywhere\Desktop\.NET\CPP\TestMessage\TestMessage.sln 的形式提供的。

下面的版本用于 Pocket PC：

基于 .NET Compact Framework 构建的 C# 版本是以 Samples\QAnywhere\PocketPC\.NET\CS\TestMessage\TestMessage.sln 的形式提供的。

必需的软件

Visual Studio .NET 2003 需要打开解决方案文件并构建 .NET Framework 项目和 .NET Compact Framework 项目。

浏览 C# 或 Visual Basic .NET 源代码

本节将引导您浏览 C# 源代码。这两个版本的结构很类似。

此教程不是让您查看应用程序中的每一行，而是挑出对理解 QAnywhere 应用程序特别有用的某些行。使用 C# 版本来演示特定的行。

打开您感兴趣的 TestMessage 项目版本。

双击解决方案文件以在 Visual Studio .NET 中打开项目。例如，Samples\QAnywhere\Desktop\.NET\CS\TestMessage\TestMessage.sln 是一个解决方案文件。有多个解决方案文件用在不同的环境中。
确保显示 [Solution Explorer]。

您可以从 [View] 菜单中打开 [Solution Explorer]。
检查 [Source Files] 文件夹。

有两个文件特别重要。MessageList 文件 (MessageList.cs) 接收消息并允许您查看消息。NewMessage 文件 (NewMessage.cs) 允许您构造和发送消息。
从 [Solution Explorer] 中打开 MessageList 文件。
检查所包含的命名空间。

每个 QAnywhere 应用程序都需要 iAnywhere.QAnywhere.Client 命名空间。定义此命名空间的程序集以 DLL iAnywhere.QAnywhere.Client.dll 的形式提供，位于 SQL Anywhere Studio 安装目录的 ce 或 win32 子目录中。在您自己的项目中，必须以引用的形式添加此 DLL。使用以下行在每个文件的顶部包含该命名空间：
```
using iAnywhere.QAnywhere.Client;
```

检查 MessageList_Load 方法。

此方法执行 QAnywhere 应用程序共有的初始化任务：

创建 QAManager 对象。
```
_qaManager = 
QAManagerFactory.Instance.CreateQAManager( null );
```
QAnywhere 提供 QAManagerFactory 对象来创建 QAManager 对象。QAManager 对象处理 QAnywhere 消息传递操作：特别是接收消息（从队列中获取消息）和发送消息（将消息置于队列中）。

QAnywhere 提供两类管理器：QAManager 和 QATransactionalManager。两者区别在于当使用事务管理器时所有的发送和接收操作都在一个事务内发生，因此要么发送（或接收）所有消息，要么都不发送（或都不接收）。
编写一个方法来处理消息。

处理常规非系统消息的 onMessage 函数调用 addMessage 函数。它接收的消息被编码为 QAMessage 对象。QAMessage 类及其子类（QATextMessage 和 QABinaryMessage）提供保存 QAnywhere 应用程序所需的与消息相关的所有信息的属性和方法。
```
private void onMessage(QAMessage msg)
      {
         if( addMessage( msg ) ) {
            String info_msg = _resources.GetString( "MessageReceived" );
            MessageBox.Show( this, info_msg, "Test Message",
               MessageBoxButtons.OK, MessageBoxIcon.Information );
         }
      }
```

声明 MessageListener。

_receiveListener = new 
    QAManager.MessageListener( onMessage );

只要 QAnywhere 代理接收到一条消息并将其置于应用程序监听的队列中，就会调用 OnMessage 方法。

消息监听器和通知监听器

消息监听器与在使用推式通知进行消息传递的方案中描述的监听器组件不同。监听器组件接收通知，而消息监听器从队列中接收消息。

在同一文件中检查 startReceiver 方法。

此步骤将消息监听器指派给队列。当您为队列设置一个消息监听器时，QAnywhere Manager 将把到达该队列的消息传递给该监听器。只能为一个给定的队列设置一个监听器。设置一个空监听器将清除该队列的所有监听器。

使用 MessageListener 将以异步方式接收信息。您也可以同步接收信息，也就是说，应用程序显式地去队列中查找消息（可能是响应一个用户操作，如单击 [刷新] 按钮），而不是在消息出现时获得通知。

此方法完成初始化任务：
- 打开并启动 QAManager 对象。
```
_qaManager.Open( 
        AcknowledgementMode.EXPLICIT_ACKNOWLEDGEMENT );
_qaManager.Start();
```
  AcknowledgementMode 枚举常量确定如何向发送者确认消息已接收。EXPLICIT_ACKNOWLEDGEMENT 常量指示直到调用一个 QAManager 确认方法时才确认消息。
- 装载在队列中等待的任何消息。
```
_mainWindow.LoadMessages();
```
- 将一个监听器指派给将来的消息队列。
  
  该监听器在 MessageList_Load 方法中声明。
```
_qaManager.SetMessageListener( 
     Options.GetReceiveQueueName(), 
     _receiveListener );
```
  Options.GetReceiveQueueName() 函数返回 testmessage 字符串，即在 TestMessage [Options] 对话框中设置的 TestMessage 队列。
在同一文件中检查 addMessage 函数。

只要应用程序接收到消息，就会调用此方法。它将获取消息的属性，例如 ReplyToAddress、PreferredName 和发送时间（时间戳），并在 TestMessage 用户界面中显示此信息。以下行用于将进来的消息转换为 QATestMessage 对象并获取消息的 ReplyToAddress：
```
text_msg = ( QATextMessage )msg;
from = text_msg.ReplyToAddress;
```
这里简要分析了在 MessageList 文件中执行的一些主要任务。
从 [Solution Explorer] 中打开 NewMessage 文件。
检查 sendMessage 函数。

此函数获取在 [New Message] 对话框中输入的信息并构造一个 QATextMessage 对象。然后，QAManager 将该消息置于要发送的队列中。

下面的行用于创建一个 QATextMessage 对象并设置它的 ReplyToAddress 属性：
```
qa_manager = MessageList.GetQAManager();
msg = qa_manager.CreateTextMessage();
msg.ReplyToAddress = Options.GetReceiveQueueName();
```
下面的行用于将消息置于要发送的队列中。变量 to 为目标地址，将作为函数的参数提供。
```
to = BuildQueue( to );
qa_manager.PutMessage( to, msg );
```

进一步阅读

有关详细信息，请参见：

QAnywhere C++ API 参考
命名空间 iAnywhere.QAnywhere.Client
编写 QAnywhere 客户端应用程序
安装到 SQL Anywhere Studio 目录的 Samples\QAnywhere 子目录中的 TestMessage 示例