PSCreatePropertyChangeArray function

Creates a container for a set of IPropertyChange objects. This container can be used with IFileOperation to apply a set of property changes to a set of files.


HRESULT PSCreatePropertyChangeArray(
  _In_opt_ const PROPERTYKEY *rgpropkey,
  _In_opt_ const PKA_FLAGS   *rgflags,
  _In_opt_ const PROPVARIANT *rgpropvar,
  _In_           UINT        cChanges,
  _In_           REFIID      riid,
  _Out_          void        **ppv


rgpropkey [in, optional]

Type: const PROPERTYKEY*

Pointer to an array of PROPERTYKEY structures that name the specific properties whose changes are being stored. If this value is NULL, cChanges must be 0.

rgflags [in, optional]

Type: const PKA_FLAGS*

Pointer to an array of PKA_FLAGS values. If this value is NULL, cChanges must be 0.

rgpropvar [in, optional]

Type: const PROPVARIANT*

Pointer to an array of PROPVARIANT structures. If this value is NULL, cChanges must be 0.

cChanges [in]

Type: UINT

Count of changes to be applied. This is the number of elements in each of the arrays rgpropkey, rgflags, and rgpropvar.

riid [in]


Reference to the ID of the requested interface.

ppv [out]

Type: void**

When this function returns, contains the interface pointer requested in riid. This is typically IPropertyChangeArray.

Return value


If this function succeeds, it returns S_OK. Otherwise, it returns an HRESULT error code.


This function creates a Component Object Model (COM) object that implements IPropertyChangeArray. This object is a container for a set of IPropertyChange interfaces and can be used with IFileOperation to apply a set of property changes to a set of files.

You must initialize COM with CoInitialize or OleInitialize before you call PSCreatePropertyChangeArray. COM must remain initialized for the lifetime of this object. The property change array executes in a single-threaded apartment (STA).

A property change array can be initialized either by specifying simple changes by using the parameters, or by using various IPropertyChangeArray methods to insert or append additional changes.

The parameters are tied together by their index value. For instance, for property rgpropkey[0], the new value rgpropvar[0] is applied as specified by rgflags[0]. The cChanges parameter states how many of these sets there are. Therefore, the number of elements in each array should be the same: ARRAYSIZE(rgpropkey) = ARRAYSIZE(rgflags) = ARRAYSIZE(rgpropvar) = cChanges.

IFileOperation applies all changes in the property change array to a file simultaneously to avoid opening the file multiple times.


The following example, to be included as part of a larger program, demonstrates how to use PSCreatePropertyChangeArray to set the Comment property to "Fun" and Rating to 4 on one or more files.

// 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();
    ClearPropVariantArray(rgpropvar, ARRAYSIZE(rgpropvar));


Minimum supported client

Windows XP with SP2, Windows Vista [desktop apps only]

Minimum supported server

Windows Server 2003 with SP1 [desktop apps only]


Windows Desktop Search (WDS) 3.0






Propsys.dll (version 6.0 or later)

See also