PSCreateMultiplexPropertyStore function (propsys.h)

Article
10/13/2021

Creates a read-only property store that contains multiple property stores, each of which must support either IPropertyStore or IPropertySetStorage.

Syntax

PSSTDAPI PSCreateMultiplexPropertyStore(
  [in]  IUnknown **prgpunkStores,
  [in]  DWORD    cStores,
  [in]  REFIID   riid,
  [out] void     **ppv
);

Parameters

[in] prgpunkStores

Type: IUnknown**

Address of a pointer to an array of property stores that implement either IPropertyStore or IPropertySetStorage.

[in] cStores

Type: DWORD

The number of elements in the array referenced in prgpunkStores.

[in] riid

Type: REFIID

Reference to the requested IID.

[out] ppv

Type: void**

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

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 IPropertyStore, INamedPropertyStore, IObjectProvider, and IPropertyStoreCapabilities. The multiplex property store object aggregates the properties exposed from multiple property stores.

This object can be useful for aggregating the properties from multiple existing property store implementations in a Shell namespace extension, or for reusing an existing property store and providing additional read-only properties.

Applications must call this object from only one thread at a time.

You must initialize COM with CoInitialize or OleInitialize before you call PSCreateDelayedMultiplexPropertyStore. COM must remain initialized for the lifetime of this object.

Each of the objects in the array prgpunkStores must implement either IPropertyStore or IPropertySetStorage. If an object implements IPropertySetStorage, it is wrapped using PSCreatePropertyStoreFromPropertySetStorage for use in the multiplex property store.

The multiplex property store implementation of IPropertyStore::GetValue asks each of the provided property stores for the value. The multiplex property store stops searching when one of the property stores returns a success code and a non-VT_EMPTY value. Failure codes cause the search to end and are passed back to the calling application.

The multiplex property store implementation of IPropertyStoreCapabilities::IsPropertyWritable delegates the call to the first store that implements IPropertyStoreCapabilities. If multiple stores implement IPropertyStoreCapabilities, the subsequent ones are ignored. If no store implements IPropertyStoreCapabilities, this method returns S_OK.

Examples

The following example, to be included as part of a larger program, demonstrates how to use PSCreateMultiplexPropertyStore in an implementation of IPropertyStoreFactory::GetPropertyStore.

// CMyFactory is a reference counted COM object that implements 
// both IPropertyStoreFactory.

// CMyFactory is assumed to be fully implemented, but for the sake of brevity, 
// many functions are not shown here.

// Private functions are prefixed with an underscore.
 
// CMyFactory implementation for IPropertyStoreFactory::GetPropertyStore.
HRESULT CMyFactory::GetPropertyStore(__in GETPROPERTYSTOREFLAGS flags,
                                     __in_opt IUnknown *pUnkFactory,
                                     __in REFIID riid,
                                     __deref_out void **ppv)
{
    *ppv = NULL;
    HRESULT hr;
 
    // This application creates only read-only stores.
    if (flags & GPS_READWRITE)
    {
        hr = STG_E_ACCESSDENIED;
    }
    else
    {
        // More advanced applications would check other GETPROPERTYSTOREFLAGS 
        // flags and respond appropriately.
 
        // CMyFactory multiplexes two property stores.
        IPropertyStore *ppsFirst;
        
        hr = _CreateFirstStore(IID_PPV_ARGS(&ppsFirst));
        
        if (SUCCEEDED(hr))
        {
            IPropertyStore *ppsSecond;
            
            hr = _CreateSecondStore(IID_PPV_ARGS(&ppsSecond));
            
            if (SUCCEEDED(hr))
            {
                IUnknown *rgStores[] = {ppsFirst, ppsSecond};
            
                hr = PSCreateMultiplexPropertyStore(rgStores, ARRAYSIZE(rgStores), riid, ppv);
            
                ppsSecond->Release();
            }
            ppsFirst->Release();
        }
    }
    return hr;
}

Requirements

Requirement	Value
Minimum supported client	Windows XP with SP2, Windows Vista [desktop apps only]
Minimum supported server	Windows Server 2003 with SP1 [desktop apps only]
Target Platform	Windows
Header	propsys.h
Library	Propsys.lib
DLL	Propsys.dll (version 6.0 or later)
Redistributable	Windows Desktop Search (WDS) 3.0

Share via