IABLogon::PrepareRecips
适用于：Outlook 2013 | Outlook 2016
准备收件人列表，供消息系统稍后使用。
HRESULT PrepareRecips(
ULONG ulFlags,
LPSPropTagArray lpPropTagArray,
LPADRLIST lpRecipList
);
参数
ulFlags
[in]控制返回字符串中文本类型的标志的位掩码。 可以设置以下标志：
- MAPI_CACHE_ONLY：仅使用脱机通讯簿来执行名称解析。 例如，可以使用此标志允许客户端应用程序在缓存交换模式下打开全局地址列表 (GAL) ，并从缓存访问该通讯簿中的条目，而无需在客户端和服务器之间创建流量。 仅 Exchange 通讯簿提供程序支持此标志。
lpPropTagArray
[in]指向 SPropTagArray 结构的指针，该结构包含属性标记数组，这些标记指示需要更新的属性（如果有）。 lpPropTagArray 参数可以为 NULL。
lpRecipList
[in]指向保存收件人列表的 ADRLIST 结构的指针。
返回值
S_OK
已成功准备收件人列表。
MAPI_E_NOT_FOUND
lpRecipList 参数中的一个或多个收件人不存在。
客户端调用 MAPI IAddrBook：:P repareRecips 方法修改或重新排列一个或多个收件人的一组属性。 收件人可能是也可能不是传出邮件的收件人列表的一部分。 MAPI 将此调用转移到通讯簿提供程序的 IABLogon：:P repareRecips 方法。
IABLogon：:P repareRecips 执行四个main任务：
确保 lpRecipList 参数指向的地址列表中的所有收件人都具有长期条目标识符。
确保所有收件人都具有 lpPropTagArray 参数指向的属性值数组中指定的属性。
确保属性值数组中的属性显示在调用之前存在的任何其他属性之前。
确保 ADRLIST 结构中每个收件人 ADRENTRY 结构中的属性顺序与属性值数组中的属性顺序相同。
lpRecipList 参数中的 ADRENTRY 结构包含每个收件人的一个 ADRENTRY 结构。 每个 ADRENTRY 结构都包含一个 SPropValue 结构数组，用于描述收件人的属性。 当 IABLogon：:P repareRecips 返回时，每个收件人的 SPropValue 结构数组包括 来自 lpPropTagArray 的属性，后跟收件人的其他属性。
针对实现者的说明
实现 IABLogon：:P repareRecips 涉及按特定顺序放置属性、检索属性值以及将短期条目标识符转换为长期条目标识符。 lpPropTagArray 参数中请求的属性必须位于与 lpRecipList 参数中每个收件人的 ADRENTRY 结构关联的属性值数组的开头。 如果这些属性的值不存在，请使用其入口标识符打开关联的消息用户或通讯组列表，并检索缺少的属性值。
单独分配在 lpRecipList 中传递的每个 SPropValue 结构，以便可以单独释放结构。 如果必须为任何 SPropValue 结构分配额外的空间（例如，若要存储字符串属性的数据），请使用 MAPIAllocateBuffer 函数为完整的属性值数组分配额外的空间。 使用 MAPIFreeBuffer 函数释放原始属性值数组，然后使用 MAPIAllocateMore 函数分配所需的任何其他内存。
若要实现 IABLogon：:P repareRecips，请使用以下过程：
检查 lpPropTagArray 参数中的条目。 如果属性值数组为空，则无需执行任何操作。 返回成功值。
处理 lpRecipList 参数中的每个收件人。 列表中每个收件人都有一个 ADRENTRY 结构成员。 忽略以下类型的收件人：
在其 ADRENTRY 结构的 rgPropVals 成员中没有条目标识符的收件人 (，即未解析的收件人) 。
具有不属于提供商的条目标识符的收件人。 这些收件人将传递给另一个通讯簿提供商。
打开收件人并检索已为收件人设置的属性。
将 lpRecipList 中指定的属性值数组与从 GetProps 返回的属性数组合并。 如果同一属性出现在两个属性数组中，请使用 lpRecipList 中的值。
如果 lpRecipList 属性值数组足够大，足以容纳所有必要的属性，只需将其替换为合并的数组即可。 如果 lpRecipList 属性值数组不够大，请将其替换为新分配的数组。 请确保新数组在其每个 cValues 成员中都有更新的值。
如果无法识别 lpPropTagArray 参数中的一个或多个属性，请在收件人的 ADRENTRY 结构中将属性类型设置为 PT_ERROR，并将属性值设置为 MAPI_E_NOT_FOUND 或另一个值，该值提供属性不可用的更具体原因。 有关PT_ERROR的信息，请参阅 属性类型。
注意
切勿重新分配传递到 IABLogon：:P repareRecips 的 ADRLIST 结构或更改其条目数。