CSMTPConnection v1.11

Welcome to CSMTPConnection, a freeware MFC class to support the SMTP protocol. SMTP for those not familiar with all the internet protocols is the protocol used to send internet email.

For detailed information about the Simple Mail Transfer Protocol you should read RFC 821, You can download this from ftp://ds.internic.net/rfc/rfc821.txt. If this server is unavailable, try ftp://venera.isi.edu/in_notes/

Another document that these classes refer to is RFC 2045 which defines how MIME attachments are to be handled in a standard SMTP message. You can download this from ftp://ds.internic.net/rfc/rfc2045.txt. Again, If this server is unavailable, try ftp://venera.isi.edu/in_notes/

Features

• Simple and clean C++ interface.
• The interface provided is synchronous which provides an easier programming model than using asynchronous sockets.
• The code does not rely on the MFC socket classes. These classes have a number of shortcomings, one of which causes problems when they are used in NT services.
• The code can be used in a console application without any problems (Again this is not the case for the MFC socket classes).
• A configurable timeout for the connection can be set through the class API.
• The classes are fully Unicode compliant and include Unicode built options in the workspace file.
• As of v1.1, the classes now fully supports file attachments.

Usage

• To use the class in your code simply include smtp.cpp in your project and #include smtp.h in which ever of your modules needs to make calls to the class.
• Your code will need to include MFC either statically or dynamically.
• You will need to have a functioning winsock stack installed and correctly initialised prior to calling any functions in CSMTPConnection. Depending on your application, this will involve calling either WSAStartup or AfxSocketInit at startup of your application.
• You will also need to have afxtempl.h ,winsock.h or afxsock.h and afxpriv.h in your precompiled header. The code will work just aswell in a GUI or console app. The code should also work in a multithreaded application, although it has not be explicitly tested in this scenario.
• To see the class in action, have a look at the code in InitInstance in the module "main.cpp".  For example to send a message to the author about this class, the code would look something like this (ignoring error handling):

        CSMTPConnection smtp;
        smtp.Connect("mail.someisp.com");
        CSMTPMessage m;
        m.AddRecipient(CSMTPAddress("pjn@indigo.ie"));
        m.m_From = CSMTPAddress("adeveloper@someisp.com");
        m.m_sSubject = "A Fellow developer!";
        m.m_sBody = "if you can read this then the CSMTPConnection code is working";
        smtp.SendMessage(m);

        To send your autoexec.bat as a file attachment to me you would use the following code:

        CSMTPConnection smtp;
        smtp.Connect("mail.yourisp.com");
        CSMTPMessage m;
        m.AddRecipient(CSMTPAddress("pjn@indigo.ie"));
        m.m_From = CSMTPAddress("you@someisp.com");
        m.m_sSubject = "Here's my autoexec.bat file!";
        CSMTPAttachment a;
        a.Attach("c:\\autoexec.bat");
        m.AddAttachment(a);
        smtp.SendMessage(m);

History

V1.0 (26th May 1998)

• Initial public release.

V1.1 (17th June 1998)

• Fixed the case where a single dot occurs on its own in the body of a message
• Classes now supports an optional "Reply-To" Header Field
• Classes now fully supports file attachments
• Some rework on the contents of the help file

V1.11 (18th June 1998)

• Fixed a memory overwrite problem which was occurring with the buffer used for encoding base64 attachments

API Reference

The API consists of the public member functions of the class CSMTPAddress, CSMTPMessage & CSMTPConnection

CSMTPAddress
CSMTPAttachment::Attach
CSMTPAttachment::GetFilename
CSMTPAttachment::GetEncodedBuffer
CSMTPAttachment::GetEncodedSize
CSMTPMessage::AddRecipient
CSMTPMessage::RemoveRecipient
CSMTPMessage::GetRecipient
CSMTPMessage::GetNumberOfRecipients
CSMTPMessage::AddAttachment
CSMTPMessage::RemoveAttachment
CSMTPMessage::GetAttachment
CSMTPMessage::GetNumberOfAttachments
CSMTPMessage::m_From
CSMTPMessage::m_sSubject
CSMTPMessage::m_sBody
CSMTPMessage::m_sXMailer
CSMTPMessage::m_ReplyTo
CSMTPConnection::Connect
CSMTPConnection::Disconnect
CSMTPConnection::GetLastCommandResponse
CSMTPConnection::GetLastCommandResponseCode
CSMTPConnection::GetTimeout
CSMTPConnection::SetTimeout
CSMTPConnection::SendMessage

