| |
| INT WINAPI MimeEnumMessageRecipients(
|
| |
HMESSAGE hMessage, |
|
| |
LPCTSTR lpszExtraAddress, |
|
| |
LPTSTR lpBuffer, |
|
| |
LPDWORD lpcchBuffer |
|
| );
|
The MimeEnumMessageRecipients function returns a
null-terminated list of strings which contain the email address of
each recipient for the specified message.
Parameters
- hMessage
- Handle to the message.
- lpszExtraAddress
- A pointer to a null-terminated string which contains one or
more additional email addresses that should be included in the
list, in addition to those found in the message. If more than one
address is specified, each address should be separated by a comma.
This parameter may be NULL if there are no extra addresses to
include in the recipient list.
- lpBuffer
- Pointer to buffer which will contain zero or more
null-terminated strings. The end of the string list is indicated by
an additional terminating null. If this parameter is NULL, the
function will calculate the minimum number of bytes required to
store the addresses and return the value in the lpcbBuffer
parameter.
- lpcchBuffer
- A pointer to an unsigned long integer which should be
initialized to the maximum number of characters that can be copied
into the buffer specified by the lpBuffer parameter. When
the function returns, it will be updated to contain the actual
number of characters copied into the buffer. If the lpBuffer
parameter is NULL, then this value will contain the minimum number
of characters required to store all of the recipient addresses in
the current message.
Return Value
If the function succeeds, the return value is the total number
of recipients for the current message. If the function fails, the
return value is MIME_ERROR. To get extended error information, call
MimeGetLastError.
Remarks
The MimeEnumMessageRecipients function returns a list of
recipient e-mail addresses for the specified message, with each
address being terminated by a null character. The end of the list
is indicated by an additional null character. To determine the size
of the buffer you should pass to this function, you can specify the
lpBuffer parameter as NULL and initialize the value of the
lpcchBuffer parameter to zero.
This function is primarily designed for use with C/C++ and
languages that can easily use C-style strings and pointers to
string values. In many cases, it may be preferable to use the
MimeGetAllRecipients function which returns a
comma-separated list of recipient addresses in a string buffer.
Example
LPTSTR lpRecipients = NULL;
DWORD cchRecipients = 0;
INT nRecipients = 0;
// Determine the number of characters that should be allocated to store
// all of the recipient addresses in the current message
nRecipients = MimeEnumMessageRecipients(hMessage,
NULL,
NULL,
&cchRecipients);
// Allocate the memory for the string buffer that will contain all
// of the recipient addresses and call MimeEnumMessageRecipients
// again to store those addresses in the buffer
if (nRecipients > 0 && cchRecipients > 0)
{
lpRecipients = (LPTSTR)LocalAlloc(LPTR, cchRecipients * sizeof(TCHAR));
if (lpRecipients == NULL)
return; // Virtual memory exhausted
nRecipients = MimeEnumMessageRecipients(hMessage,
NULL,
lpRecipients,
&cchRecipients);
}
// Move through the buffer, processing each recipient address
// that was returned
if (nRecipients > 0)
{
LPTSTR lpszAddress = lpRecipients;
INT cchAddress;
while (lpszAddress != NULL)
{
if ((cchAddress = lstrlen(lpszAddress)) == 0)
break;
// lpszAddress specifies a recipient address
// Advance to the next address string in the buffer
lpszAddress += cchAddress + 1;
}
}
if (lpRecipients)
{
LocalFree((HLOCAL)lpRecipients);
lpRecipients = NULL;
}
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
MimeGetAllRecipients,
MimeGetFirstMessageHeader,
MimeGetMessageHeader,
MimeGetNextMessageHeader,
MimeSetMessageHeader
|
|