PSCreatePropertyChangeArray function (propsys.h)

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.

Syntax

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
);

Parameters

[in, optional] rgpropkey

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.

[in, optional] rgflags

Type: const PKA_FLAGS*

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

[in, optional] rgpropvar

Type: const PROPVARIANT*

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

[in] cChanges

Type: UINT

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

[in] riid

Type: REFIID

Reference to the ID of the requested interface.

[out] ppv

Type: void**

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

Return value

Type: HRESULT

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

Remarks

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.

Examples

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();
            }
            pChangeArray->Release();
        }
    }
    ClearPropVariantArray(rgpropvar, ARRAYSIZE(rgpropvar));
}

Requirements

See also

PSCreateSimplePropertyChange