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

Статья
08/08/2023

[Предупреждение: 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 и описан в Windows SDK в REGSAM. Битовая маска не должна указывать GENERIC_WRITE, KEY_CREATE_SUB_KEY или WRITE_DAC доступа. (Хотя драйвер не может указать KEY_CREATE_SUB_KEY, его вызов RetrieveDevicePropertyStore может создать подраздел.)

[in] SubkeyPath

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

[out] PropertyStore

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

[out] Disposition

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

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

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

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

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

Драйвер может вызвать RetrieveDevicePropertyStore , чтобы получить доступ к программному ключу драйвера, аппаратному ключу текущего устройства, ключам для интерфейсов устройств, поддерживаемых текущим устройством, или ключу 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 (включая Wudfddi.h)
DLL	WUDFx.dll

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

IWDFDevice::RetrieveDevicePropertyStore

IWDFDeviceInitialize::RetrieveDevicePropertyStore

IWDFPropertyStoreFactory