PSCreatePropertyChangeArray 函数 (propsys.h)

为一组 IPropertyChange 对象创建容器。 此容器可以与 IFileOperation 一起使用，以将一组属性更改应用于一组文件。

语法

PSSTDAPI PSCreatePropertyChangeArray(
  [in, optional] const PROPERTYKEY *rgpropkey,
  [in, optional] const PKA_FLAGS   *rgflags,
  [in, optional] const PROPVARIANT *rgpropvar,
  [in]           UINT              cChanges,
  [in]           REFIID            riid,
  [out]          void              **ppv
);

参数

[in, optional] rgpropkey

类型： const PROPERTYKEY*

指向 PROPERTYKEY 结构的数组的指针，这些结构命名要存储其更改的特定属性。 如果此值为 NULL， 则 cChanges 必须为 0。

[in, optional] rgflags

类型： const PKA_FLAGS*

指向PKA_FLAGS值数组 的 指针。 如果此值为 NULL， 则 cChanges 必须为 0。

[in, optional] rgpropvar

类型： const PROPVARIANT*

指向 PROPVARIANT 结构数组的指针。 如果此值为 NULL， 则 cChanges 必须为 0。

[in] cChanges

类型： UINT

要应用的更改计数。 这是每个数组 rgpropkey、 rgflags 和 rgpropvar 中的元素数。

[in] riid

类型： REFIID

对所请求接口 ID 的引用。

[out] ppv

类型： void**

当此函数返回时，包含 riid 中请求的接口指针。 这通常是 IPropertyChangeArray。

返回值

类型： HRESULT

如果此函数成功，则返回 S_OK。 否则，将返回 HRESULT 错误代码。

注解

此函数 (实现 IPropertyChangeArray 的 COM) 对象创建组件对象模型。 此对象是一组 IPropertyChange 接口的容器，可与 IFileOperation 一起使用，以将一组属性更改应用于一组文件。

在调用 PSCreatePropertyChangeArray 之前，必须使用 CoInitialize 或 OleInitialize 初始化 COM。 COM 必须在此对象的生存期内保持初始化状态。 属性更改数组在单线程单元中执行， (STA) 。

可以通过使用参数指定简单更改或使用各种 IPropertyChangeArray 方法来插入或追加其他更改来初始化属性更改数组。

参数按索引值绑定在一起。 例如，对于属性 rgpropkey[0]，按 rgflags[0] 指定应用新值 rgpropvar[0]。 cChanges 参数指出存在多少个这些集。 因此，每个数组中的元素数应相同：ARRAYSIZE (rgpropkey) = ARRAYSIZE (rgflags) = ARRAYSIZE (rgpropvar) = cChanges。

IFileOperation 同时将属性更改数组中的所有更改应用于文件，以避免多次打开该文件。

示例

以下示例将作为较大程序的一部分包含在内，演示如何使用 PSCreatePropertyChangeArray 对一个或多个文件将 Comment 属性设置为“Fun”， 并将 Rating 设置为 4。

// IFileOperation *pfo;
// Assume variable pfo has been initialized by calling SetOperationFlags, 
// ApplyPropertiesToItems, and SetProgressMessage as appropriate.
 
PROPVARIANT rgpropvar[2] = {0};

HRESULT hr = InitPropVariantFromString(L"Fun", &rgpropvar[0]);

if (SUCCEEDED(hr))
{
    hr = InitPropVariantFromUInt32(RATING_FOUR_STARS_SET, &rgpropvar[1]);

    if (SUCCEEDED(hr))
    {
        REFPROPERTYKEY rgkey[2] = {PKEY_Comment, PKEY_Rating};
        PKA_FLAGS rgflags[2] = {PKA_SET, PKA_SET};
        IPropertyChangeArray *pChangeArray;

        hr = PSCreatePropertyChangeArray(rgkey, rgflags, rgpropvar, 2, IID_PPV_ARGS(&pChangeArray));

        if (SUCCEEDED(hr))
        {
            hr = pfo->SetProperties(pChangeArray);

            if (SUCCEEDED(hr))
            {
                hr = pfo->PerformOperations();
            }
            pChangeArray->Release();
        }
    }
    ClearPropVariantArray(rgpropvar, ARRAYSIZE(rgpropvar));
}

要求

要求	值
最低受支持的客户端	Windows XP SP2、Windows Vista [仅限桌面应用]
最低受支持的服务器	Windows Server 2003 SP1 [仅限桌面应用]
目标平台	Windows
标头	propsys.h
Library	Propsys.lib
DLL	Propsys.dll (6.0 或更高版本)
可再发行组件	Windows 桌面搜索 (WDS) 3.0

另请参阅

PSCreateSimplePropertyChange