IMAPIProp::GetProps

适用于: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 成员中设置正确的类型。

如果属性类型在 lpPropTagArraySPropTagArray 中指定,则 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 方法必须至少支持以下属性:

给调用方的说明

对于PT_OBJECT类型的属性,请调用 IMAPIProp::OpenProperty 方法而不是 GetProps

对于安全属性,不要期望通过调用 GetProps将 lppPropTagArray 参数设置为 NULL)来检索它们。 调用 GetProps 时,必须在其属性标记数组的 aulPropTag 成员中显式设置安全属性的标识符。 安全属性的可用时间和方式由服务提供程序决定。

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

如果 GetProps 由于无法访问一个或多个属性而返回MAPI_W_ERRORS_RETURNED,请检查返回的属性的属性标记。 失败的属性在其属性值结构中设置以下值:

  • aulPropTag 成员中设置为PT_ERROR的属性类型。

  • 成员中的属性值设置为错误的状态代码,例如MAPI_E_NOT_FOUND。

由于属性值结构中太大而无法方便地返回的属性会将其 成员设置为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。 如果存在,可以假定 PST 已配置为SharePoint;如果没有,则 PST 尚未配置为 SharePoint PST。

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

MFCMAPI 引用

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

文件 函数 备注
MAPIFunctions.cpp
GetPropsNULL
MFCMAPI 使用 IMAPIProp::GetProps 方法通过传递 NULL 或 lpPropTagArray 参数中的 IMAPIProp::GetPropList 方法返回的数组来获取对象的所有属性。

另请参阅

IMAPIProp::GetPropList

IMAPIProp::OpenProperty

MAPIAllocateBuffer

MAPIAllocateMore

MAPIFreeBuffer

SPropTagArray

SPropValue

IMAPIProp : IUnknown

MFCMAPI 代码示例

检索 MAPI 属性

使用宏进行错误处理