Função PSCreatePropertyChangeArray (propsys.h)

Cria um contêiner para um conjunto de objetos IPropertyChange . Esse contêiner pode ser usado com IFileOperation para aplicar um conjunto de alterações de propriedade a um conjunto de arquivos.

Sintaxe

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

Parâmetros

[in, optional] rgpropkey

Tipo: const PROPERTYKEY*

Ponteiro para uma matriz de estruturas PROPERTYKEY que nomeia as propriedades específicas cujas alterações estão sendo armazenadas. Se esse valor for NULL, cChanges deverá ser 0.

[in, optional] rgflags

Tipo: const PKA_FLAGS*

Ponteiro para uma matriz de valores PKA_FLAGS . Se esse valor for NULL, cChanges deverá ser 0.

[in, optional] rgpropvar

Tipo: const PROPVARIANT*

Ponteiro para uma matriz de estruturas PROPVARIANT . Se esse valor for NULL, cChanges deverá ser 0.

[in] cChanges

Tipo: UINT

Contagem de alterações a serem aplicadas. Esse é o número de elementos em cada uma das matrizes rgpropkey, rgflags e rgpropvar.

[in] riid

Tipo: REFIID

Referência à ID da interface solicitada.

[out] ppv

Tipo: void**

Quando essa função retorna, contém o ponteiro de interface solicitado em riid. Normalmente, isso é IPropertyChangeArray.

Retornar valor

Tipo: HRESULT

Se essa função for bem-sucedida, ela retornará S_OK. Caso contrário, ele retornará um código de erro HRESULT.

Comentários

Essa função cria um objeto COM (Component Object Model) que implementa IPropertyChangeArray. Esse objeto é um contêiner para um conjunto de interfaces IPropertyChange e pode ser usado com IFileOperation para aplicar um conjunto de alterações de propriedade a um conjunto de arquivos.

Você deve inicializar COM com CoInitialize ou OleInitialize antes de chamar PSCreatePropertyChangeArray. O COM deve permanecer inicializado durante o tempo de vida deste objeto. A matriz de alteração de propriedade é executada em um STA (apartamento de thread único).

Uma matriz de alteração de propriedade pode ser inicializada especificando alterações simples usando os parâmetros ou usando vários métodos IPropertyChangeArray para inserir ou acrescentar alterações adicionais.

Os parâmetros são vinculados por seu valor de índice. Por exemplo, para a propriedade rgpropkey[0], o novo valor rgpropvar[0] é aplicado conforme especificado por rgflags[0]. O parâmetro cChanges indica quantos desses conjuntos existem. Portanto, o número de elementos em cada matriz deve ser o mesmo: ARRAYSIZE(rgpropkey) = ARRAYSIZE(rgflags) = ARRAYSIZE(rgpropvar) = cChanges.

IFileOperation aplica todas as alterações na matriz de alteração de propriedade a um arquivo simultaneamente para evitar abrir o arquivo várias vezes.

Exemplos

O exemplo a seguir, a ser incluído como parte de um programa maior, demonstra como usar PSCreatePropertyChangeArray para definir a propriedade Comment como "Fun" e Rating como 4 em um ou mais arquivos.

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

Requisitos

Confira também

PSCreateSimplePropertyChange