CMapi v1.06

CMapi v1.06

Welcome to CMapi, 2 simple classes to encapsulate sending mail using Simple MAPI.

Simple MAPI is a set of functions exported by MAPI32.dll which allows you to send and receive mail in a transport independent way. It is an optional part of all Win32 operating systems since Windows 95 (excluding WinCE). MAPI is intended more for the corporate environment when compared with the Internet mail standard SMTP e.g. products such as MS Exchange Server use MAPI extensively. Transport providers are available for a number of messaging transports including Exchange Server, SMTP, Fax, cc:Mail Compuserve etc. To be able to specify different transports, MAPI provides the concept of profiles which are setup using the Mail control panel applet.

Contacting the Author

Features

Simple and clean C++ interface.
All the code is UNICODE compliant and build configurations are provided for this. Even though Simple MAPI only exports an ASCII versions of it's functions, the class internally performs the necessary conversions.
The code can be used in a console application or without bringing up any Map dialogs if so desired.
The code gracefully handles the case where MAPI is not installed on client machines. Internally the class loads the DLL and uses GetProcAddress calls.

Usage

To use the class in your code simply include cmapi.cpp in your project and #include cmapi.h in which ever of your modules needs to make calls to the classes.
Your code will need to include MFC either statically or dynamically.
You may want to add mapi.h to your pre compiled header to improve compilation speed. An build message will inform you of this.
To see the class in action, have a look at the code in InitInstance in the module "app.cpp".

History

V1.0 (14th May 1999)

Initial public release.

V1.01 (5 December 1999)

Fixed potential problem where CMapi is used in a console app which was giving an ASSERT
Fixed an assert which can occur if you dismiss the login dialog when doing an interactive MAPI logon

V1.02 (28 March 2000)

Provision of a sample app which implements a mini mail sender.
Added a CMapiMessage::AddMultipleRecipients method similar to my SMTP class.

V1.03 (2 April 2000)

Password field in the configuration dialog now uses ES_PASSWORD edit control style.
Password value used for MAPI logon is now stored in the registry encrypted instead of as plain text.

V1.04 (21 May 2000)

Added an optional parameter to CMapi::SendMessage to allow you to decide whether or not addresses should be resolved.

V1.05 (22 June 2000)

Fixed a bug in CMapiMessage::AddMultipleRecipients where BCC recipients were not being added correctly.

V1.06 (18 July 2000)

Fixed check for MAPI being installed when client apps create an incorrect "MAPI" entry in win.ini or the registry, Thanks to Chris Raethke for spotting this.
A "SharedLogon" method has been provided which tries to acquire a shared MAPI session
SendMessage method has been extended to allow the message to be interactively edited.

2 October 2002

Updated the caption in the configuration dialog in the sample app when asking for configuration settings
Updated the sample app to not ask for configuration if you are trying to send using a shared MAPI session.

API Reference

The API consists of the following 2 classes and their methods and variables

CMapiMessage

CMapiMessage::m_To
CMapiMessage::m_CC
CMapiMessage::m_BCC
CMapiMessage::m_sSubject
CMapiMessage::m_sBody
CMapiMessage::m_Attachments
CMapiMessage::m_AttachmentTitles

CMapiSession

CMapiSession::CMapiSession
CMapiSession::~CMapiSession
CMapiSession::Logon
CMapiSession::SharedLogon
CMapiSession::LoggedOn
CMapiSession::Logoff
CMapiSession::Send
CMapiSession::MapiInstalled
CMapiSession::GetLastError

CMapiMessage::m_To

Remarks

m_To is of type CStringArray and contains the array of recipients which the email is to be mailed to. The name of each recipient can be a friendly name (the friendly name is the name which a recipient with an address book entry is known as e.g. "PJ at Work" could map to using an SMTP MAPI transport to send to pj.naughter@softech-telecom.com) or it can be a specific transport address e.g. SMTP:pjna@naughter.com, FAX:34567 etc.

CMapiMessage::m_CC

Remarks

m_CC is of type CStringArray and contains the array of recipients which the email will be Carbon Copied to. The way addresses are specified is the same as for m_To.

CMapiMessage::m_BCC

Remarks

m_BCC is of type CStringArray and contains the array of recipients which the email will be Blind Carbon Copied to. The way addresses are specified is the same as for m_To.

CMapiMessage::m_sSubject

Remarks

m_sSubject is of type CString and is the subject line of the email.

CMapiMessage::m_sBody

Remarks

m_sBody is of type CString and is the body of the email.

