IMAPIProp::GetProps

项目
04/04/2023

适用于：Outlook 2013 | Outlook 2016

检索对象的一个或多个属性的属性值。

HRESULT GetProps(
  LPSPropTagArray lpPropTagArray,
  ULONG ulFlags,
  ULONG FAR * lpcValues,
  LPSPropValue FAR * lppPropArray
);

参数

lpPropTagArray

[in]指向属性标记数组的指针，这些标记标识要检索其值的属性。 lpPropTagArray 参数必须为 NULL，指示应返回对象的所有属性的值，或指向包含一个或多个属性标记的 SPropTagArray 结构。

ulFlags

[in]标志的位掩码，指示类型为PT_UNSPECIFIED的属性的格式。可以设置以下标志：

MAPI_UNICODE

应以 Unicode 格式返回这些属性的字符串值。如果未设置MAPI_UNICODE标志，则应以 ANSI 格式返回字符串值。

lpcValues

[out]指向 lppPropArray 参数指向的属性值计数的指针。如果 lppPropArray 为 NULL，则 lpcValues 参数的内容为零。

lppPropArray

[out]指向指向检索的属性值的指针的指针。

返回值

S_OK

已成功检索属性值。

MAPI_W_ERRORS_RETURNED

调用总体成功，但无法访问一个或多个属性。每个不可用属性的属性值的 aulPropTag 成员具有PT_ERROR属性类型，标识符为零。返回此警告时，应将调用处理为成功。若要测试此警告，请使用 HR_FAILED 宏。有关详细信息，请参阅使用宏进行错误处理。

MAPI_E_INVALID_PARAMETER

在 lpPropTagArray 指向的 SPropTagArray 结构的 cValues 成员中传递了零。

备注

IMAPIProp：：GetProps 方法获取对象的一个或多个属性的属性值。

属性值的返回顺序与请求的顺序相同 (也就是说， lpPropTagArray 指向的属性标记数组中的属性顺序与 lppPropArray) 指向的属性值结构数组中的顺序匹配。

属性标记数组的 aulPropTag 成员中指定的属性类型指示应在每个属性值结构的 Value 成员中返回的值的类型。但是，如果调用方不知道属性的类型，则可以将 aulPropTag 成员中的类型改为PT_UNSPECIFIED。在检索值时， GetProps 在属性的属性值结构的 aulPropTag 成员中设置正确的类型。

如果在 lpPropTagArray 的 SPropTagArray 中指定了属性类型，则 lppPropArray 中返回的 SPropValue 中的属性值具有与请求的类型完全匹配的类型，除非改为返回错误值。

字符串属性可以有两种属性类型之一：PT_UNICODE表示 Unicode 格式，PT_STRING8表示 ANSI 格式。如果在 ulFlags 参数中设置了 MAPI_UNICODE 标志，则每当 GetProps 无法确定字符串属性的相应格式时，它将返回 Unicode 格式的值。在以下情况下，GetProps 无法确定确切的字符串属性类型：

lpPropTagArray 参数设置为 NULL 以请求所有属性。
aulPropTag 成员将值PT_UNSPECIFIED作为其属性类型包含在属性标记数组中。

如果 lpPropTagArray 参数设置为 NULL 以检索对象的所有属性且不存在任何属性， 则 GetProps 将执行以下操作：

返回S_OK。
将属性值结构的 cValues 成员中的计数值设置为 0。
将 lpcValues 的内容设置为 0。
将 lppPropArray 设置为 NULL。

GetProps 不得返回 cValues 设置为 0 的多值属性。

针对实现者的说明

调用 MAPIAllocateBuffer 函数，最初为 lpPropTagArray 指向的 SPropValue 结构分配内存;调用 MAPIAllocateMore 以分配结构成员所需的任何其他内存。

如果无法检索一个或多个请求的属性的值，则返回MAPI_W_ERRORS_RETURNED。在属性值结构中，将 aulPropTag 成员中的类型设置为 PT_ERROR， 将 Value 成员设置为描述错误的状态代码。例如，如果必须将字符串转换为 Unicode 且不支持 Unicode，请将 Value 成员设置为 MAPI_E_BAD_CHARWIDTH。如果属性太大，请将其设置为 MAPI_E_NOT_ENOUGH_MEMORY。如果对象不支持属性，请将其设置为 MAPI_E_NOT_FOUND。

