IPerPropertyBrowsing：：GetPredefinedStrings 方法 (ocidl.h)

  • 项目

检索指定属性可以接受的允许值的数组说明字符串。

语法

HRESULT GetPredefinedStrings(
  [in]  DISPID     dispID,
  [out] CALPOLESTR *pCaStringsOut,
  [out] CADWORD    *pCaCookiesOut
);

参数

[in] dispID

属性的调度标识符。

[out] pCaStringsOut

指向调用方分配的计数数组结构的指针，该结构包含字符串指针的方法分配数组的元素计数和地址。 此方法还为包含预定义名称的字符串值分配内存，并将字符串指针存储在 数组中。 如果方法失败，则不分配内存，并且结构的内容未定义。

[out] pCaCookiesOut

指向调用方分配的计数数组结构的指针，该结构包含 DWORD 值的方法分配数组的元素计数和地址。 数组中的值可以传递给 IPerPropertyBrowsing：：GetPredefinedValue ，以检索 与 pCaStringsOut 内同一数组位置中的名称关联的值。 如果方法失败，则不分配内存，并且结构的内容未定义。

返回值

此方法可以返回标准返回值E_INVALIDARG、E_OUTOFMEMORY和E_UNEXPECTED，以及以下值。

返回代码 说明
S_OK
 该方法已成功完成。
E_NOTIMPL
 此方法未实现，并且不支持预定义的名称。
E_POINTER
 pCaStringsOut 或 pCaCookiesOut 中的地址无效。 例如，任一参数都可以为 NULL。

注解

pCaStringsOut 指向的数组中返回的每个字符串在 pCaCookiesOut 指向的计数数组中都有一个匹配标记，其中令牌可以传递给 IPerPropertyBrowsing：：GetPredefinedValue，以获取 (对应于字符串的 VARIANT) 的实际值。

使用预定义的字符串，调用方可以获取用于填充用户界面元素（如下拉列表框）的字符串列表。 当最终用户选择其中一个字符串作为要分配给属性的值时，调用方可以通过 IPerPropertyBrowsing：：GetPredefinedValue 获取相应的值。

调用方备注

传递给此方法的 CALPOLESTR 和 CADWORD 结构都是调用方分配的。 调用方负责释放 CALPOLESTR 数组和 CALPOLESTR 结构指向的每个字符串。

所有内存都与 CoTaskMemAlloc 一起分配。 调用方负责使用 CoTaskMemFree 释放字符串和数组。

从此方法返回时，调用方负责所有这些内存，并且必须在不再需要时释放它。 实现此目的的代码如下所示。

CALPOLESTR     castr; 
CWDWORD        cadw; 
ULONG          i; 
 
pIPerPropertyBrowsing->GetPredefinedStrings(dispID, &castr, &cadw); 
 
//...Use the strings and the cookies 
 
CoTaskMemFree((void *)cadw.pElems); 
 
for (i=0; i < castr.cElems; i++) 
    CoTaskMemFree((void *)castr.pElems[i]); 
 
CoTaskMemFree((void *)castr.pElems);

实施者说明

不需要支持预定义的名称和值。 如果对象不支持这些名称，请从此方法返回E_NOTIMPL。 如果未实现此方法，则 IPerPropertyBrowsing：：GetPredefinedValue 也不得实现。

此方法填充 CADWORD 和 CALPOLESTR 结构的 cElems 和 pElems 成员。 它使用 CoTaskMemAlloc 分配这些结构指向的数组，并填充这些数组。 在 CALPOLESTR 情况下，此方法还会使用 CoTaskMemAlloc 分配每个字符串，并将每个字符串指针存储在数组中。

要求

要求 值
最低受支持的客户端 Windows 2000 Professional [仅限桌面应用]
最低受支持的服务器 Windows 2000 Server [仅限桌面应用]
目标平台 Windows
标头 ocidl.h

另请参阅

CADWORD

CALPOLESTR

IPerPropertyBrowsing