| |
| HMESSAGE WINAPI MimeComposeMessage(
|
| |
LPCTSTR lpszFrom, |
|
| |
LPCTSTR lpszTo, |
|
| |
LPCTSTR lpszCc, |
|
| |
LPCTSTR lpszSubject, |
|
| |
LPCTSTR lpszMessageText, |
|
| |
LPCTSTR lpszMessageHTML, |
|
| |
UINT nCharacterSet, |
|
| |
UINT nEncodingType |
|
| );
|
The MimeComposeMessage function creates a new message
using the specified parameters.
Parameters
- lpszFrom
- A pointer to a null-terminated string which specifies the
sender's email address. This parameter may be NULL, in which case
no sender address will be included in the message header.
- lpszTo
- A pointer to a null-terminated string which specifies one or
more recipient addresses. If multiple addresses are specified, each
address must be separated by a comma. This parameter may be NULL,
in which case no recipient addresses will be included in the
message header.
- lpszCc
- A pointer to a null-terminated string which specifies one or
more addresses that will receive a copy of the message in addition
to the listed recipients. If multiple addresses are specified, each
address must be separated by a comma. This parameter may be NULL,
in which case no carbon-copy addresses will be included in the
message header.
- lpszSubject
- A pointer to a null-terminated string which specifies the
subject of the message. This parameter may be NULL, in which case
no subject will be included in the message.
- lpszMessageText
- A pointer to a null-terminated 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
parameter is NULL or points to an empty string, then the message
will have an empty body unless the lpszMessageHTML parameter
is not NULL.
- lpszMessageHTML
- A pointer to a null-terminated string which contains the
message using HTML formatting. If the lpszMessageText
parameter 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 lpszMessageText argument 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.
- nCharacterSet
- A numeric identifier 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 |
The default character set using US-ASCII which defines 7-bit
printable characters with values ranging from 20h to 7Eh. An
application that uses this character set has the broadest
compatibility with most mail servers (MTAs) because it does not
require the server to handle 8-bit characters correctly when the
message is delivered. This is the most commonly used character set
for plain text e-mail messages in the English language and is the
default character set used by the library. |
| 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. The Windows code page for this
character set is 28591, however Windows code page 1252
(Windows-1252) is typically used to represent this character set in
most applications. |
| 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. This
character set is similar to Windows code page 1250, however the
characters are arranged differently. |
| MIME_CHARSET_ISO8859_5 |
An 8-bit character set for Cyrillic languages such as Russian,
Bulgarian and Serbian. The Windows code page for this character set
is 28595. This character set is not widely used and it is
recommended that you use UTF-8 instead. |
| 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. This character set is
not widely used and it is recommended that you use UTF-8
instead. |
| MIME_CHARSET_ISO8859_7 |
An 8-bit character set for the Greek language. This character
set is also commonly referred to as Latin/Greek. The Windows code
page for this character set is 28597. |
| 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. The Windows code page for this character set is
28598. |
| MIME_CHARSET_ISO8859_9 |
An 8-bit character set for the Turkish language. This character
set is also commonly referred to as Latin5. The Windows code page
for this character set is 28599. |
| MIME_CHARSET_UTF7 |
A 7-bit Unicode Transformation Format that uses variable-length
character encoding to represent Unicode text as a stream of ASCII
characters that are safe to transport between mail servers that
only support 7-bit printable characters. It is primarily used as an
alternative to UTF-8 which requires that the mail server support
8-bit text or use quoted-printable encoding. |
| MIME_CHARSET_UTF8 |
An 8-bit Unicode Transformation Format that uses multibyte
character sequences to represent Unicode text. It is backwards
compatible with the ASCII character set, however because it uses
8-bit text, it should be encoded using either quoted-printable or
base64 encoding to ensure that mail servers that do not support
8-bit characters. |
- nEncodingType
- 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 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. Most e-mail messages are composed using 7-bit
ASCII. |
| 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 may be used
with multi-byte character sets, although this encoding type is
uncommon in e-mail messages. It is recommended that
quoted-printable encoding be used for 8-bit character sets. |
| 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. |
Return Value
If the function succeeds, the return value is a handle to the
message. If the function fails, the return value is
INVALID_MESSAGE. To get extended error information, call
MimeGetLastError.
Remarks
The MimeComposeMessage function composes a new message
and returns a handle which can be used to further modify or export
the message. To create an empty message without any predefined
header values, call the MimeCreateMessage function.
E-mail 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 parameter
cannot specify multiple addresses, however it is permitted with the
lpszTo, lpszCc and lpszBcc parameters.
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.
Call the MimeDeleteMessage function to free the memory
allocated for this message when it is no longer needed.
Requirements
Client: Requires Windows 7, Windows Vista or Windows
XP.
Server: Requires Windows Server 2008 or Windows Server
2003.
Header: Include cstools7.h.
Library: Use csmsgav7.lib.
Unicode: Implemented as Unicode and ANSI versions.
See Also
MimeCreateMessage, MimeCreateMessagePart, MimeDeleteMessage, MimeExportMessage, MimeImportMessage, MimeInitialize
|
|