CSMTPAddress

Remarks

This class is an encapsulation of an address used in sending an email. It consists of 2 strings namely m_sFriendlyName and m_sEmailAddress. An example of constructing an address is:

        CSMTPAddress a(_T("pjn@indigo.ie")); or
        CSMTPAddress b(_T("PJ Naughter"), _T("pjn@indigo.ie"));

The second form which includes a friendly address allows it to be used in "To" and "Reply-To" headers in the form "PJ Naughter <pjn@indigo.ie>"

One public class method is included called GetRegularFormat which returns the format just discussed.

See Also

CSMTPConnection::SendMessage

CSMTPAttachment::Attach

BOOL CSMTPAttachment::Attach(const CString& sFilename);

Return Value

TRUE if the file was successfully encoded as an attachment otherwise FALSE.

Parameters

sFilename A reference to the name of the file to setup as an attachment.

Remarks

Internally this function will perform a base64 encoding of the specified file and store the encoding in a private buffer ready for use when this attachment is associated with an SMTP message.

See Also

CSMTPMessage::AddAttachment

CSMTPAttachment::GetFilename

CString CSMTPAttachment::GetFilename() const;

Return Value

Returns the name of the file this attachment represents

Parameters

None

Remarks

This will return just the "filename.ext" form of the filename. e.g. if you called Attach with the filename "c:\autoexec.bat", the return value from GetFilename will be "autoexec.bat".

CSMTPAttachment::GetEncodedBuffer

const char* CSMTPAttachment::GetEncodedBuffer() const;

Return Value

Returns the base64 encoded representation of the attachment

Parameters

None

Remarks

None

CSMTPAttachment::GetEncodedSize

int CSMTPAttachment::GetEncodedSize() const;

Return Value

Returns the size of the encoded representation of the file

Parameters

None

Remarks

None

CSMTPMessage::AddRecipient

int CSMTPMessage::AddRecipient(CSMTPAddress& recipient);

Return Value

The index of the newly added recipient to the message.

Parameters

recipient A reference to the recipient to add to this message.

Remarks

Adds a recipient to a message. This would normally be called at least once, prior to sending an email message.

See Also

CSMTPMessage::RemoveRecipient

CSMTPMessage::RemoveRecipient

void CSMTPMessage::RemoveRecipient(int nIndex);

Return Value

None.

Parameters

nIndex The index of the recipient to remove.

Remarks

The corollary function of AddRecipient.

See Also

CSMTPMessage::AddRecipient

CSMTPMessage::GetRecipient

CSMTPAddress CSMTPMessage::GetRecipient(int nIndex) const;

Return Value

The recipient at the specified offset.

Parameters

nIndex The index of the recipient to retrieve.

Remarks

Allows access to the array of recipients associated with a message.

See Also

CSMTPMessage::AddRecipient

CSMTPMessage::GetNumberOfRecipients

int CSMTPMessage::GetNumberOfRecipients() const;

Return Value

The number of recipients for this message.

Parameters

None.

Remarks

Returns the number of recipients this message is destined for.

See Also

CSMTPMessage::AddRecipient

CSMTPMessage::AddAttachment

int CSMTPMessage::AddRecipient(CSMTPAttachment* attachment);

Return Value

The index of the newly added attachment to the message.

Parameters

attachment A pointer to the file attachment to add to this message.

Remarks

Adds an attachment to a message.

See Also

CSMTPMessage::RemoveAttachment

CSMTPMessage::RemoveAttachment

void CSMTPMessage::RemoveAttachment(int nIndex);

Return Value

None.

Parameters

nIndex The index of the attachment to remove.

Remarks

The corollary function of AddAttachment.

See Also

CSMTPMessage::AddAttachment

CSMTPMessage::GetAttachment

CSMTPAttachment* CSMTPMessage::GetAttachment(int nIndex) const;

Return Value

The attachment pointer at the specified offset.

Parameters

nIndex The index of the attachment to retrieve.

Remarks

Allows access to the array of attachments associated with a message.

See Also

CSMTPMessage::AddAttachment

CSMTPMessage::GetNumberOfAttachments

int CSMTPMessage::GetNumberOfAttachments() const;

Return Value

The number of attachments for this message.

Parameters

None.

Remarks

Returns the number of attachments this message contains.

See Also

CSMTPMessage::AddAttachment

