 |
|||||||||
|
|||||||||
|
|||||||||
Web Development »
Internet / Network »
General
Intermediate
CSMTPConnection v1.36By PJ NaughterAn MFC class to encapsulate the SMTP protocol. |
VC6, C++Windows, NT4, MFC, VS6, VS, Dev Posted: 9 Mar 2000 Updated: 3 Mar 2000 Views: 280,265 |
||
|
|
|||
 |
Summer Code Competition! |
 |
Code Generation comp. $1,000 prize! |
 |
Win CodeProject Coffee! |
|
Monthly Competition |
- .NET SOFTWARE DEVELOPER/ENGINEER at Manticore Technology
- Product Planner, Visual Studio at Microsoft
- Product Manager: Visual Studio Web Development at Microsoft
- View Latest Jobs...
|
Advanced Search Sitemap |
|
|
|
||||||||||||||||
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,
Other documents that these classes refer to are RFC 2045 (which defines how MIME attachments are to be handled in a standard SMTP message) and RFC 822 (which defines the way standard headers which SMTP uses).
You can find numerous Web Servers which carry these documents by going to www.yahoo.com and look for RFC and 821, 822 or 2045.
| Features |
| Usage |
| History |
| API Reference |
| Planned Enhancements |
| Contacting the Author |
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 sending file attachments.
- Multi CC, BCC & Reply To support is included.
- Support for regular email address formats and multiple email address parsing.
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.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);
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.
V1.12 (27th June 1998)
- The case where a line begins with a "." but contains other text is now also catered for. See RFC821, Section 4.5.2 for further details.
- m_sBody in CSMTPMessage has now been made protected. Client applications now should call AddBody instead. This ensures that FixSingleDot is only called once even if the same message is sent a number of times.
- Fixed a number of problems with how the MIME boundaries were defined and sent.
- Got rid of an unreferenced formal parameter compiler warning when doing a release build.
V1.2 (11 August 1998)
- VC 5 project file is now provided instead of VC 4.x
- Attachment array which the message class contains now uses references instead of pointers.
- Now uses Sleep(0) to yield our time slice instead of Sleep(100), this is the preferred way of writting polling style code in Win32 without serverly impacting performance.
- All trace statements now display the value as returned from GetLastError
- A number of extra asserts have been added
- AddMultipleRecipients has been added which supports added a number of recipients at one time from a single string
- Extra trace statements have been added to help in debugging
- A number of updates to the documentation.
V1.21 (12 September 1998)
- Removed a couple of unreferenced variable compiler warnings discovered when the class was compiled on Visual C++ 6.0.
- Fixed a major bug which was causing an ASSERT when the CSMTPAttachment destructor was being called in the InitInstance of the sample app. This was inadvertingly introduced for the 1.2 release. The fix is to revert fix 2) as done for v1.2. This new fix will also help to reduce the number of attachment images kept in memory at one time.
- Fixed a few errors in this help file.
V1.3 (18 January 1999)
- Full support has now been added for CC (Carbon Copy) & BCC (Blind Carbon Copy).
V1.31 (22 February 1999)
- Added a Get and SetTitle method which allows a files attachment title to be different that the original filename.
- Updated sample app to include a more descriptive subject line.
- Default timeout for the code when a debug build is built has now been set to 60 seconds.
- Improved the reading of responses back from the server by implementing a growable receive buffer.
- Updated instructions on how the relavent RFC documents can be retrieved.
V1.32 (25 March 1999)
- Now sleeps for 250 ms instead of yielding the time slice. This helps reduce CPU usage when waiting for data to arrive in the socket.
V1.33 (14 May 1999)
- Updated documentation to refer to RFC 822.
- Fixed a bug with the way the code generates time zone fields in the Date headers. Thanks to Randy A. Scott for reporting this bug.
V1.34 (10 September 1999)
- Improved CSMTPMessage::GetHeader to include mime field even when no attachments are included.
V1.35 (5 October 1999)
- Fixed 2 level 4 warnings when compiled using VC 6.
V1.36 (16 February 2000)
- Fixed another compiler problem when compiled with VC 6.
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
CSMTPAttachment::SetTitle
CSMTPAttachment::GetTitle
CSMTPMessage::AddRecipient
CSMTPMessage::RemoveRecipient
CSMTPMessage::GetRecipient
CSMTPMessage::GetNumberOfRecipients
CSMTPMessage::AddAttachment
CSMTPMessage::RemoveAttachment
CSMTPMessage::GetAttachment
CSMTPMessage::GetNumberOfAttachments
CSMTPMessage::m_From
CSMTPMessage::m_sSubject
CSMTPMessage::AddBody
CSMTPMessage::AddMultipleRecipients
CSMTPMessage::m_sXMailer
CSMTPMessage::m_ReplyTo
CSMTPConnection::Connect
CSMTPConnection::Disconnect
CSMTPConnection::GetLastCommandResponse
CSMTPConnection::GetLastCommandResponseCode
CSMTPConnection::GetTimeoutCSMTPConnection::SetTimeout
CSMTPConnection::SendMessage
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
BOOL 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
CString 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* GetEncodedBuffer() const;
Return Value
Returns the base64 encoded representation of the attachment
Parameters
None
Remarks
None
CSMTPAttachment::SetTitle
void SetTitle(const CString& sTitle);
Parameters
sTitle The new title of the file attachment
Remarks
Allows you to change the name of the attachment as it will appear in the email. By default it will be the filename of the file you add. Examples where this are useful are if you save a file to a temporary filename on your machine prior to emailing it to someone.
See Also
CSMTPAttachment::GetTitle
CString GetTitle() const;
Return Value
The name of the attchement as it will appear in the email
See Also
int AddRecipient(CSMTPAddress& recipient, RECIPIENT_TYPE RecipientType = TO);
Return Value
The index of the newly added recipient to the message.
Parameters
recipient A reference to the recipient to add to this message.
RecipientType The type of recipient to add. RECIPIENT_TYPE is an enum with the following three values: TO, CC & BCC
Remarks
Adds a recipient of the specified type to a message. This would normally be called at least once, prior to sending an email message.
See Also
void RemoveRecipient(int nIndex, RECIPIENT_TYPE RecipientType = TO);
Return Value
None.
Parameters
nIndex The index of the recipient to remove.
RecipientType The type of recipient "nIndex" refers to. RECIPIENT_TYPE is an enum with the following three values: TO, CC & BCC
Remarks
The corollary function of AddRecipient.
See Also
CSMTPAddress GetRecipient(int nIndex, RECIPIENT_TYPE RecipientType = TO) const;
Return Value
The recipient at the specified offset.
Parameters
nIndex The index of the recipient to retrieve.
RecipientType The type of recipient "nIndex" refers to. RECIPIENT_TYPE is an enum with the following three values: TO, CC & BCC
Remarks
Allows access to the array of recipients associated with a message.
See Also
CSMTPMessage::GetNumberOfRecipients
int GetNumberOfRecipients(RECIPIENT_TYPE RecipientType = TO) const;
Return Value
The number of recipients for this message.
Parameters
RecipientType The type of recipients to retreive the size for. RECIPIENT_TYPE is an enum with the following three values: TO, CC & BCC
Remarks
Returns the number of recipients this message is destined for.
See Also
int AddAttachment(CSMTPAttachment* pAttachment);
Return Value
The index of the newly added attachment to the message.
Parameters
pAttachment A pointer to the file attachment to add to this message.
Remarks
Adds an attachment to a message. Please bear in mind that internally a buffer will be allocated by this function and which is used while sending the attachment. This means that the "attachment" instance must remain valid during the lifetime of the call to CSMTPConnection::SendMessage
See Also
CSMTPMessage::RemoveAttachment CSMTPConnection::SendMessage
CSMTPMessage::RemoveAttachment
void RemoveAttachment(int nIndex);
Return Value
None.
Parameters
nIndex The index of the attachment to remove.
Remarks
The corollary function of AddAttachment.
See Also
CSMTPAttachment* GetAttachment(int nIndex) const;
Return Value
A pointer to the attachment 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::GetNumberOfAttachments
int GetNumberOfAttachments() const;
Return Value
The number of attachments for this message.
Parameters
None.
Remarks
Returns the number of attachments this message contains.
See Also
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
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.
void AddBody(const CString& sBody);
Return Value
None.
Parameters
sBody A reference to the text to add to the body of the message.
Remarks
Internally this function will ensure that the contents of the string conforms to the standards required for an SMTP message. Prior to v1.12 a public member m_sBody was available. Client applications now should call AddBody instead. This ensures that the internal function FixSingleDot is only called once even if the same message is sent a number of times.
See Also
CSMTPMessage::AddMultipleRecipients
BOOL AddMultipleRecipients(const CString& sRecipients);
Return Value
TRUE if the string was successfully parsed for recipients otherwise FALSE.
.Parameters
sRecipients A string containing a number of recipient addresses.
Remarks
This function allows the class to add a number of recipients quickly without having to create a single CSMTPAddress for each recipient. The delimters allowed in the string are ";" and "," and friendly names can be specified with "<", ">" delimiters. An example of a valid string is:
face="Times New Roman">"PJ Naughter <pjn@indigo.ie> , My Boss <someboss@company.com> ; Joe <joe@ms.com>"
See Also
Remarks
The X-Mailer field which will be included in the email address. By default it is set to _T("CSMTPConnection v1.21"). You are free to change this prior to sending an email message from your application.
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
BOOL 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
BOOL 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::GetLastCommandResponse
CString 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 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
DWORD 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
void 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
BOOL 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
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
Please send any comments or bug reports to me via email. For any updates to this article, check my site here.