远程传输提供程序的 GetProps 方法实现必须返回调用方请求的属性的文件夹属性值。实现必须执行以下操作：

分配属性值数组以返回到调用方，并将其地址存储在为此传入的属性值指针参数中。
根据传递给 GetProps 的属性标记数组，将文件夹的属性标记复制到属性值数组中的属性标记中。
确保为传递给 GetProps 的所有属性标记设置属性类型。调用方可以传入 PT_UNSPECIFIED 的属性类型，在这种情况下 ，GetProps 必须为该属性标记设置正确的属性类型。
根据属性值数组的标记设置属性值数组中每个属性的值。例如，如果调用方请求的属性标记 PR_OBJECT_TYPE (PidTagObjectType) ， 则 GetProps 可以将值设置为MAPI_FOLDER。
如果调用方传入了你的实现未处理的任何属性标记，则可以将属性标记设置为这些属性PT_ERROR，并将属性值设置为MAPI_E_NOT_FOUND。
如果未发生错误，则返回S_OK;如果发生错误，则返回MAPI_W_ERRORS_RETURNED。

远程传输提供程序的 GetProps 方法实现必须至少支持以下属性：

PR_ACCESS (PidTagAccess)
PR_ACCESS_LEVEL (PidTagAccessLevel)
PR_ASSOC_CONTENT_COUNT (PidTagAssociatedContentCount)
PR_CONTENT_COUNT (PidTagContentCount)
PR_CREATION_TIME (PidTagCreationTime)
PR_DISPLAY_NAME (PidTagDisplayName)
PR_DISPLAY_TYPE (PidTagDisplayType)
PR_FOLDER_TYPE (PidTagFolderType)
PR_OBJECT_TYPE
PR_SUBFOLDERS (PidTagSubfolders)

给调用方的说明

对于类型为 PT_OBJECT 的属性，请调用 IMAPIProp：：OpenProperty 方法，而不是 GetProps。

对于安全属性，不要期望通过调用将 lppPropTagArray 参数设置为 NULL 的 GetProps 来检索它们。调用 GetProps 时，必须在其属性标记数组的 aulPropTag 成员中显式设置安全 属性的标识符。何时以及如何提供安全属性由服务提供商决定。

仅当 GetProps 返回S_OK或MAPI_W_ERRORS_RETURNED时，才通过调用 MAPIFreeBuffer 函数来释放返回的 SPropValue 结构。

如果 GetProps 返回MAPI_W_ERRORS_RETURNED，因为它无法访问一个或多个属性，检查返回的属性标记。失败的属性将在其属性值结构中设置以下值：

aulPropTag 成员中的属性类型设置为 PT_ERROR。
Value 成员中的属性值设置为错误的状态代码，例如MAPI_E_NOT_FOUND。

如果属性因太大而无法方便地在属性值结构中返回，则其 Value 成员设置为MAPI_E_NOT_ENOUGH_MEMORY。通常，当属性的值为 4 KB 或更大时，PT_STRING8、PT_UNICODE或PT_BINARY类型的字符串或二进制属性会出现这种情况。调用 IMAPIProp：：OpenProperty 以检索大型属性。

并非所有 GetProps 实现都支持字符串的 Unicode 和 ANSI 格式。当特定属性需要字符串格式转换并且 GetProps 不支持它时，该属性的 Value 成员将设置为 MAPI_E_BAD_CHARWIDTH。

若要检查 PST 是否为 SharePoint PST，请使用 IMAPISession：：OpenMsgStore 装载 PST，然后在请求此属性的消息存储对象上调用 GetProps。如果存在，可以假定已为 SharePoint 配置 PST;如果不是，则 PST 尚未配置为 SharePoint PST。

有关如何使用 GetProps 访问属性的详细信息，请参阅检索 MAPI 属性。

MFCMAPI 引用

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

文件	函数	Comment
MAPIFunctions.cpp	GetPropsNULL	MFCMAPI 使用 IMAPIPropProp：：GetProps 方法在 lpPropTagArray 参数中传递 NULL 或 IMAPIPropProp：：GetPropList 方法返回的数组来获取对象的所有属性。