CCMC v1.04

Welcome to CCMC, 2 simple classes to encapsulate sending mail using the Common Messaging Calls (CMC) interface.

CMC is a platform independent API which provides messaging capabilities similar to simple MAPI on Windows. Other obvious API's of use to the MFC programmer are SMTP and Simple MAPI. The author has provided freeware classes for these at http://www.naughter.com/smtp.html and http://www.naughter.com/cmapi.html respectively. This class has been exclusively tested with the MS reference implementation of CMC but should work ok with any other CMC implementation on Windows.

Features

• Simple and clean C++ interface.
• All the code is UNICODE compliant and build configurations are provided for this. Even though CMC only exports an ASCII versions of it's functions, the class internally performs the necessary conversions. Please note that since the API is ASCII based, you will still have problems if you use UNICODE characters which cannot be represented in the ASCII code page.
• The code can be used in a console application or without bringing up any UI dialogs if so desired.
• The code gracefully handles the case where CMC is not installed on client machines. Internally the class loads the DLL and uses GetProcAddress calls.

Copyright

• You are allowed to include the source code in any product (commercial, shareware, freeware or otherwise) when your product is released in binary form.
• You are allowed to modify the source code in any way you want except you cannot modify the copyright details at the top of each module.
• If you want to distribute source code with your application, then you are only allowed to distribute versions released by the author. This is to maintain a single distribution point for the source code.

Usage

• To use the class in your code simply include CCmc.cpp in your project and #include CCmc.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 xcmc.h to your pre compiled header to improve compilation speed. An build message will inform you of this.

History

V1.0 (25th November 1999)

• Initial public release.

V1.01 (28 March 2000)

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

V1.02 (2 April 2000)

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

V1.03 (22 December 2006)

• Updated copyright details
• Made function pointer typedefs part of the CCMCSession class
• Updated the code to clean compile on VC 2005
• CCMCMessage::AddMultipleRecipients method now has a return value of void
• Optimized CCMCSession constructor code
• Addition of a CCMCMessage::AddMultipleAttachements method
• Code now uses newer C++ style casts instead of C style casts.
• Reviewed all TRACE statements for correctness
• Fixed problems when the code is compiled for UNICODE. The issue was that the Send method was using the various T2A macros which allocates a stack based string. This was causing issues because the recipients and attachments array for the CMC message was being allocated in loops which was using scoping. This scoping was causing the stack based strings to be deallocated before the "cmc_send" method was called. This issue has now been fixed by the introduction of new generic heap based macros in PJNConv.h which allocates the converted string using the C++ new operator. To ensure orderly cleanup of this heap memory, the CMC_message structure is now allocated using a hidden C++ class "CCMC_messageCleanup" which cleans up this memory automatically in its destructor.
• General review of the code to bring it up to date with the author's simple MAPI class.
• Addition of a CCMC_EXT_CLASS preprocessor macro to allow the classes to be more easily added to an extension dll

V1.04 (1 January 2007)

• Updated copyright details.
• Fixed incorrect usage of preprocessor macro in CCMCMessage::AddMultipleRecipients method

API Reference

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

CCMCMessage

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

CCMCSession

CCMCSession::CCMCSession
CCMCSession::~CCMCSession
CCMCSession::Logon
CCMCSession::LoggedOn
CCMCSession::Logoff
CCMCSession::Send
CCMCSession::CMCInstalled
CCMCSession::GetLastError

CCMCMessage::m_To

Remarks

m_To is of type CStringArray and contains the array of recipients which the email is to be mailed to.

CCMCMessage::m_CC

Remarks

m_CC is of type CStringArray and contains the array of recipients which the email will be Carbon Copied to.

CCMCMessage::m_BCC

Remarks

m_BCC is of type CStringArray and contains the array of recipients which the email will be Blind Carbon Copied to.

CCMCMessage::m_sSubject

Remarks

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

CCMCMessage::m_sBody

Remarks

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

CCMCMessage::m_Attachments

Remarks

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

CCMCMessage::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.

CCMCSession::CCMCSession

CCMCSession();

Remarks

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

CCMCSession::~CCMCSession

~CCMCSession();

Remarks

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

CCMCSession::Logon

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

Return Value

TRUE if you were successfully logged in to CMC otherwise FALSE

Parameters

sProfileName CMC profile name to use to logon.

sPassword Password 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 CMC 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 CMC 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 CMC prior to sending a message. Internally the code will "ASSERT" to ensure you do not forget to do this.

CCMCSession::LoggedOn

BOOL LoggedOn() const;

Remarks

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

CCMCSession::Logoff

BOOL Logon();

Return Value

TRUE if you were successfully logged off from CMC otherwise FALSE

Remarks

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

CCMCSession::Send

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

Return Value

TRUE if the message was successfully sent otherwise FALSE.

Parameters

message Message to be sent

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 CMC profile currently logged into.

CCMCSession::CMCInstalled

BOOL CMCInstalled() const;

Remarks

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

CCMCSession::GetLastError

CMC_return_code GetLastError() const;

Return Value

The last CMC error generated by this CCMCSession instance.

Remarks

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

Planned Enhancements

• 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
1 January 2007