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

  • Статья

[Применимо к 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