CSMTPConnection v1.3
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 |
Usage |
History |
API Reference |
Planned Enhancements |
Contacting the Author |
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.AddBody("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);
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)
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::AddBody
CSMTPMessage::AddMultipleRecipients
CSMTPMessage::m_sXMailer
CSMTPMessage::m_ReplyTo
CSMTPConnection::Connect
CSMTPConnection::Disconnect
CSMTPConnection::GetLastCommandResponse
CSMTPConnection::GetLastCommandResponseCode
CSMTPConnection::GetTimeout
CSMTPConnection::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::GetEncodedSize
int GetEncodedSize() const;
Return Value
Returns the size of the encoded representation of the file
Parameters
None
Remarks
None
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:
"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
PJ Naughter
Email: pjn@indigo.ie
Web: http://indigo.ie/~pjn
18th January 1999