分类: C/C++
2008-08-26 11:25: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,
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 and look for RFC and 821, 822 or 2045.
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);
V1.0 (26th May 1998)
V1.1 (17th June 1998)
V1.11 (18th June 1998)
V1.12 (27th June 1998)
V1.2 (11 August 1998)
V1.21 (12 September 1998)
V1.3 (18 January 1999)
V1.31 (22 February 1999)
V1.32 (25 March 1999)
V1.33 (14 May 1999)
V1.34 (10 September 1999)
V1.35 (5 October 1999)
V1.36 (16 February 2000)
The API consists of the public member functions of the class CSMTPAddress, CSMTPMessage & CSMTPConnection
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
One public class method is included called GetRegularFormat which returns the format just discussed.
See Also
CSMTPAttachment::Attach
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
CSMTPAttachment::GetFilename
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
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
CString GetTitle() const;
Return Value
The name of the attchement as it will appear in the email
See Also
CSMTPMessage::AddRecipient
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
CSMTPMessage::RemoveRecipient
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
CSMTPMessage::GetRecipient
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
CSMTPMessage::AddAttachment
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
void RemoveAttachment(int nIndex);
Return Value
None.
Parameters
nIndex The index of the attachment to remove.
Remarks
The corollary function of AddAttachment.
See Also
CSMTPMessage::GetAttachment
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
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
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::AddBody
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
See Also
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.21"). 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
CSMTPConnection::Connect
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
CSMTPConnection::Disconnect
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
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::GetTimeout
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
CSMTPConnection::SetTimeout
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
CSMTPConnection::SendMessage
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
Please send any comments or bug reports to me via . For any updates to this article, check my site .