IMAPIProp::GetNamesFromIDs

项目
04/04/2023

适用于：Outlook 2013 | Outlook 2016

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

HRESULT GetNamesFromIDs(
  LPSPropTagArray FAR * lppPropTags,
  LPGUID lpPropSetGuid,
  ULONG ulFlags,
  ULONG FAR * lpcPropNames,
  LPMAPINAMEID FAR * FAR * lpppPropNames
);

参数

lppPropTags

[in，out]输入时，指向包含属性标记数组的 SPropTagArray 结构的指针;否则为 NULL，指示应返回所有名称。属性标记数组的 cValues 成员不能为 0。如果 lppPropTags 是输入上的有效指针， 则 GetNamesFromIDs 将返回数组中包含的每个属性标识符的名称。

lpPropSetGuid

[in]指向标识属性集的 GUID 或 GUID 结构的指针。 lpPropSetGuid 参数可以指向有效的属性集，也可以为 NULL。

ulFlags

[in]指示要返回的名称类型的标志的位掩码。如果设置了两个标志，则可以 (使用以下标志，) 不会返回任何名称：

MAPI_NO_IDS

仅返回存储为 Unicode 字符串的名称的请求。

MAPI_NO_STRINGS

仅返回存储为数字标识符的名称的请求。

lpcPropNames

[out]指向 lppPropNames 参数指向的数组中属性名称指针计数的指针的指针。

lpppPropNames

[out]指向指向包含属性名称的 MAPINAMEID 结构的指针数组的指针的指针。

返回值

S_OK

已成功返回属性名称。

MAPI_E_NO_SUPPORT

对象不支持命名属性。

MAPI_W_ERRORS_RETURNED

调用总体成功，但无法返回一个或多个属性的名称。失败属性的属性标记具有 PT_ERROR的属性类型。返回此警告时，应将调用处理为成功。若要测试此警告，请使用 HR_FAILED 宏。有关详细信息，请参阅使用宏进行错误处理。

MAPI_E_INVALID_PARAMETER

lppPropTags 指向的属性标记数组中一个或多个条目的 cValues 成员设置为 0。

备注

虽然对大多数属性的访问是通过属性标识符访问的，但某些属性可以按名称进行访问。可以调用 IMAPIProp：：GetNamesFromIDs 方法执行以下操作：

检索特定属性集中特定属性标识符的名称。
检索任何属性集中特定属性标识符的名称。
检索对象映射中包含的所有命名属性的名称。

如果 lppPropTags 指向具有一个或多个属性标识符的有效属性标记数组，而 lpPropSetGuid 指向有效的属性集， 则 GetNamesFromIDs 将忽略属性集和属性类型，并返回映射到指定标识符的所有名称。

如果 lppPropTags 指向具有一个或多个属性标识符的有效属性标记数组，并且 lpPropSetGuid 为 NULL， 则 GetNamesFromIDs 将返回映射到指定标识符的所有名称。

如果指定的标识符没有名称， 则 GetNamesFromID 在lpppPropNames 中返回的结构中该标识符的位置返回 NULL，并返回MAPI_W_ERRORS_RETURNED。

如果 lpPropSetGuid 和 lppPropTags 均为 NULL， 则 GetNamesFromIDs 将分配一个新的属性标记数组，并返回对象的所有命名属性的所有名称。

如果没有要返回的名称，可能是因为请求的属性集中没有属性，或者所有属性都是标志排除的类型， GetNamesFromIDs 将执行以下操作：

返回S_OK。
分配新的 SPropTagArray 结构，并将 cValues 成员设置为 0。
将 lpcPropNames 的内容设置为 0。
将 lpppPropNames 的内容设置为 NULL。

针对实现者的说明

如果 lpPropSetGuid 指向有效的属性集，并且 lppPropTags 为 NULL，则结果为未定义。可以使用以下策略之一：

忽略属性集，并返回属性标记数组中标识符的名称。
仅返回属于指定属性集的属性标记数组中标识符的名称。
调用失败，返回MAPI_E_INVALID_PARAMETER。

给调用方的说明

若要检索对象的所有命名属性，必须首先调用对象的 IMAPIProp：：GetPropList 方法，然后将0x8000范围以上的返回标识符传递给 GetNamesFromID。

如果传递有效的属性集，但未传递有效的属性标记数组，请准备好应对不可预知的结果。 GetNamesFromID 的某些实现忽略属性集，并返回属性标记数组中标识符的名称。某些实现返回MAPI_E_INVALID_PARAMETER。其他实现返回属性集中所有属性的标识符的名称。如果属性集PS_PUBLIC_STRINGS， 则 GetNamesFromIDs 可以返回曾经创建过的所有名称。服务提供程序是否将属性存储在与公共字符串关联的标识符下是无关紧要的。

完成属性名称后，检查 lpcPropNames 参数的内容，以确定是否返回了任何名称。如果是这样，请在返回成功结果时调用 MAPIFreeBuffer 函数以释放 lppPropTags 和 lpppPropNames 指向的 内存。对 MAPIFreeBuffer 进行一次调用就足以满足每个参数的需求;无需遍历指针数组并单独释放每个 MAPINAMEID 结构。

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

MFCMAPI 引用

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

文件	函数	Comment
SingleMAPIPropListCtrl.cpp	CSingleMAPIPropListCtrl：：FindAllNamedProps	MFCMAPI 使用 IMAPIProp：：GetNamesFromIDs 方法查找以前已映射的命名属性。