Export (0) Print
Expand All

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.

Syntax


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

Parameters

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]

Type: REFIID

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

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

Minimum supported client

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

Minimum supported server

Windows Server 2003 with SP1 [desktop apps only]

Redistributable

Windows Desktop Search (WDS) 3.0

Header

Propsys.h

Library

Propsys.lib

DLL

Propsys.dll (version 6.0 or later)

See also

PSCreateSimplePropertyChange

 

 

Community Additions

ADD
Show:
© 2014 Microsoft