Creating a New Interpersonal (IPM) Message Class

There are several ways to create a new message class used for person-to-person communication. By using MAPI properties to structure message content, you avoid writing code to parse message text or a binary attachment.

Design Tasks

1. Decide whether yours is an interpersonal messaging (IPM) application or a type of interprocess communication (IPC) application. There is an enormous variety of applications; following is a basic list of types and examples. For more information about IPC applications, see Creating a New Interprocess (IPC) Message Class.
   • Person-to-person. A person initiates the exchange of messages, and another person responds. This includes traditional e-mail as well as more structured exchanges such as document routing or expense approval.
   • Person-to-machine. A person initiates the exchange of messages, and a machine responds. Examples include submitting a database query by e-mail and subscribing to a mailing list.
   • Machine-to-person. A machine initiates the exchange of messages, and a person responds. Examples include news feeds and other types of document distribution, and opinion surveys.
   • Machine-to-machine. A machine initiates the exchange of messages, and another machine responds. Examples include link heartbeat monitoring, directory and database replication.
   • A more complex pattern with both people and machines in the route.
   • A more complex pattern where, instead of being transmitted, the message may be posted directly into a public folder or bulletin board forum supported by a message store for consumption by other readers, an administrator, or a software agent.

   Logically, person-to-person applications, machine-to-person applications, and applications that post to public forums should be designated IPM, while person-to-machine and machine-to-machine applications are IPC message classes. The only real difference is that IPM messages in a message store are visible to messaging clients, while IPC messages usually are not. Anything that requires a person to respond must use an IPM message class. Applications involving a more complex pattern including people and machines often involve a mix of IPM and IPC messages.

2. Choose the message class name, beginning it with IPM. or IPC. according to the preceding guidelines.
3. Choose the application framework for sending and reading your messages. Alternatives include:
   • A form. A form is a MAPI object that is integrated into messaging clients; it can create, display, print, and perform custom commands — called "verbs" in MAPI — on a particular type of message. Forms take maximum advantage of integration with the messaging client. See Forms.
   • A standalone application. This gives you the greatest control over the user interface to your messages but also requires the most work in creating and distributing your application and in making it easy for your users to find.
   • A client extension. This is a compromise. An extension is easier for users to discover than a standalone application and in some respects easier to write than a form, but the integration with the client is less complete than with a form. See Advantages of Extending Microsoft Exchange.
4. Decide whether to use Simple MAPI, CMC, MAPI, or the Active Messaging Library. See Selecting a Client Interface. In addition to the considerations listed there, you must think about whether that interface fits well into the application framework you have chosen. For instance, both forms and extensions must use or furnish several COM interfaces which are not easily supported by Visual Basic programs.
5. Define properties specific to your message class. Decide whether to use named properties or properties from the 0x6800-0x7fff range. See About Property Identifiers and Named Properties. Properties that contain e-mail addresses should be stored in a special way to provide for translation when changing messaging domains. See Sending Across Messaging Domains.

   Consider the need for interoperability with messaging clients that can be only message text. It may be advisable to duplicate some or all of your message's properties in the message text if you expect the message to be read by people using such messaging clients.

6. Define the commands — called "verbs" in MAPI — specific to your message class, and choose which standard verbs to implement. See Form Verbs.
7. Choose a distribution mechanism. For a standalone application, this generally involves making an executable and any necessary auxiliary files available to your users. Additional steps are necessary if you are implementing a form, including which library to register it in. See Form Libraries. Additional steps are also necessary if you are implementing a client extension. See Registering Extensions.

Implementation Tasks

All IPM message classes should honor common IPM client options for disposition of sent messages and other features.

    To implement a form

1. Choose a class identifier (CLSID) for the form. You can use the tool UUIDGEN.EXE for this purpose. See Using UUIDGEN.EXE.
2. Choose a message class name for the form. See Message Classes.
3. Create an .EXE file that acts as a COM server for the form, registered with the form's class identifier. It must implement the OLE interface IClassFactory, and the IMAPIForm and IPersistMessage interfaces; it may optionally implement the IMAPIFormAdviseSink and IMAPIFormFactory interfaces. See Implementing the IClassFactory Interface for Form Servers. The class factory's CreateInstance method must return an IMAPIForm interface; that form object's QueryInterface method must be capable of returning an IPersistMessage interface.
4. Create a .CFG file listing the form's class identifier, message class, properties, verbs, extensions, and so forth. See File Format of Form Configuration Files.
5. For each user of your form, make the .EXE file and any auxiliary files available, and register the .CFG file in a form library using PDKIN.EXE, INSTFORM.EXE, or your own code. See Form Libraries. If using the local form library, you must also register your .EXE file as a COM server for the form's class identifier, using REGEDIT.EXE.

For more information, see Developing MAPI Form Servers.

    To add an extension to the messaging client

1. Decide which client contexts your extension should be available in, and whether your extension requires a specific message service to be available. See How Extensions Work.
2. Create a DLL with an entry point that returns an extension object — an object that implements the IExchExt interface and any other required interfaces. Implement the IExchExt interface and any other required interfaces.
3. For each user of your extension, make the DLL and any auxiliary files available, and register your extension in the system registry or WIN.INI file. See Registering Extensions.

For more information, see Command Extensions.

    To create a standalone application using MAPI

1. Verify that MAPI is installed before proceeding if your installation process does not guarantee that MAPI is installed. See Installing MAPI.
2. Load and initialize the MAPI DLL. See Initializing MAPI and Initializing OLE for Use with MAPI.
3. Log on to MAPI using the messaging client's session if available. See Logging On.
4. Open the user's default message store, Inbox and Outbox folders. See Opening a Message Store and Opening a Folder.
5. Create and send a message using the following steps:
   1. Create a message in the Outbox folder using the IMAPIFolder::CreateMessage method.
   2. Add recipients to the message's recipient table. See Recipients.
   3. Add the document to the message as an attachment. See Attachments.
   4. Optionally, add text to the message. See the PR_BODY property.
   5. Send the message. See Sending Messages with MAPI.
6. Scan the Inbox for new messages using the following steps:
   1. Optionally, force any incoming messages to be downloaded. See IMAPIStatus::FlushQueues.
   2. Open the Inbox folder's contents table.
   3. Restrict the contents table to messages of interest to your application.
   4. Optionally, register for new mail notifications on the message store object to be advised of further incoming messages.
7. For each user of your application, make the .EXE file and any auxiliary files available.

About Sample Source Code

See the following topics:

Sample Custom Sendable Form

Sample Command Extension

Sample Routing Client

Sample Form

Sample Timecard Application