Share via


MAPI Rules

Windows Mobile SupportedWindows Embedded CE Not Supported

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

Usage

To run the code sample

  1. 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\MapiRule

    Microsoft Visual Studio 2005 launches and loads the solution.

  2. Build the solution (Ctrl+Shift+B).

  3. 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

  1. Click Start > Run.

  2. 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 Certificates
    
  3. Double-click the SamplePrivDeveloper.pfx certificate icon. The Certificate Import Wizard appears.

  4. Click Next. The certificate path-name is filled-in.

  5. Click Next.

  6. Click Next (you do not need a password).

  7. Click Next. Accept the default options; automatically select the certificate store based on certificate type.

  8. 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.

See Also

Concepts

Code Samples for Windows Mobile