IMAPIProp::GetIDsFromNames

项目
04/04/2023

适用于：Outlook 2013 | Outlook 2016

提供对应于一个或多个属性名称的属性标识符。

HRESULT GetIDsFromNames(
  ULONG cPropNames,
  LPMAPINAMEID FAR * lppPropNames,
  ULONG ulFlags,
  LPSPropTagArray FAR * lppPropTags
);

参数

cPropNames

[in] lppPropNames 参数指向的属性名称计数。如果 lppPropNames 为 NULL，则 cPropNames 参数必须为 0。

lppPropNames

[in]指向属性名称数组的指针，或 NULL。传递 NULL 请求对象具有相关信息的所有属性集中所有属性名称的属性标识符。如果在 ulFlags 参数中设置了MAPI_CREATE标志，则 lppPropNames 参数不得为 NULL。

ulFlags

[in]标志的位掩码，指示应如何返回属性标识符。可以设置以下标志：

MAPI_CREATE

将属性标识符（如果尚未分配）分配给 lppPropNames 指向的属性名称数组中包含的一个或多个名称。此标志在名称到标识符映射表中内部注册标识符。

lppPropTags

[out]指向包含现有或新分配的属性标识符的属性标记数组的指针的指针。此数组中属性标记的属性类型设置为 PT_UNSPECIFIED。

返回值

S_OK

已成功返回指定属性名称的标识符。

MAPI_E_NO_SUPPORT

对象不支持命名属性。

MAPI_E_NOT_ENOUGH_MEMORY

内存不足，无法检索标识符。

MAPI_E_TOO_BIG

无法执行该操作，因为它需要返回太多属性标记。

MAPI_W_ERRORS_RETURNED

调用总体成功，但无法返回一个或多个属性标识符。每个不可用属性的相应属性类型设置为 PT_ERROR ，其标识符设置为零。返回此警告时，将调用视为成功。若要测试此警告，请使用 HR_FAILED 宏。请参阅使用宏进行错误处理。

备注

IMAPIProp：：GetIDsFromNames 方法检索属性标记数组，这些标记保存一个或多个命名属性的属性标识符。可以调用 IMAPIProp：：GetIDsFromNames 来执行以下操作：

为新名称创建标识符。
检索特定名称的标识符。
检索对象映射中包含的所有命名属性的标识符。

命名属性通常由文件夹和邮件的邮件存储提供程序使用。其他对象（如消息用户和配置文件部分）可能不支持将名称关联到属性标识符，并且可能从 GetIDsFromNames 返回MAPI_E_NO_SUPPORT。

如果错误返回特定名称的标识符， GetIDsFromNames 将返回MAPI_W_ERRORS_RETURNED并将属性标记数组条目中的属性类型设置为 PT_ERROR ，标识符为零。

名称到标识符的映射由对象的 PR_MAPPING_SIGNATURE (PidTagMappingSignature) 属性表示。 PR_MAPPING_SIGNATURE 包含一个 MAPIUID 结构，该结构指示负责对象的服务提供商。如果两个对象的 PR_MAPPING_SIGNATURE 属性相同，则假定这些对象使用相同的名称到标识符映射。

针对实现者的说明

在 lppPropNames 参数指向的属性标记数组中传递回的标识符必须位于要0xFFFE范围的0x8000中。此数组中的条目必须与 lppPropNames 指向的属性名称数组中传递的名称的顺序相同。

如果支持容器上的命名属性，请对容器中的所有对象使用相同的名称到标识符映射 (即，不要对邮件存储中的每个文件夹或文件夹中的每封邮件使用不同的映射) 。

给调用方的说明

由于 lppPropTags 指向的属性标记数组中返回的标识符的属性类型设置为 PT_UNSPECIFIED，因此必须调用 IMAPIProp：：SetProps 方法才能检索准确的类型。

如果移动或复制具有命名属性的对象，并且源对象和目标对象具有其 PR_MAPPING_SIGNATURE 属性值指示的不同映射签名，则必须在这些操作期间保留这些名称。若要保留属性名称，请调整相应的属性标识符以匹配目标对象的名称到标识符映射。

某些对象对可以命名的属性标识符数有限制。如果对 GetIDsFromNames 的 调用导致超出此限制，该方法将返回MAPI_E_TOO_BIG。在这种情况下，按标识符查询。

有关详细信息，请参阅 MAPI 命名属性。

MFCMAPI 引用

有关 MFCMAPI 示例代码，请参阅下表。

文件	函数	Comment
SingleMAPIPropListCtrl.cpp	CSingleMAPIPropListCtrl：：FindAllNamedPropsUsed	MFCMAPI 使用 IMAPIProp：：GetIDsFromNames 方法获取已映射的所有命名属性的属性标记。