CSMTPMessage::m_From

Remarks

This is the address of the person from which the message is being sent. You would normally set this value to your email address prior to sending a message.

See Also

CSMTPAddress

CSMTPMessage::m_sSubject

Remarks

The subject line of the message in the form of a CString. You would normally set this value to something meaningful prior to sending a message.

CSMTPMessage::m_sBody

Remarks

The body of the message in the form of a CString. You would normally set this value to something meaningful prior to sending a message.

CSMTPMessage::m_sXMailer

Remarks

The X-Mailer field which will be included in the email address. By default it is set to _T("CSMTPConnection v1.00"). You are free to change this prior to sending an email message from your application.

CSMTPMessage::m_ReplyTo

Remarks

This is the address of the person to which any replies to this message should be sent. This is an optional field which is normally not required to be present as you would normally want replies to your messages to be sent directly back to the sender of the message. By default this field is not sent with a SMTP message is sent.

See Also

CSMTPAddress

CSMTPConnection::Connect

BOOL CSMTPConnection::Connect(LPCTSTR pszHostName, int nPort = 25);

Return Value

If the function succeeds, the return value is TRUE. If the function fails, the return value is FALSE. To get extended error information, call ::GetLastError.

Parameters

pszHostName The network address of the socket to connect to: a machine name such as “mail.yourisp.com”, or a dotted number such as “128.56.22.8”.

nPort This is the port number on which to connect. The default value is 25 which is the default SMTP port number.

Remarks

Call this member function to establish a connection to a SMTP mail server.

See Also

CSMTPConnection::Disconnect

CSMTPConnection::Disconnect

BOOL CSMTPConnection::Disconnect();

Return Value

If the function succeeds, the return value is TRUE. If the function fails, the return value is FALSE. To get extended error information, call ::GetLastError.

Parameters

None.

Remarks

The corollary function of Connect.

See Also

CSMTPConnection::Connect

CSMTPConnection::GetLastCommandResponse

CString CSMTPConnection::GetLastCommandResponse() const;

Return Value

The last command response from the server as a CString.

Parameters

None.

Remarks

The CSMTPConnection class can return additional text information along with most errors. This extended error information can be retrieved by using the GetLastCommandResponse function after an unsuccessful function call. GetLastCommandResponse can be called multiple times until another CSMTPConnection function is called which sends an SMTP command.

See Also

CSMTPConnection::GetLastCommandResponseCode

CSMTPConnection::GetLastCommandResponseCode

int CSMTPConnection::GetLastCommandResponseCode() const;

Return Value

The last command response from the server as a CString.

Parameters

None.

Remarks

The CSMTPConnection class can return additional text information along with most errors. This extended error information can be retrieved by using the GetLastCommandResponse function after an unsuccessful function call. Embedded within each SMTP response is a 3 digit error code. The GetLastCommandResponseCode retrieves this value.

See Also

CSMTPConnection::GetLastCommandResponse

CSMTPConnection::GetTimeout

DWORD CSMTPConnection::GetTimeout() const;

Return Value

The timeout in milliseconds which the code will wait for responses from the SMTP server.

Parameters

None.

Remarks

Since CSMTPConnection provides a synchronous API, a timeout mechanism is provided. By default the value is 2 seconds in release mode and 20 seconds in debug mode. The value is larger in debug mode so that the code does not time out when you are debugging it.

See Also

CSMTPConnection::SetTimeout

CSMTPConnection::SetTimeout

void CSMTPConnection::SetTimeout(DWORD dwTimeout) const;

Return Value

None.

Parameters

dwTimeout The new timeout value in milliseconds.

Remarks

Sets the timeout to use for connections to the SMTP server.

See Also

CSMTPConnection::GetTimeout

CSMTPConnection::SendMessage

BOOL CSMTPConnection::SendMessage(const CSMTPMessage& Message) const;

Return Value

If the function succeeds, the return value is TRUE. If the function fails, the return value is FALSE. To get extended error information, call ::GetLastError.

Parameters

Message A const reference to the message to send.

Remarks

Sends the specified message using the server which it is currently connected to.

See Also

CSMTPMessage

PLANNED ENHANCEMENTS

• Package the code up into an OCX, COM Interface or DLL to allow non MFC apps to use the code.
• Provide a better sample app. At the moment, it's very much a test program which tests all of the functions.
• 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: pjn@indigo.ie
Web: http://indigo.ie/~pjn
17th June 1998