MAPISENDMAILW 回调函数 (mapi.h)

项目
08/24/2023

发送 Unicode 消息。此函数替换 ANSI 函数 MAPISendMail。

在 Windows 7 及更早版本上： 安装适用于 Windows 8 的 Microsoft Windows 软件开发工具包 (SDK) ，并使用 MAPISendMailHelper 发送邮件。

除非另行指定，否则所有信息都适用于 MAPISendMailW 和 MAPISendMail 。

语法

MAPISENDMAILW Mapisendmailw;

ULONG Mapisendmailw(
  [in] LHANDLE lhSession,
  [in] ULONG_PTR ulUIParam,
  [in] lpMapiMessageW lpMessage,
  [in] FLAGS flFlags,
       ULONG ulReserved
)
{...}

parameters

[in] lhSession

类型： LHANDLE

简单 MAPI 会话的句柄或零。

如果 lhSession 参数的值为零，则 MAPI 将记录用户并创建仅在调用期间存在的会话。此临时会话可以是现有共享会话，也可以是新会话。如有必要，将显示登录对话框。

[in] ulUIParam

类型： ULONG_PTR

父窗口句柄或零。

如果 ulUIParam 参数包含父窗口句柄，则句柄的类型为 HWND (强制转换为 ULONG_PTR) 。

如果在调用期间未显示任何对话框，则忽略 ulUIParam 。

[in] lpMessage

类型： lpMapiMessageW

指向包含要发送的邮件的 MAPISendMailW 结构的指针。

注意对于 MAPISendMail 函数，此参数指向 MapiMessage 结构。

调用函数时，请注意有关消息结构成员的以下信息：

成员	注释
lpFiles	当邮件没有文件附件时，将此成员设置为 NULL 。
lpszMessageType	由不处理人际消息的应用程序使用。如果应用程序处理人际消息，请将 lpszMessageType 成员设置为 NULL ，或将其设置为指向空字符串。
lpszSubject	NULL 值表示邮件的主题没有文本。
lpszNoteText	NULL 值表示消息正文中没有文本。
lpRecips	NULL 值表示没有收件人。此外，如果此成员为 NULL，则 nRecipCount 成员必须为零。
nRecipCount	如果值为零，则表示没有收件人。此外，如果此成员为零，则 lpRecips 成员必须为 NULL。

提示调用函数且没有收件人时，必须设置 MAPI_DIALOG 标志或 MAPI_DIALOG_MODELESS 标志以提示用户输入收件人信息。

如果未设置 MAPI_DIALOG 或 MAPI_DIALOG_MODELESS ，则结构的 nRecipCount 和 lpRecips 成员必须有效才能成功传递消息。客户端应用程序可以将 flFlags 成员设置为 MAPI_RECEIPT_REQUESTED 以请求读取报表。

有关函数如何处理收件人信息的更多详细信息，请参阅处理备注中的收件人信息。

[in] flFlags

类型： FLAGS

选项标志的位掩码。可以设置以下标志。

值	含义
MAPI_DIALOG 0x00000008	应显示应用程序模式对话框，提示用户输入收件人和其他发送选项。如果未设置 MAPI_DIALOG 和 MAPI_DIALOG_MODELESS ，则必须至少指定一个收件人。
MAPI_DIALOG_MODELESS 0x00000004 \|MAPI_DIALOG	在具有下一个 Office 版本的 Windows 上可用：应显示无模式对话框，提示用户输入收件人和其他发送选项。如果设置了 MAPI_DIALOG_MODELESS ，则 lhSession 参数应设置为零。否则，如果设置了此标志并且 lhSession 不为零，Outlook 将引发异常。此外，如果设置了 MAPI_DIALOG_MODELESS ，系统会忽略 MAPI_NEW_SESSION 标志。如果未设置 MAPI_DIALOG 和 MAPI_DIALOG_MODELESS ，则必须至少指定一个收件人。提示若要在 Windows 7 或更早版本上使用此标志，必须同时安装适用于 Windows 8 的 Windows SDK 和 Office 的下一个版本，并且必须调用 MAPISendMailHelper 而不是 MAPISendMailW。
MAPI_LOGON_UI 0x00000001	应显示一个对话框，提示用户根据需要登录。如果未设置 MAPI_LOGON_UI 标志，则客户端应用程序不会显示登录对话框，如果用户未登录，则返回错误值。如果 lpszMessageID 参数为空，则忽略MAPI_LOGON_UI 标志。
MAPI_NEW_SESSION 0x00000002	尝试创建新会话，而不是获取环境的共享会话。如果未设置 MAPI_NEW_SESSION 标志，则函数将使用现有的共享会话。如果设置 MAPI_NEW_SESSION 标志 (阻止使用共享会话) 并且配置文件需要密码，则还必须设置 MAPI_LOGON_UI 标志，否则函数将失败。客户端应用程序可以通过使用没有密码的默认配置文件或不使用密码的显式配置文件来避免此故障。
MAPI_FORCE_UNICODE 0x00040000	如果提供程序不支持 Unicode，请不要将消息转换为 ANSI。注意此标志仅适用于 MAPISendMailW 。

ulReserved

类型： ULONG

保留;必须为零。

返回值

类型： ULONG

此函数返回以下值之一。

