Функция WdfFdoInitQueryProperty (wdffdo.h)

Статья
08/08/2023

[Применимо к KMDF и UMDF]

Метод WdfFdoInitQueryProperty извлекает указанное свойство устройства.

Синтаксис

NTSTATUS WdfFdoInitQueryProperty(
  [in]  PWDFDEVICE_INIT          DeviceInit,
  [in]  DEVICE_REGISTRY_PROPERTY DeviceProperty,
  [in]  ULONG                    BufferLength,
  [out] PVOID                    PropertyBuffer,
  [out] PULONG                   ResultLength
);

Параметры

[in] DeviceInit

Указатель на структуру WDFDEVICE_INIT , полученную драйвером из функции обратного вызова EvtDriverDeviceAdd .

[in] DeviceProperty

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

[in] BufferLength

Размер (в байтах) буфера, на который указывает PropertyBuffer.

[out] PropertyBuffer

Предоставленный вызывающим объектом указатель на буфер, выделенный вызывающим объектом, который получает запрошенное свойство устройства. Этот указатель может иметь значение NULL , если параметр BufferLength равен нулю.

[out] ResultLength

Указанное вызывающей стороной расположение, которое при возврате содержит размер в байтах сведений, которые WdfFdoInitQueryProperty хранятся в PropertyBuffer. Если возвращаемое значение этого метода равно STATUS_BUFFER_TOO_SMALL, ResultLength получает требуемый размер буфера.

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

Если операция выполнена успешно, метод возвращает STATUS_SUCCESS. К дополнительным возвращаемым значениям относятся:

Код возврата	Описание
STATUS_BUFFER_TOO_SMALL	Предоставленный буфер слишком мал для получения информации.
STATUS_INVALID_PARAMETER_2	Указанное значение DeviceProperty недопустимо.
STATUS_INVALID_DEVICE_REQUEST	Структура WDFDEVICE_INIT не была получена из функции обратного вызова EvtDriverDeviceAdd драйвера.

Метод также может возвращать другие значения NTSTATUS.

Прежде чем получать данные свойств устройства, драйверы обычно должны выполнить первоначальный вызов WdfFdoInitQueryProperty , чтобы получить требуемый размер буфера. Для некоторых свойств размер данных может меняться между временем возврата требуемого размера и временем повторного вызова этой подпрограммы драйвером. Поэтому драйверы должны вызывать WdfFdoInitQueryProperty внутри цикла, который выполняется до тех пор, пока состояние возврата не STATUS_BUFFER_TOO_SMALL.

WdfFdoInitQueryProperty рекомендуется использовать только в том случае, если требуемый размер буфера известен и неизменяем, так как в этом случае драйвер должен вызывать WdfFdoInitQueryProperty только один раз. Если требуемый размер буфера неизвестен или отличается, драйвер должен вызвать WdfFdoInitAllocAndQueryProperty.

Драйвер может вызывать WdfFdoInitQueryProperty только перед вызовом WdfDeviceCreate. Дополнительные сведения о вызове WdfDeviceCreate см. в разделе Создание объекта устройства платформы.

После вызова WdfDeviceCreate драйвер может получить сведения о свойствах устройства, вызвав WdfDeviceQueryProperty.

Дополнительные сведения о методе WdfFdoInitQueryProperty см. в разделе Создание объектов устройств в драйвере функции.

Кроме того, можно использовать WdfFdoInitQueryPropertyEx для доступа к свойствам устройства, предоставляемым через модель унифицированных свойств.

Примеры

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

NTSTATUS  status = STATUS_SUCCESS;
WCHAR  enumeratorName[64] = {0};
ULONG  returnSize;
UNICODE_STRING  unicodeEnumName, temp;

status = WdfFdoInitQueryProperty(
                                 DeviceInit,
                                 DevicePropertyEnumeratorName,
                                 sizeof(enumeratorName),
                                 enumeratorName,
                                 &returnSize
                                 );
if(!NT_SUCCESS(status)){
    return status;
}

RtlInitUnicodeString(
                     &unicodeEnumName,
                     enumeratorName
                     );
RtlInitUnicodeString(
                     &temp,
                     L"PCI"
                     );
if(RtlCompareUnicodeString(
                           &unicodeEnumName,
                           &temp,
                           TRUE
                           ) == 0) {
    //
    // This device is a PCI device.
    //
    return TRUE;
}

Требования

Требование	Значение
Целевая платформа	Универсальное
Минимальная версия KMDF	1,0
Минимальная версия UMDF	2,0
Верхняя часть	wdffdo.h (включая Wdf.h)
Библиотека	Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF)
IRQL	PASSIVE_LEVEL
Правила соответствия DDI	DeviceInitAPI(kmdf), DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf)

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

WdfDeviceQueryProperty

WdfFdoInitAllocAndQueryProperty

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