Windows Mobile MAPI 入门教程

Windows Mobile MAPI 入门教程

Windows Mobile MAPI 入门教程 　　名词翻译对比： 　　Messaging 消息 　　Inbox 收件箱 　　message stores 消息仓库 　　message transport 消息传输模块 　　一 概述 　　MAPI是一个基于COM的库，提供了客户端应用程序操作“消息“(信息)的编程方法。消息(之前命名为“收件箱“)、消息仓库及它们包含的消息项。 　　你使用MAPI能够创建一个新的完整的“消息“客户端程序，创建一个“消息”的发送，创建一个自定义窗体的“消息”应用程序，执行一条客户端“邮件规则”到可编程的处理收到的消息，执行一个advise-sink 对象用来操作通知消息，可编程方式的管理容器对象类似地址簿、通讯分组列表、目录的高级操作。 　　注意： 在Windows Mobile 2002发布之前，对消息系统的编程方法都是通过MsgStore APIs(查看msgstore.h和msgstore.lib)实现的。尽管以后的Windows Mobile版本提供了有限的兼容性，但还是推荐在您的代码中使用MAPI。 　　关于消息子系统的更多背景信息，和拓展的消息应用，可查看下面几个部分： 　　1) 消息传输模块 　　2) 消息格式 　　3) 自定义的消息客户端规则 　　4) 消息仓库 　　1 消息传输 　　消息传输是一个网络协议，简化了消息从一个消息客户端到消息本地服务器的传送过程。 　　MAPI 支持通过提供的功能使用消息传送，并允许他们直接和消息仓库通信。 　　消息应用程序使用IMailSyncHandler接口的方法和消息传送模块通信。 　　消息传送模块使用IMailSyncCallBack接口的方法和消息应用程序通信。 　　运行Windows Mobile软件的Mobile设备，使用微软的ActiveSync做为mobile设备和桌面服务端电脑做发送E-Mail、Microsoft Outlook PIM项目的传送工作，除了ActiveSync外，Windows Mobile为基础的设备支持Post Office Protocol3 (POP3)和Internet Message Access protocol 4 (IMAP4)以无线方式在mobile设备和互联网e-mail服务器之间传送e-mail-based消息项。Windows Mobile构建的设备也支持短消息服务(SMS),实现在mobile设备和一个移动操作短信息服务(SMS)服务器之间发送和接受蜂窝电话的文本消息项。 　　与Pocket2000密切相关的40创建一个自定义的消息传送方式不同于Windows CE MsgStore APIs。在Windows  Mobile2002及以后版本中已经简化为流程化的IMailSyncHandler接口。 　　注意： IMailSyncHandler 在Pocket PC 2000下并没有提供向后兼容。 　　一个自定义的消息传送模块，是一个包含传输协议的DLL，它输出OneStopFactory功能并支持IMailSyncHand接口。 　　要成为动态的，自定义消息传送模块必需注册到Windows CE。入口指定为新的消息传送接口的名称，名称被包含在其名称下的DLL中，在如下的注册表键里：HKEY_LOCAL_MACHINESoftwareMicrosoftInboxTransportsTransportName. 　　注意：要响应注册表的更改，消息应用程序必需在更新注册表后重启。 　　自定义的消息传送模块通常和自定义窗体一起被用在提供增强的EMS和MMS(彩信)上。 　　当一个消息通过自定义消息发送模块发送时，将会触发以下事件： 　　消息应用程序在Windows CE注册表中搜索消息传输模块的入口。 　　消息应用程序动态载入消息传送模块的DLL。 　　消息应用程序调用DLL中的OneStopFactory 函数，也就是DLL的入口点。 　　DLL返回它的IMailSyncHandler接口，它提供关于消息应用程序和消息传输模块的连接。 　　消息应用程序调用IMailSyncHandler::Initialize 初始化消息传输模块。 　　消息应用程序使用IMailSyncHandler接口的方法来处理消息、连接或者断开网络，并通过调用IMailSyncHandler::ShutDown方法关闭一个传输的回话。 　　2 Messaging Forms 消息格式 　　你能够通过创建自定义的消息格式来更改消息应用程序的行为(或者其它的消息应用客户端程序)，他们是自定义的读取和合成格式，能够使用新的或者已经存在的传输模块。他们提供的行为表现可能不同，像添加如多媒体消息服务(MMS)这样新的消息类型，又如一种支持播放游戏类似ticktacktoe。 　　一个自定义的消息格式是一个包含自定义读取和合成的格式的DLL，输出接口是FormFactoryEx函数，支持IFormProviderEx和IMessageFormEx接口。 　　要实现动态的，格式必需被注册两次。 　　第一次注册入口作为一个消息类型，在下面的注册键： 　　HKEY_CURRENT_USERSoftwareMicrosoftInboxMsgTypesMessageClass 　　第二个入口指定可使用的消息传输：HKEY_LOCAL_MACHINESoftwareMicrosoftInboxSvcTransportTypeMsgClasses 　　注意：要响应注册表的更改，消息应用程序必需在更新注册表后重启。 当一个消息应用程序显示或者创建一条消息，它首先搜索匹配消息的消息类型的DLL。当消息应用程序找到一个合适的DLL，它就载入并调用消息类型的FormFactoryEx函数。DLL以返回IFormProviderEx接口做响应。 　　消息应用程序(主程序)使用IMessageFormEx接口和自定义消息格式通信，它能使用IMessageFormHostEx接口和消息应用程序通信。 　　当处理一个自定义的消息格式的消息，消息应用程序使用下表描述的方法： 　　功能方法 　　创建格式自定义读取和合成格式在消息应用程序调用IFormProviderEx::CreateComposeForm或者 IFormProviderEx::CreateReadForm被创建。这将创建它自己的格式作为主格式的子格式。同时返回子格式(phwndBody 参数)和IMessageFormEx接口指针。 　　消息应用程序使用phwndBody参数来传递windows消息，这个消息并不处理自定义的消息格式，并且它使用IMessageFormEx接口与自定义格式通信。) 　　当一个消息应用程序调用CreateComposeForm和CreateReadForm方法，它传递一个指针给IMessageFormHostEx接口，这个接口允许格式与消息应用程序通信。 　　显示格式菜单When the form is initially created, the Messaging application calls IMessageFormEx::GetMenuCapabilities to provide a way for the form to specify which optional menu commands it can process and to allow enabling or disabling of the menu items. 　　当一个格式初始化创建，消息应用程序调用IMessageFormEx::GetMenuCapabilities提供一种方法来实现为一个格式指定一个能处理的选项菜单，允许其使能和禁用菜单选项。 　　命令在格式菜单被禁用时(显示为灰色)不做处理，GetMenuCapabilities接着被调用，这就允许动态的使能或者禁用菜单命令。 　　运行格式对于格式处理的消息条目而言，当一个菜单命令被选择时消息应用程序调用IMessageFormEx::DoAction。 　　当窗体与消息应用程序通信时，它使用IMessageFormHostEx接口(消息应用程序使其有效，并创建自定义的读取和合成格式)。 　　关闭格式窗体能够在任何point上关闭其自身，并触发以下事件：发送消息，删除消息，单击消息格式的关闭按钮，单击消息格式上的OK按钮。 　　当消息应用程序调用IMessageFormEx::CloseForm，窗体首先调用IMessageFormHostEx::DoAction使消息应用程序不是关闭就是删除消息，然后格式调用IMessageFormHostEx::FormClosing。 调用了FormClosing之后，格式发送一个WM_CLOSE消息给父格式(which it received from the Messaging application on creation)，这样就清楚了窗体句柄并不再使用。 　　4 Message Stores 消息仓库 　　消息仓库就是一个在基于Windows Mobile构建的设备上存放消息的本地档案文件。一个消息仓库对应一个消息账号，每个消息账号都联系着消息传输模块。举例来说，你可能使用Pocket PC服务于3个POP3邮件账号。在这种情况下，你可能需要4个消息仓库：一个用来存放通过ActiveSync传输的Outlook E-Mail，两个通过POP3传输的Outlook E-Mail，和一个通过短信息(SMS)传输的文字消息。 　　Mobile设备的Windows Mobile2003 第二个版本及以后的软件，使用一个消息仓库，称之为Outlook E-Mail，带有电话功能的设备使用另一个消息仓库，用来存放短消息(SMS)文字消息，称之为文本消息。在Windows Mobile 2003之前，这些消息仓库被分别称为ActiveSync和短消息(SMS)。 　　消息仓库分配了folder来包含和管理其子集合，也就是消息作为条目，到达的消息被存放进指定的接受folder中，在Windows Mobile 消息应用程序中，它被称为收件箱。 　　消息客户端应用程序使用IMsgStore接口和消息仓库通信，通过这个接口，你能够做以下的事情： 　　打开folders和消息，并获得他们的指针，以便进行更多的处理(folder的IMAPIFolder接口和消息的IMessage接口)。 　　得到，设置，删除folder和消息的属性。 　　注册接受指定事件的通知，一般是更改了消息仓库内容的事件。 　　在你能够操作一个消息仓库之前，你必需初始化MAPI子系统，并且开始一个MAPI会话(MAPI Session)，它返回一个IMAPISession接口对象的参考，这个接口让你能够操作消息仓库的表，消息仓库，消息目录(译者注：Message folders)和消息。 　　开始MAPI会话 　　1. (译者注：首先初始化MAPI：)增加MAPI子系统参考计数器，并且使用全局MAPI MAPIInitialize函数初始化MAPI DLL的全局数据，如下所示： 　　hr = MAPIInitialize(NULL); 　　2. 使用全局MAPI MAPILogonEx的函数开始一个MAPI会话，并且得到一个ICEMAPISession接口对象的参考： 　　hr = MAPILogonEx(0, NULL, NULL, 0, (LPMAPISESSION *)&pSession); 　　示例代码 　　下面的示例代码演示了如何开始一个MAPI会话。 注意： 使用下面代码前请首先阅读，代码没有包含安全检查和错误处理. 这个示例代码在修改包含以上代码前，不要使用于发布版本。 　　HRESULT hr; 　　ICEMAPISession * pSession = NULL; 　　hr = MAPIInitialize(NULL); 　　if (hr != S_OK) { 　　// MAPIInitialize初始化失败 　　MessageBox(NULL, 　　_T("MAPIInitialize failed."), 　　_T("Warning"), 　　MB_OK); 　　exit(0); // 使用指定的错误处理代码替换 　　} 　　hr = MAPILogonEx(0, NULL, NULL, 0, (LPMAPISESSION *)&pSession); 　　if (hr != S_OK) { 　　// MAPILogonEx 执行失败. 　　MessageBox(NULL, 　　_T("MAPILogonEx failed."), 　　_T("Warning"), 　　MB_OK); 　　exit(0); //使用指定的错误处理代码替换 　　}