MAPI Forms

MAPI forms are forms created and used with MAPI subsystem. If you use a standalone MAPI client such as Outlook you may benefit from their functionality. They may also be useful in a client-server MAPI environment, for example, in organizations where Microsoft Exchange server is installed.

What Is a MAPI Form?

A MAPI form is a non-trivial object. Perhaps one particular area where MAPI complexity is overwhelming is MAPI forms. Underneath a form is really a COM object (local server), which is launched in a standalone executable when user wants to create a new form message. MAPI dictates rules for its behavior and defines interfaces that it must or may export. I would consider dealing with raw MAPI forms an advanced technique. You need to learn quite a few things before being able to produce something useful. Thus, the complexity of the subject is a strong drawback against MAPI forms. There is a benefit also, and it is promising. Because user interface is defined by you local server COM program, you can display almost anything there. For example, you form may be a chess board, which allows users to play a game of chess. In fact, Microsoft has provided a nice code CHECKERS.FRM sample - which allows messaging users to play a game of checkers. A form is a colorful checkers board where you can move things with a mouse. This would be a good reference material to find out how to implement your own MAPI form.

What to Read about MAPI Forms?

MSDN Library has quite a good description of MAPI forms and related things. In fact, if you plan to proceed with raw MAPI forms development, the Forms and Developing MAPI Form Servers sections in Messaging API Guide in the library are a must. The material looks quite concise and informative. It is the minimum list of things you need to know before starting raw MAPI forms development. These chapters with the addition of CHECKERS.FRM sample perhaps would suffice to start your own forms programming by incremental altering the behavior of the sample.

Another worthwhile reading I could recommend is Ben Goether book "Developing Applications for Microsoft Exchange with C++" (4), where pages 219-458 are devoted to the topic of MAPI forms. This book is especially helpful because it has code samples showing how you could write custom MAPI form servers.

Beware, however, about potential danger to drown in complexity and always proceed with caution.

How MAPI Forms Work?

Before a MAPI form could work, it must be properly installed on the system. The installation requires the following three things:

Availability of the form executable file.
Proper registration of the form CLSID in the system registry so that MAPI subsystem could launch this executable when necessary.
Proper registration of the form with MAPI subsystem. This means that the form should be "installed" in some container. This step really creates a message object in the container associated contents table.

A form has associated message class, which is linked to the form CLSID. A form has also a collection of properties (potentially including some custom defined) that are to be transmitted with the message. When a form is installed on the sender and on the recipient systems, only these properties are usually transmitted. The values of these properties are used to populate user interface controls on the form. The system determines which form to launch by looking at message class of the message. Thus, the concept is really straightforward.

Where MAPI Forms Are Stored?

MAPI forms are stored as messages in MAPI folders. For example, it can be your Outbox or the Personal Forms Library container (your mailbox root folder). PR_ENTRYID properties of all forms installed in a folder will be in its associated contents table through the use of MAPI_ASSOCIATED flag. Having this entry identifier you could open a message as you would do for a normal message and examine its properties. Each folder can have two types of contents: standard and associated. Standard content holds standard items such as messages. Associated content holds associated items such as forms, views, rule templates, reply templates and others. Associated content is usually hidden from users.

A form definition does not actually define user interface for a form. Instead, it defines properties that go with the form. In addition it references a CLSID of the form server - a local executable file that is launched to display a form. Also, these executables are saved as attachments to the form definition message. For example, after I have installed IPM.Checkers form on my system I have noticed the form definition message to have 3 attachments, one of which was the form server executable: wcheck32.exe.

An evolution of a form has a few distinguished states:

A form is not installed on the system.
A form is installed in a specific MAPI folder. What this means is that there exists a form definition message in this folder. It may be accessible though the folder's associated contents table. The form server is stored as an attachment to this message. However, the CLSID is not referenced in the system registry, and it is impossible to display a form without an additional step of installing it there.
A form exists in a folder and its CLSID is properly registered with the system. Thus, the system can actually launch a form server when necessary. Usually this step is achieved automatically when you try to launch the form (already installed in a folder) for the very first time. Outlook, for example, displays a progress bar indicator titled "Installing the form on your machine". If you examine the system registry after this step you will see an entry there for the form CLSID.

Form definitions can also be stored in a local file, usually in windows %SystemRoot%\Forms\Frmcache.dat. The discussion of this is out of scope of this book. You can easily examine the file, however, to get an idea about its contents.

Thus, any form is represented by 2 objects: a COM object, which should be properly installed on the system, and a collection of MAPI properties that go with the form. When a form message is sent from one system to another, only these properties are sent. This assumes that the form is properly installed on the other side. If it is not, the user will not be able to see the form's UI. For Outlook generated forms there exists a means of sending the form definition (UI and code) with the message. If such message is received by an Outlook application, it may actually extract UI and code from the message and properly display a form. More on this later.

[ Contents | Home ]