IMessage::ModifyRecipients

项目
04/04/2023

适用于：Outlook 2013 | Outlook 2016

添加、删除或修改邮件收件人。

HRESULT ModifyRecipients(
  ULONG ulFlags,
  LPADRLIST lpMods
);

参数

ulFlags

[in]控制收件人更改的标志的位掩码。如果为 ulFlags 参数传递零， 则 ModifyRecipients 会将所有现有收件人替换为 lpMods 参数指向的收件人列表。可以为 ulFlags 设置以下标志：

MODRECIP_ADD

lpMods 参数指向的收件人应添加到收件人列表中。

MODRECIP_MODIFY

lpMods 参数指向的收件人应替换现有收件人。所有现有属性都替换为相应 ADRENTRY 结构中的属性。

MODRECIP_REMOVE

应使用 PR_ROWID (PidTagRowid) 属性包含在 lpMods 参数中每个收件人条目的属性值数组中的属性作为索引，从收件人列表中删除现有收件人。

lpMods

[in]指向 ADRLIST 结构的指针，该结构包含邮件中要添加、删除或修改的收件人列表。

返回值

S_OK

已成功修改收件人列表。

备注

IMessage：：ModifyRecipients 方法更改邮件的收件人列表。从此列表（保存在 ADRLIST 结构中）生成收件人表。

ADRLIST 结构包含每个收件人的一个 ADRENTRY 结构，每个 ADRENTRY 结构包含描述收件人属性的属性值数组。

ADRLIST 结构中的收件人可以解析或未解析。区别在于包含的属性的数量和类型。未解析的收件人仅包含 PR_DISPLAY_NAME (PidTagDisplayName) 和 PR_RECIPIENT_TYPE (PidTagRecipientType) 属性，而解析的收件人则包含这两个属性以及 (PidTagAddressType) 和 PR_ENTRYID (PidTagEntryId) PR_ADDRTYPE。如果 PR_EMAIL_ADDRESS (PidTagEmailAddress) 可用，则还可以包含它。

在提交邮件时，邮件必须仅在其收件人列表中包括已解析的收件人。未解析的收件人会导致创建未送达报告并将其发送给邮件的原始发件人。有关从客户端角度进行名称解析过程的详细信息，请参阅解析名称。有关通讯簿提供程序视角的详细信息，请参阅实现名称解析。

除了已解析和未解析的收件人之外，收件人还可以为 NULL。收件人 ADRENTRY 结构的 cValues 成员设置为零，rgPropVals 成员设置为 NULL。

给调用方的说明

可以通过调用 IAddrBook：：Address 来创建收件人列表，以显示通用对话框并提示用户选择条目。 lppAdrList 参数指向 Address 的地址列表可以作为 lpMods 参数传递给 ModifyRecipients。

在 ADRLIST 结构中为收件人指定属性时，包括收件人的所有属性，而不仅仅是新属性或已更改的属性。修改收件人时，将删除 ADRLIST 结构中未包含的任何属性。若要检索邮件的所有收件人的当前属性集，请调用 GetRecipientTable 并检索所有行。由于 SRowSet 的结构与 ADRLIST 相同，因此可以互换使用它们。

当 ulFlags 参数中未设置任何标志时，ModifyRecipients 会将当前收件人列表中的所有条目替换为 lpMods 指向的信息。

设置MODRECIP_MODIFY标志时，ModifyRecipients 会将每个收件人行替换为在 lpMods 中传递的 ADRLIST 结构中的关联行。请谨慎指定收件人应具有的所有属性，无论这些属性是否已更改以防止意外删除。

下面是在 ADRLIST 结构中设置收件人属性的一些规则：

不要将 PT_NULL 用作属性类型。在遇到此值时，ModifyRecipients 返回错误。
不要将 PT_ERROR 用作属性类型。 ModifyRecipients 忽略此值。
在 ulFlags 中设置MODRECIP_REMOVE或MODRECIP_MODIFY标志时，包括所有收件人的 PR_ROWID 属性。
在 ulFlags 中设置MODRECIP_ADD标志或在 ulFlags 中传递零时，请勿包含任何收件人的 PR_ROWID 属性。

如果包含收件人的 PR_ADDRTYPE 属性或 PR_EMAIL_ADDRESS 属性，并且其中一个或两个属性与 PR_ENTRYID标识的收件人的地址类型和地址不一致，则结果为未定义。也就是说，根据服务提供商的不同，有三种可能性：

消息将传递到 PR_ADDRTYPE 和 PR_EMAIL_ADDRESS 属性描述的地址。
邮件将传递到 由PR_ENTRYID标识的收件人。
由于地址信息不明确，消息将被声明为无法传递。

使用管理 ADRLIST 的内存和 SRowSet 结构中所述的分配规则为收件人列表分配内存。 ModifyRecipients 不会释放 ADRLIST 结构及其任何子结构。必须使用 MAPIAllocateBuffer 函数单独分配 ADRLIST 结构和每个 SPropValue 结构，以便可以单独释放每个结构。如果方法需要任何 SPropValue 结构的额外空间，它可以将 SPropValue 结构替换为一个新的结构，该结构稍后可以使用 MAPIFreeBuffer 释放。还应使用 MAPIFreeBuffer 释放原始 SPropValue 结构。