返回代码/值	说明
MAPI_E_AMBIGUOUS_RECIPIENT 21	收件人匹配多个收件人描述符结构，并且未设置MAPI_DIALOG。未发送任何消息。
MAPI_E_ATTACHMENT_NOT_FOUND 11	找不到指定的附件。未发送任何消息。
MAPI_E_ATTACHMENT_OPEN_FAILURE 12	无法打开指定的附件。未发送任何消息。
MAPI_E_ATTACHMENT_TOO_LARGE 28	指定的附件太大。未发送任何消息。
MAPI_E_BAD_RECIPTYPE 15	收件人的类型不是MAPI_TO、MAPI_CC或MAPI_BCC。未发送任何消息。
MAPI_E_FAILURE 2	发生了一个或多个未指定的错误。未发送任何消息。
MAPI_E_INSUFFICIENT_MEMORY 5	内存不足，无法继续。未发送任何消息。
MAPI_E_INVALID_RECIPS 25	一个或多个收件人无效或未解析为任何地址。
MAPI_E_LOGIN_FAILURE 3	没有默认登录，并且显示登录对话框时用户无法成功登录。未发送任何消息。
MAPI_E_TEXT_TOO_LARGE 18	消息中的文本太大。未发送任何消息。
MAPI_E_TOO_MANY_FILES 9	文件附件太多。未发送任何消息。
MAPI_E_TOO_MANY_RECIPIENTS 10	接收者太多。未发送任何消息。
MAPI_E_UNICODE_NOT_SUPPORTED 27	指定了 MAPI_FORCE_UNICODE 标志，并且不支持 Unicode。注意此值只能由 MAPISendMailW 返回。
MAPI_E_UNKNOWN_RECIPIENT 14	收件人未显示在地址列表中。未发送任何消息。
MAPI_E_USER_ABORT 1	用户取消了其中一个对话框。未发送任何消息。
SUCCESS_SUCCESS 0	调用成功，消息已发送。

注解

MAPISendMailW (Unicode) 和 MAPISendMail (ANSI) 函数都发送标准消息，无论是否具有任何用户交互。必须配置配置文件，以便任一函数都可以打开默认服务提供程序，而无需用户交互。

MAPISendMailW 和 MAPISendMail 都不需要发起方类型的收件人来发送邮件。

客户端应用程序可以提供收件人姓名、主题文本、文件附件或邮件文本的完整列表或部分列表。如果缺少任何信息， (MAPISendMailW 或 MAPISendMail) 调用的函数可以提示用户输入缺失的信息。

如果未缺少任何信息，则可以按原样发送消息，或者可以提示用户验证信息并在必要时更改值。

MAPISendMailW 和 MAPISendMail 都不同于 MAPISendDocuments 函数，因为它们允许在生成消息时具有更大的灵活性。

消息文本

某些客户端应用程序可以截断过长或包含回车符、换行符或表单源的主题行。

每个段落都应以 CR (0x0d) 、LF (0x0a) 或 CRLF 对 (0x0d0a) 结尾。 MAPISendMailW 和 MAPISendMail 均根据需要换行。

如果文本超出系统限制，函数将返回 MAPI_E_TEXT_TOO_LARGE 值。

文件附件

在某些消息传送系统中，每封邮件的附件数可能会受到限制。如果超出此限制，函数将失败并返回 MAPI_E_TOO_MANY_FILES 值。

在函数返回之前，将文件附件复制到消息中;因此，以后对文件的更改不会影响消息的内容。复制文件时，必须关闭这些文件。

不要尝试显示邮件文本范围之外的附件。

收件人

某些消息传送系统可以限制每封邮件的收件人数。如果客户端应用程序传递指示超过系统限制的收件人数的非 NULL 值，则该函数将失败并返回 MAPI_E_TOO_MANY_RECIPIENTS 值。

如果客户端应用程序将消息发送到一个或多个自定义收件人，并且你想要避免解析这些收件人的姓名，则必须指定自定义收件人的地址。

若要在调用 MAPISendMailW 时指定收件人的地址，必须将包含收件人信息的 MapiRecipDescW 结构的 lpszAddress 成员设置为自定义地址。此 MapiRecipDescW 结构包含在存储在 MapiMessageW 结构的 lpRecips 成员中的收件人数组中，该成员由 lpMessage 参数传递给函数。

注意若要在调用 MAPISendMail 时指定收件人的地址，请按照 MAPISendMailW 的上述说明操作，但请替换 MapiRecipDesc 和 MapiMessage 结构。

从函数成功返回并不一定意味着接收方验证。邮件可能尚未发送给所有收件人。根据传输提供程序，收件人验证过程可能很长。

处理收件人信息

MapiMessageW 或 MapiMessage 结构的 lpRecips 成员可以包含条目标识符、收件人的姓名、地址或姓名和地址对。下表显示了函数如何处理每个事例。

收件人信息	操作
条目标识符	无名称解析;名称和地址将被忽略。
名称	使用简单 MAPI 解析规则解析的名称。
地址	无名称解析;address 用于邮件传递和显示收件人姓名。
名称和地址	无名称解析;name 仅用于显示收件人姓名。

要求


最低受支持的客户端	Windows 8 [仅限桌面应用]
最低受支持的服务器	Windows Server 2012 [仅限桌面应用]
目标平台	Windows
标头	mapi.h

另请参阅

MAPISendMailHelper

适用于 Windows 8 的 Windows SDK

Share via