| |
This structure provides information about the contents of a message
and is used by the SubmitMessage
method.
typedef struct _SMTPMESSAGEEX
{
DWORD dwSize
LPCTSTR lpszFrom;
LPCTSTR lpszTo;
LPCTSTR lpszCc;
LPCTSTR lpszBcc;
LPCTSTR lpszDate;
LPCTSTR lpszSubject;
LPCTSTR lpszHeaders;
LPCTSTR lpszText;
LPCTSTR lpszHTML;
LPCTSTR lpszAttach;
UINT nCharSet;
UINT nEncType;
DWORD dwReserved;
} SMTPMESSAGEEX, *LPSMTPMESSAGEEX;
Members
- dwSize
- An integer value that specifies the size of the SMTPMESSAGEEX
data structure. This must always be explicitly defined, and if the
value is incorrect, an error will be returned. This structure member
is used to ensure that the correct version of the structure is being
passed to the method.
- lpszFrom
- A pointer to a string that specifies the email
address of the person sending the message. This structure member
must point to a valid address and cannot be NULL.
- lpszTo
- A pointer to a string that specifies the email
addresses of one or more recipients. If multiple addresses are
provided, they must be separated by commas or semi-colons. This
structure member must point to at least one valid address and cannot
be NULL.
- lpszCc
- A pointer to a string that specifies the email
addresses of one or more recipients that will receive copies of the
message. If multiple addresses are provided, they must be separated
by commas or semi-colons. This structure member may be NULL or point
to an empty string.
- lpszBcc
- A pointer to a string that specifies the email
addresses of one or more recipients that will receive blind copies
of the message. If multiple addresses are provided, they must be
separated by commas or semi-colons. This structure member may be
NULL or point to an empty string. Unlike the recipients specified by
the lpszTo and lpszCc members, any addresses specified
by this member will not be included in the header of the email
message.
- lpszDate
- A pointer to a string that specifies the date and time for
the message. This structure member may be NULL or point to an empty
string. If the date is not specified, then the current date and
time will be used by default. If a date is specified, it should be
in the standard format as defined by RFC822.
- lpszSubject
- A pointer to a string that specifies the subject
of the message. This structure member may be NULL, in which case no
subject will be included in the message.
- lpszHeaders
- A pointer to a string that specifies additional headers that
should be included in the message. Header names should be separated
from values by a colon, and multiple headers may be defined by
separating them with a newline character. This structure member may
be NULL, in which case no additional headers will be included in
the message.
- lpszText
- A pointer to a string which contains the body
of the message as plain text. Each line of text contained in the
string should be terminated with a carriage-return and linefeed (CRLF)
pair, which is recognized as the end-of-line. If this structure
member is NULL or points to an empty string, then the lpszHTML
member must specify the body of the message.
- lpszHTML
- A pointer to a string which contains the
message using HTML formatting. If the lpszText member is not
NULL, then a multipart message will be created with both plain text
and HTML text as the alternative. This allows mail clients to select
which message body they wish to display. If the lpszText
member is NULL or points to an empty string, then the message will
only contain HTML. Although this is supported, it is not recommended
because older mail clients may be unable to display the message
correctly.
- lpszAttach
- A pointer to a string which specifies one or
more file attachments for the message. If multiple files are to be
attached to the message, each file name must be separated by a
semi-colon. It is recommended that you provide the complete path to
the file. If this structure member is NULL or points to an empty
string, the message will be created without attachments.
- nCharSet
- A integer value which specifies the character set to use
when composing the message. A value of zero specifies that the
default USASCII character set should be used. The following values
may also be used:
| Constant |
Description |
| MIME_CHARSET_USASCII |
Each character is encoded in one or more bytes, with each
byte being 8 bits long, with the first bit cleared. This
encoding is most commonly used with plain text using the
US-ASCII character set, where each character is represented by a
single byte in the range of 20h to 7Eh. |
| MIME_CHARSET_ISO8859_1 |
An 8-bit character set for most western European languages
such as English, French, Spanish and German. This character set
is also commonly referred to as Latin1. |
| MIME_CHARSET_ISO8859_2 |
An 8-bit character set for most central and eastern
European languages such as Czech, Hungarian, Polish and
Romanian. This character set is also commonly referred to as
Latin2. |
| MIME_CHARSET_ISO8859_5 |
An 8-bit character set for Cyrillic languages such as
Russian, Bulgarian and Serbian. |
| MIME_CHARSET_ISO8859_6 |
An 8-bit character set for Arabic languages. Note that the
application is responsible for displaying text that uses this
character set. In particular, any display engine needs to be
able to handle the reverse writing direction and analyze the
context of the message to correctly combine the glyphs. |
| MIME_CHARSET_ISO8859_7 |
An 8-bit character set for the Greek language. |
| MIME_CHARSET_ISO8859_8 |
An 8-bit character set for the Hebrew language. Note that
similar to Arabic, Hebrew uses a reverse writing direction. An
application which displays this character should be capable of
processing bi-directional text where a single message may
include both right-to-left and left-to-right languages, such as
Hebrew and English. |
| MIME_CHARSET_ISO8859_9 |
An 8-bit character set for the Turkish language. This
character set is also commonly referred to as Latin5. |
- nEncType
- A numeric identifier which specifies the encoding type to use
when composing the message. A value of zero specifies that default
7bit encoding should be used. The following values may also be
used:
| Constant |
Description |
| MIME_ENCODING_7BIT |
Each character is encoded in one or more bytes, with each
byte being 8 bits long, with the most significant bit cleared. This
encoding is most commonly used with plain text using the US-ASCII
character set, where each character is represented by a single byte
in the range of 20h to 7Eh. |
| MIME_ENCODING_8BIT |
Each character is encoded in one or more bytes, with each
byte being 8 bits long and all bits are used. 8-bit encoding
is typically used with multibyte character sets and is the default
encoding used with Unicode text. |
| MIME_ENCODING_QUOTED |
Quoted-printable encoding is designed for textual messages
where most of the characters are represented by the ASCII
character set and is generally human-readable. Non-printable
characters or 8-bit characters with the high bit set are
encoded as hexadecimal values and represented as 7-bit text.
Quoted-printable encoding is typically used for messages which
use character sets such as ISO-8859-1, as well as those which
use HTML. |
- dwReserved
- An unsigned integer value reserved for future use. This
structure member should always have a value of zero.
Remarks
This structure is used to define the contents of a message that
will be submitted for delivery using the SubmitMessage method. It is required that you specify a sender, at least one
recipient and a message body. Other structure members may be NULL
or have a value of zero to indicate that either the value is not
required, or that a default should be used. It is recommended that you
initialize all of the structure members to a value of zero using the
ZeroMemory function prior to populating the structure.
Note that you must explicitly define the size of the structure by
setting the value of the dwSize member
variable. This ensures that the correct version of the structure is
being passed to the method.
Email addresses may be specified as simple addresses, or as
commented addresses that include the sender's name or other
information. For example, any one of these address formats are
acceptable:
user@domain.tld
User Name <user@domain.tld>
user@domain.tld (User Name)
To specify multiple addresses, you should separate each address by
a comma or semi-colon. Note that the lpszFrom member cannot specify
multiple addresses, however it is permitted with the lpszTo, lpszCc
and lpszBcc structure members. Each message must have at least
one valid recipient, or the message cannot be submitted for delivery.
If you specify a message date by assigning a value to the lpszDate
member, and it does not include any timezone information, Coordinated
Universal Time (UTC) will be used by default. This is an important
consideration if you provide input from a user, because
in most cases they will not include the timezone and will assume the date
and time they enter is for their current timezone.
If you wish to include additional headers in the message, you can
specify them in a string. Each header consists of a name and value,
separated by a colon (":") character. If you wish to define multiple
headers, then you can separate them with a newline (e.g.: a linefeed
character or combination of a carriage-return and linefeed).
Extraneous leading and trailing whitespace are trimmed from header
names and values. Invalid names or values will be ignored and will not
generate an error.
To send a message that contains HTML, it is recommended that you
provide both a plain text version of the message body and an HTML
formatted version. While it is permitted to send a message that only
contains HTML, some older mail clients may not be capable of
displaying the message correctly. In some cases, anti-spam software
will increase the spam score of messages that do not contain a plain
text message body. This can result in your message being rejected or
quarantined by the mail server.
Requirements
Minimum Desktop Platform: Windows 7 (Service Pack 1)
Minimum Server Platform: Windows Server 2008 R2 (Service Pack 1)
Header File: cstools10.h
Unicode: Implemented as Unicode and ANSI versions.
See Also
SMTPSERVER
|
|