Метод IWDFPropertyStoreFactory::RetrieveDevicePropertyStore (wudfddi.h)

Статья
02/07/2025

[ предупреждение: UMDF 2 является последней версией UMDF и заменяет UMDF 1. Все новые драйверы UMDF должны быть написаны с помощью UMDF 2. Новые функции не добавляются в UMDF 1, а поддержка UMDF 1 в более новых версиях Windows 10 ограничена. Универсальные драйверы Windows должны использовать UMDF 2. Дополнительные сведения см. в разделе Начало работы с UMDF.]

Метод RetrieveDevicePropertyStore извлекает интерфейс хранилища свойств, который драйверы могут использовать для доступа к реестру.

Синтаксис

HRESULT RetrieveDevicePropertyStore(
  [in]  PWDF_PROPERTY_STORE_ROOT          RootSpecifier,
  [in]  WDF_PROPERTY_STORE_RETRIEVE_FLAGS Flags,
  [in]  REGSAM                            DesiredAccess,
  [in]  PCWSTR                            SubkeyPath,
  [out] IWDFNamedPropertyStore2           **PropertyStore,
  [out] WDF_PROPERTY_STORE_DISPOSITION    *Disposition
);

Параметры

[in] RootSpecifier

Адрес выделенной драйвером структуры WDF_PROPERTY_STORE_ROOT. Драйвер заполняет эту структуру, чтобы определить хранилище свойств, которое извлекается RetrieveDevicePropertyStore.

[in] Flags

Флаг типа WDF_PROPERTY_STORE_RETRIEVE_FLAGS, указывающий, должен ли UMDF создать указанную запись реестра, если она не существует, и следует ли удалить новую запись при перезапуске Windows.

[in] DesiredAccess

Битовая маска с типом REGSAM, указывающая типы доступа к реестру, который требуется драйверу. Тип REGSAM определен в Winreg.h и описан в пакете SDK для Windows REGSAM. Битовая маска не должна указывать GENERIC_WRITE, KEY_CREATE_SUB_KEY или WRITE_DAC доступа. (Хотя драйвер не может указать KEY_CREATE_SUB_KEY, его вызов RetrieveDevicePropertyStore может создать вложенный ключ.)

[in] SubkeyPath

Указатель на указанную вызывающим символьную строку, представляющую имя подраздела, расположенного в разделе реестра, который указывает параметр RootSpecifier. Этот параметр является необязательным и может быть null. Дополнительные сведения см. в примечаниях.

[out] PropertyStore

Адрес расположения, получающего указатель на интерфейс IWDFNamedPropertyStore 2. Драйвер использует этот интерфейс для доступа к значениям в реестре.

[out] Disposition

Адрес расположения, получающего WDF_PROPERTY_STORE_DISPOSITIONтипизированное значение.

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

RetrieveDevicePropertyStore возвращает S_OK, если операция завершится успешно. В противном случае метод может вернуть одно из следующих значений:

Возвращаемый код	Описание
E_INVALIDARG	Вызывающий объект предоставил недопустимый входной аргумент.
E_OUTOFMEMORY	Не удалось выделить память.

Этот метод может возвращать одно из других значений, содержащихся в Winerror.h.

Замечания

Драйвер может вызывать GetDevicePropertyStore для получения доступа к ключу программного обеспечения драйвера, аппаратному ключу текущего устройства, ключам для интерфейсов устройств, поддерживаемых текущим устройством, или ключом DEVICEMAP.

Если указать параметр SubkeyPath, необходимо использовать уникальное имя, например имя службы драйвера. Драйвер может использовать вложенный ключ для хранения сведений, относящихся к устройству.

Дополнительные сведения об использовании RetrieveDevicePropertyStore для доступа к реестру см. в статье Использование реестра в драйверах на основе UMDF.

Примеры

В следующем примере кода извлекается значение, назначенное записи PortName в аппаратном ключе устройства.

IWDFPropertyStoreFactory *pPropertyStoreFactory = NULL;
WDF_PROPERTY_STORE_ROOT RootSpecifier;
IWDFNamedPropertyStore2 * pHardwarePropertyStore2 = NULL;
PROPVARIANT comPortPV;
WCHAR portName[] = L"PortName";
HRESULT hr;
...
//
// Get the property store factory interface.
//
hr = m_FxDevice->QueryInterface(IID_PPV_ARGS(&pPropertyStoreFactory));
if (FAILED(hr))
{
    goto Exit;
}
//
//Initialize the WDF_PROPERTY_STORE_ROOT structure. We want to open the 
// \Device Parameters subkey under the device's hardware key.
//
RtlZeroMemory(&RootSpecifier,
              sizeof(WDF_PROPERTY_STORE_ROOT));
RootSpecifier.LengthCb = sizeof(WDF_PROPERTY_STORE_ROOT);
RootSpecifier.RootClass = WdfPropertyStoreRootClassHardwareKey;
RootSpecifier.Qualifier.HardwareKey.ServiceName = WDF_PROPERTY_STORE_HARDWARE_KEY_ROOT;

//
// Get the property store interface for the hardware key of the
// device that m_FxDevice represents.
//
hr = pPropertyStoreFactory->RetrieveDevicePropertyStore(
                                           &RootSpecifier,
                                           WdfPropertyStoreNormal,
                                           KEY_QUERY_VALUE,
                                           NULL,
                                           &pHardwarePropertyStore2,
                                           NULL
                                           );
if (FAILED(hr))
{
    goto Exit;
}

//
// Get the value of the "PortName" entry, which is stored under 
// the device's \Device Parameters subkey.
//
PropVariantInit(&comPortPV);
hr = pHardwarePropertyStore2->GetNamedValue(portName,
                                            &comPortPV);
if (FAILED(hr))
{
   goto Exit;
}
...
Exit:
    SAFE_RELEASE(pHardwarePropertyStore2);
    SAFE_RELEASE(pPropertyStoreFactory);
...

Требования

Требование	Ценность
завершение поддержки	Недоступно в UMDF 2.0 и более поздних версиях.
целевая платформа	Настольный
минимальная версия UMDF	1.9
заголовка	wudfddi.h (include Wudfddi.h)
DLL	WUDFx.dll

См. также

IWDFDevice::RetrieveDevicePropertyStore

IWDFDeviceInitialize::RetrieveDevicePropertyStore

IWDFPropertyStoreFactory

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