MAPI Rules
.gif "A checkmark indicates that the information in this topic is relevant for this platform, and that any API listed is also supported on this platform.")
.gif "A hyphen indicates that the information in this topic is not relevant for this platform, or that the platform does not support the API that is listed.")
8/28/2008
This code sample is named MapiRule. It demonstrates how to implement a Message Rule Client, which is a COM object that can process incoming MAPI messages.
Feature Area
Relevant APIs
- Messaging API (MAPI) API
- IMailRuleClient interface
- IMailRuleClient::ProcessMessage method
- IMailRuleClient::Initialize method
- IMsgStore interface
- IMsgStore::OpenEntry method
- IMessage interface
Usage
To run the code sample
Navigate to the solution file (*.sln), and double-click it. By default, the solution files are copied to the following folders:
C:\Program Files\Windows Mobile 6 SDK\Samples\Common\CPP\Win32\MapiRuleMicrosoft Visual Studio 2005 launches and loads the solution.
Build the solution (Ctrl+Shift+B).
Deploy the solution (F5).
If you have not installed the SamplePrivDeveloper certificate, you will need to so that your Dll and CAB projects are signed correctly.
To install the certificate from the windows desktop
Click Start > Run.
Type the path-name to SamplePrivDeveloper.pfx certificate, and click OK. By default, this is located in the following folder:
C:\Program Files\Windows Mobile 6 SDK\Tools\Security\SDK Development CertificatesDouble-click the SamplePrivDeveloper.pfx certificate icon. The Certificate Import Wizard appears.
Click Next. The certificate path-name is filled-in.
Click Next.
Click Next (you do not need a password).
Click Next. Accept the default options; automatically select the certificate store based on certificate type.
9. Click Finish.
See Mobile device Security Model for further details on how to install the SDK certificates onto the mobile device, and how to use the privileged SDK certificate to sign this application.
Using the application
- After installing the Message Rule Client sample, you can run it by sending yourself a test SMS message. Send an SMS message to the mobile device (use 425-001-0001) with the sample Rule Client installed containing the string "zzz" anywhere in the message. Instead of the standard popup dialog that appears, you will see a standard message box with the address as the caption and the message itself as the body. You might have to close the Inbox to see this message box, as it can appear underneath. Note that the message does not appear in the Inbox at all. This is because it was handled and discarded by the Message Rule Client.
- Send the mobile device another SMS message without "zzz". This will be handled normally, with the standard incoming SMS popup dialog showing the message, and the message appearing in the Inbox.
- To disable the Message Rule Client, remove both registry keys, and reboot the mobile device.
Remarks
It is assumed that the mobile device is capable of sending and receiving SMS messages.
If you have not installed the SamplePrivDeveloper certificate, you will need to so that your dll and CAB projects are signed correctly.
Of particular relevance is the implementation of IMailRuleClient and its IMailRuleClient::ProcessMessage method. This method is called by the Messaging Subsystem when a message matching the Message Rule Client's transport (SMS, ActiveSync, POP3) arrives. From within ProcessMessage, you can reroute messages, delete messages, parse messages, and send custom data to other applications.
Currently, only SMS is supported as a transport for Message Rule Clients.
IMailRuleClient::Initialize must also be implemented to set message store access privileges.
A Message Rule Client is a COM object (generally packaged as a DLL) that implements the IMailRuleClient interface. To work properly, it must be registered in two places:
Standard COM registration
HKEY_CLASSES_ROOT\CLSID\<clsid>
MAPI Inbox
HKEY_LOCAL_MACHINE\Software\Microsoft\Inbox\Svc\SMS\Rules\<clsid>where
<clsid>represents the COM object's class ID GUID.
This code sample uses MAPI message property methods to look for the string "zzz" in incoming SMS messages. If found, it displays the message and sender address in a custom message box instead of the usual incoming SMS dialog box. It deletes the message from the message store, preventing it from showing up in the Inbox.
Messages that do not contain "zzz" will be processed normally.
Development Environments
SDK: Windows Mobile 6 Professional SDK and Windows Mobile 6 Standard SDK
Development Environment: Visual Studio 2005.
ActiveSync: Version 4.5.