PSCreateDelayedMultiplexPropertyStore function (propsys.h)

Creates a read-only, delayed-binding property store that contains multiple property stores.

Syntax

PSSTDAPI PSCreateDelayedMultiplexPropertyStore(
        GETPROPERTYSTOREFLAGS        flags,
        IDelayedPropertyStoreFactory *pdpsf,
  [in]  const DWORD                  *rgStoreIds,
  [in]  DWORD                        cStores,
  [in]  REFIID                       riid,
  [out] void                         **ppv
);

Parameters

flags

Type: GETPROPERTYSTOREFLAGS

One or more GETPROPERTYSTOREFLAGS values. These values specify details of the created property store object.

pdpsf

Type: IDelayedPropertyStoreFactory*

Interface pointer to an instance of IDelayedPropertyStoreFactory.

[in] rgStoreIds

Type: const DWORD*

Pointer to an array of property store IDs. This array does not need to be initialized.

[in] cStores

Type: DWORD

The number of elements in the array pointed to by rgStoreIds.

[in] riid

Type: REFIID

Reference to the requested IID of the interface that will represent the created property store.

[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.

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.

PSCreateDelayedMultiplexPropertyStore is designed as an alternative to PSCreateMultiplexPropertyStore, which requires that the array of property stores be initialized before it creates the multiplex property store.

The delayed binding mechanism is designed as a performance enhancement for calls to IPropertyStore::GetValue on a multiplex property store. When asked for the value of a property, the delayed multiplex property store checks each of the property stores for the value. After the value is found, there is no need to create and initialize subsequent stores. The delayed multiplex property store stops searching for a value when one of the property stores returns a success code and a non-VT_EMPTY value.

When the delayed multiplex property store needs to access a particular property store, it first checks to see if it has already obtained an interface to that property store. If not, it calls IDelayedPropertyStoreFactory::GetDelayedPropertyStore with the appropriate property store ID to obtain the property store. It always uses the property store IDs in the order in which they are provided by the application. It is possible that not all IDs will be used.

If the call to IDelayedPropertyStoreFactory fails with E_NOTIMPL or E_ACCESSDENIED for a particular property store ID, or if the application specified GPS_BESTEFFORT, then the failure is ignored and the delayed multiplex property store moves on to the next property store.

In some cases, it might be beneficial to use PSCreateDelayedMultiplexPropertyStore in place of PSCreateMultiplexPropertyStore. For example, if an application needs to multiplex two property stores and the first property store is not memory-intensive to initialize and provides PKEY_Size information. Often, calling applications ask for a multiplex property store and then ask for only PKEY_Size before they release the object. In such a case, the application could avoid the cost of initializing the second property store by calling PSCreateDelayedMultiplexPropertyStore and implementing IDelayedPropertyStoreFactory.

Examples

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

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

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

// Private functions are indicated with an underscore prefix.

// The hope is that the fastest property store satisfies the caller's queries 
// so that the slower property stores are never created.
 
// 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.
 
        // This application always creates its stores in-process, so it 
        // ignores the pUnkFactory value.
        
        DWORD rgStoreIds[] = {0, 1, 2};
        
        hr = PSCreateDelayedMultiplexPropertyStore(flags, this, rgStoreIds, ARRAYSIZE(rgStoreIds), riid, ppv);
    }
 
    return hr;
}
 
// CMyFactory implementation of IDelayedPropertyStoreFactory::GetDelayedPropertyStore
HRESULT CMyFactory::GetDelayedPropertyStore(GETPROPERTYSTOREFLAGS flags,
                                            DWORD dwStoreId,
                                            REFIID riid,
                                            void **ppv)
{
    *ppv = NULL;
    HRESULT hr;
    
    // Note: The IDs here match the IDs in rgStoreIds above.

    if (dwStoreId == 0)
    {
        // This store is the fastest at returning properties.

        hr = _CreateFastestPropertyStore(flags, riid, ppv);
    }
    else if (dwStoreId == 1)
    {
        // This store is slower at returning properties.
        hr = _CreateSlowerPropertyStore(flags, riid, ppv);
    }
    else if (dwStoreId == 2)
    {
        // This store is very slow at returning properties.
        hr = _CreateSlowestPropertyStore(flags, riid, ppv);
    }
    else
    {
        // This should never happen.
        hr = E_UNEXPECTED;
    }
    
    return hr;
}

Requirements

See also

IPropertyStoreFactory

PSCreateMultiplexPropertyStore