Функция PSCreateDelayedMultiplexPropertyStore (propsys.h)

Статья
08/25/2023

Создает хранилище свойств с отложенной привязкой только для чтения, которое содержит несколько хранилищ свойств.

Синтаксис

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

Параметры

flags

Тип: GETPROPERTYSTOREFLAGS

Одно или несколько значений GETPROPERTYSTOREFLAGS . Эти значения указывают сведения о созданном объекте хранилища свойств.

pdpsf

Тип: IDelayedPropertyStoreFactory*

Указатель интерфейса на экземпляр IDelayedPropertyStoreFactory.

[in] rgStoreIds

Тип: const DWORD*

Указатель на массив идентификаторов хранилищ свойств. Этот массив не требуется инициализировать.

[in] cStores

Тип: DWORD

Количество элементов в массиве, на который указывает rgStoreIds.

[in] riid

Тип: REFIID

Ссылка на запрошенный ИДЕНТИФИКАТОР интерфейса, который будет представлять созданное хранилище свойств.

[out] ppv

Тип: void**

При возврате этой функции содержит указатель интерфейса, запрошенный в riid. Обычно это IPropertyStore.

Возвращаемое значение

Тип: HRESULT

Если эта функция выполняется успешно, она возвращает S_OK. В противном случае возвращается код ошибки HRESULT .

Перед вызовом PSCreateDelayedMultiplexPropertyStore необходимо инициализировать COM с помощью CoInitialize или OleInitialize. COM должен оставаться инициализированным в течение времени существования этого объекта.

PSCreateDelayedMultiplexPropertyStore разработан в качестве альтернативы PSCreateMultiplexPropertyStore, который требует инициализации массива хранилищ свойств перед созданием хранилища свойств мультиплекса.

Механизм отложенной привязки разработан как повышение производительности для вызовов IPropertyStore::GetValue в хранилище свойств мультиплекса. При запросе значения свойства отложенное хранилище свойств мультиплекса проверяет каждое из хранилищ свойств на наличие значения. После обнаружения значения нет необходимости создавать и инициализировать последующие хранилища. Отложенное хранилище свойств мультиплекса прекращает поиск значения, когда одно из хранилищ свойств возвращает код успешного выполнения и не VT_EMPTY значение.

Когда отложенному хранилищу свойств мультиплекса требуется доступ к определенному хранилищу свойств, сначала проверяется, получено ли уже интерфейс для этого хранилища свойств. В противном случае он вызывает IDelayedPropertyStoreFactory::GetDelayedPropertyStore с соответствующим идентификатором хранилища свойств для получения хранилища свойств. Он всегда использует идентификаторы хранилища свойств в порядке, в котором они предоставляются приложением. Возможно, будут использоваться не все идентификаторы.

Если вызов IDelayedPropertyStoreFactory завершается сбоем с E_NOTIMPL или E_ACCESSDENIED для определенного идентификатора хранилища свойств или если приложение указало GPS_BESTEFFORT, сбой игнорируется и отложенное хранилище свойств мультиплекса перемещается в следующее хранилище свойств.

В некоторых случаях может быть полезно использовать PSCreateDelayedMultiplexPropertyStore вместо PSCreateMultiplexPropertyStore. Например, если приложению требуется мультиплексировать два хранилища свойств, а первое хранилище свойств не требует большого объема памяти для инициализации и предоставляет PKEY_Size сведения. Часто вызывающие приложения запрашивают хранилище свойств мультиплекса, а затем запрашивают только PKEY_Size перед освобождением объекта. В этом случае приложение может избежать затрат на инициализацию второго хранилища свойств, вызвав PSCreateDelayedMultiplexPropertyStore и реализовав IDelayedPropertyStoreFactory.

Примеры

В следующем примере, который будет включен в состав более крупной программы, показано, как использовать PSCreateDelayedMultiplexPropertyStore в реализации 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;
}

Требования

Требование	Значение
Минимальная версия клиента	Windows XP с пакетом обновления 2 (SP2), Windows Vista [только классические приложения]
Минимальная версия сервера	Windows Server 2003 с пакетом обновления 1 (SP1) [только классические приложения]
Целевая платформа	Windows
Header	propsys.h
Библиотека	Propsys.lib
DLL	Propsys.dll (версия 6.0 или более поздняя)
Распространяемые компоненты	Windows Desktop Search (WDS) 3.0

См. также раздел

IPropertyStoreFactory

PSCreateMultiplexPropertyStore

Поделиться через