Edit

MAPI Support in MFC

  • Article

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 through 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_SENDMAIL, &CMyDoc::OnFileSendMail)
ON_UPDATE_COMMAND_UI(ID_FILE_SENDMAIL, &CMyDoc::OnUpdateFileSendMail)

    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 previously described, you can use the class Class Wizard to map messages to functions. For more information, see Mapping Messages to Functions.

For related information, see the MAPI overview.

For more information about the CDocument member functions that enable MAPI, see:

See also

MAPI