MAPI Support in MFC

Home |  Overview |  How Do I |  Sample

MFC supplies support for a subset of the Microsoft Messaging Application Program Interface (MAPI) in class CDocument. Specifically, CDocument has member functions that determine whether mail support is present on the end-user’s machine and, if so, enable a Send Mail command whose standard command ID is ID_FILE_SEND_MAIL. The MFC handler function for this command allows the user to send a document via electronic mail.

Tip   Although MFC does not encapsulate the entire MAPI function set, you can still call MAPI functions directly, just as you can call Win32 API functions directly from MFC programs.

Providing the Send Mail command in your application is very easy. MFC provides the implementation to package a document (that is, a CDocument-derived object) as an attachment and send it as mail. This attachment is equivalent to a File Save command that saves (serializes) the document’s contents to the mail message. This implementation calls upon the mail client on the user’s machine to give the user the opportunity to address the mail and to add subject and message text to the mail message. Users see their familiar mail application’s user interface. This functionality is supplied by two CDocument member functions: OnFileSendMail and OnUpdateFileSendMail.

MAPI needs to read the file to send the attachment. If the application keeps its data file open during an OnFileSendMail function call, the file needs to be opened with a share mode that allows multiple processes to access the file.

Note   An overriding version of OnFileSendMail for class COleDocument correctly handles compound documents.

To implement a Send Mail command with MFC

  1. Use the Visual C++ menu editor to add a menu item whose command ID is ID_FILE_SEND_MAIL.

    This command ID is provided by the framework in AFXRES.H. The command can be added to any menu, but it is usually added to the File menu.

  2. Manually add the following to your document’s message map: 
    ON_COMMAND(ID_FILE_SEND_MAIL, OnFileSendMail)
ON_UPDATE_COMMAND_UI(ID_FILE_SEND_MAIL, OnUpdateFileSendMail)

    Place the new lines outside of the special “//{{AFX” comments.

    Note   This message map works for a document derived from either CDocument or ColeDocument — it picks up the correct base class in either case, even though the message map is in your derived document class.

  3. Build your application.

If mail support is available, MFC enables your menu item with OnUpdateFileSendMail and subsequently processes the command with OnFileSendMail. If mail support is not available, MFC automatically removes your menu item so the user will not see it.

Tip   Rather than manually adding message map entries as described above, you can use ClassWizard to add them, although the method is indirect. To use ClassWizard, add an OnFileSendMail command handler and an OnUpdateFileSendMail command update handler as you normally would. This gives you two empty handlers that effectively override the OnFileSendMail and OnUpdateFileSendMail handlers in CDocument, which contain the MAPI implementations. To use those implementations, call the base-class versions of OnFileSendMail and OnUpdateFileSendMail in your new handlers. While this approach works,  manually adding the message map entries, as described in the procedure above, is quicker and more direct.

Note also that the MFC AppWizard lets you select an option that adds MAPI support directly to your new MFC application. If you use that option, you can skip steps 1 and 2 above.

For related information, see MAPI Topics.

What do you want to do?