Installing a MAPI Form

MAPI provides interfaces for installing and removing forms in MAPI containers. These interfaces are IMAPIFormMgr and IMAPIFormContainer. There are also a few other interfaces (all beginning with IMAPIForm) that may be used when dealing with forms. Perhaps the best way to illustrate installation of a form is by example. I have written the code below to do exactly that. It installs the checkers form (from CHECKERS.FRM sample) into the Personal Forms Library container. Trying to install this form would be a useful generic exercise, because it will give you an idea of how a custom made form may be different from traditional ones.

A form is installed into a container by first opening this container and then using its InstallForm method. Before you can open a MAPI form container, you need to have MAPI form manager. In fact, the container is opened through IMAPIFormMgr::OpenFormContainer method. To install the form you need to specify the name and location of a configuration file (with .CFG extension) that describes your form. You may read about the format of configuration files in the "File Format of Form Configuration Files" section in MSDN Library.

Well, here is the code (Forms/InstallForm):

#include <afxwin.h>
#include <edk.h>

int main()
{
    /*
     * Algorithm:
     * 1. Open Personal Forms Library container.
     * 2. Install a form there.
     */

HRESULT hr;
LPMAPISESSION pSession = NULL;

    // Initialize MAPI
    hr = MAPIInitialize(NULL);
    if (FAILED(hr)) throw -1;

    // Obtain MAPI session
    hr = MAPILogonEx(0,    // Handle to parent window
      "MS Exchange Settings", // Profile name
      NULL,   // Password
      MAPI_NEW_SESSION |
      MAPI_EXTENDED |
      MAPI_LOGON_UI, // Logon flags
      &pSession); // Resulting MAPI session
    if (FAILED(hr)) throw -1;

    // Open MAPI Form manager
    LPMAPIFORMMGR pFormMgr = NULL;
    hr = MAPIOpenFormMgr(pSession, &pFormMgr);
    if (FAILED(hr)) throw -1;

    // Open the "Personal Forms Library" container
    LPMAPIFORMCONTAINER pPersonalFormsLibrary = NULL;
    hr = pFormMgr->OpenFormContainer(HFRMREG_PERSONAL,
          NULL,
          &pPersonalFormsLibrary);
    if (FAILED(hr)) throw -1;

    // Install the form
    hr = pPersonalFormsLibrary->InstallForm(0, MAPI_DIALOG, "E:\\Temp\\ChkrForm.Cfg");
    if (FAILED(hr)) throw -1;

    // Cleanup
    if (pPersonalFormsLibrary)
        pPersonalFormsLibrary->Release();
    if (pFormMgr)
        pFormMgr->Release();
    if (pSession)
        pSession->Release();

    ::MAPIUninitialize();
    return 0;
}

As you can see, the algorithm is straightforward. You need to make sure that wCheck.Ico, wCheck.Ico and wCheck32.Exe files are located in the same place where the ChkrForm.Cfg file is. Otherwise the installation will fail. You may get all these files from the INSTFORM sample in your build environment samples under dmbsg\Exchange. Install this form and you can play a game of checkers with a remote opponent!

The CHECKERS.FRM sample as delivered from Microsoft does not support Windows NT 4.0 on Intel platform. This means that trying to compile CHECKERS.FRM (results in WCHECK.EXE) and installing it on such system will likely to succeed. However, displaying a form will fail because the platform is not supported. Perhaps you can modify the sample and make it working on Intel based NT. Also, you may notice that the configuration files in Mapi\CHECKERS.FRM and Exchange\INSTFORM are different.

If you wanted to install a form in a different container, say in Outbox, this is also possible. The code is a little bit bigger because of extra overhead in obtaining a pointer to an opened Outbox. But the strategy remains the same: opening a MAPI form container and then installing a form in it. I am providing the Forms/InstallFormInOutbox sample, which demonstrates how to install a form in your Outbox.

[ Contents | Home ]