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

所要求介面標識碼的參考。

[out] ppv

類型： void**

當此函式傳回時，包含 riid中要求的介面指標。 這通常是 IPropertyChangeArray。

傳回值

類型： HRESULT

如果此函式成功，則會傳回 S_OK。 否則，它會傳回 HRESULT 錯誤碼。

備註

此函式會在實作 IPropertyChangeArray 的 COM) 物件建立元件物件 (模型。 這個對像是一組 IPropertyChange 介面的容器，可與 IFileOperation 搭配使用，將一組屬性變更套用至一組檔案。

您必須先使用 CoInitialize 或 OleInitialize 初始化 COM，才能呼叫 PSCreatePropertyChangeArray。 COM 必須在這個物件的存留期內保持初始化狀態。 屬性變更陣列會在單一線程 Apartment 中執行， (STA) 。

屬性變更數位可以藉由使用 參數來指定簡單的變更，或使用各種 IPropertyChangeArray 方法來插入或附加其他變更來初始化。

參數會依其索引值系結在一起。 例如，針對屬性 rgpropkey[0]，新的值 rgpropvar[0] 會套用為 rgflags[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
程式庫	Propsys.lib
Dll	Propsys.dll (6.0 版或更新版本)
可轉散發套件	Windows 桌面搜尋 (WDS) 3.0

另請參閱

PSCreateSimplePropertyChange