CMapiMessage::m_Attachments

Remarks

m_Attachments is of type CStringArray and is a list of filenames to be included as attachments in the email.

CMapiMessage::m_AttachmentTitles

Remarks

m_AttachmentTitles is of type CStringArray and contains the titles of what each file attachment will be known as to recipients of this message. If you leave this array empty then the title will be the same as the filename. As an example have a look at the code in InitInstance in app.cpp to see how the "autoexec.bat" attachment has a title of "my autoexec.bat".

CMapiSession::CMapiSession

CMapiSession();

Remarks

Standard constructor for the class. This class is the main MAPI support class and contains the functions to actually send the mail message.

CMapiSession::~CMapiSession

CMapiSession();

Remarks

Standard destructor for the class. Internally this logs you out of MAPI if you're logged in and unloads the MAPI dll.

CMapiSession::Logon

BOOL Logon(const CString& sProfileName, const CString& sPassword = CString(), CWnd* pParentWnd = NULL);

Return Value

TRUE if you were successfully logged in to MAPI otherwise FALSE

Parameters

sProfileName MAPI profile name to use to logon.

sPassword sPassword associated with the profile (if any).

pParentWnd The parent window indicating that if a dialog box is displayed, it is modal with respect to.

Remarks

Logons to the MAPI messaging system creating a session with it. If you pass an empty profile name then Logon will try to interactively logon by presenting the normal MAPI logon dialog. Specifying NULL as the parent window as is the default will use the window as returned by AfxGetMainWnd(). Please note that you must be logged on to MAPI prior to sending a message. Internally the code will "ASSERT" to ensure you do not forget to do this.

CMapiSession::SharedLogon

BOOL Logon();

Return Value

TRUE if you were successfully logged in to MAPI otherwise FALSE

Parameters

Remarks

Logons to the MAPI messaging system by using a "shared" MAPI session. i.e. it will try to use an existing mapi session and if there is none, then this function will fail. For further info on "shared" MAPI sessions, please check the MSDN.

CMapiSession::LoggedOn

BOOL LoggedOn() const;

Remarks

Simply accessor which returns TRUE if this instance is logged on to MAPI otherwise FALSE.

CMapiSession::Logoff

BOOL Logon();

Return Value

TRUE if you were successfully logged off from MAPI otherwise FALSE

Remarks

The corollary function to Logon. Internally this function is called in the CMapiSession destructor.

CMapiSession::Send

BOOL Send(CMapiMessage& message, BOOL bResolve = FALSE, BOOL bInteractive = FALSE, CWnd* pParentWnd = NULL);

Return Value

TRUE if the message was successfully sent otherwise FALSE.

Parameters

message Message to be sent

bResolve TRUE if the recipient addresses should be resolved otherwise FALSE.

bInteractive TRUE if you want the message to be editable by the end user prior to the message actually being sent.

pParentWnd If bInteractive is TRUE, then this is the parent window to use. If it is left as NULL, then the window as returned by AfxGetMainWnd() will be used.

Remarks

Sends the message as specified in the "message" parameter, using the MAPI profile currently logged into. In you set bResolve to TRUE, then the recipient's address will be looked up in the profiles address books, prior to sending. This can lead to the following problem: if two people have identical "resolved" names but different e-mail addresses, the CMapi class is unable to send mail to either address because after the address is resolved, the recipient becomes "ambiguous," and MAPISendMail returns the MAPI_E_AMBIGUOUS_RECIPIENT (21) error code. Normally you should accept the default of not to resolve addresses.

CMapiSession::MapiInstalled

BOOL MapiInstalled() const;

Remarks

Simply accessor which returns TRUE if MAPI is installed and has been correctly initialized ready for this instance to use. The actual loading of the MAPI dll is handled internally by the CMapiSession constructor, meaning it is valid this function anytime after you have constructed a CMapiSession instance.

CMapiSession::GetLastError

DWORD GetLastError() const;

Return Value

The last MAPI error generated by this CMapiSession instance.

Remarks

Since the class uses MAPI which has its own way of reporting errors different to the standard Win32 way (GetLastError), this method allows this value to be retrieved. MAPI errors are documented in the MAPI.h file in your VC include directory.

PLANNED ENHANCEMENTS

Package the code up into an OCX, COM Interface or DLL to allow non MFC apps to use the code.
If you have any other suggested improvements, please let me know so that I can incorporate them into the next release.

CONTACTING THE AUTHOR

PJ Naughter
Email: pjna@naughter.com
Web: http://www.naughter.com
2 September 2002