Функция WdfDriverCreate (wdfdriver.h)

Статья
08/08/2023

[Относится к KMDF и UMDF]

Метод WdfDriverCreate создает объект драйвера платформы для вызывающего драйвера.

Синтаксис

NTSTATUS WdfDriverCreate(
  [in]            PDRIVER_OBJECT         DriverObject,
  [in]            PCUNICODE_STRING       RegistryPath,
  [in, optional]  PWDF_OBJECT_ATTRIBUTES DriverAttributes,
  [in]            PWDF_DRIVER_CONFIG     DriverConfig,
  [out, optional] WDFDRIVER              *Driver
);

Параметры

[in] DriverObject

Указатель на структуру DRIVER_OBJECT , представляющую объект драйвера модели windows (WDM). Драйвер получает этот указатель в качестве входных данных для своей подпрограммы DriverEntry .

[in] RegistryPath

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

[in, optional] DriverAttributes

Указатель на структуру WDF_OBJECT_ATTRIBUTES , выделенную вызывающим объектом. (Элемент ParentObject структуры должен иметь значение NULL.) Этот параметр является необязательным и может быть WDF_NO_OBJECT_ATTRIBUTES.

[in] DriverConfig

Указатель на структуру WDF_DRIVER_CONFIG , выделенную вызывающим объектом.

[out, optional] Driver

Указатель на расположение, которое получает дескриптор нового объекта драйвера платформы. Этот параметр является необязательным и может быть WDF_NO_HANDLE.

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

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

Код возврата	Описание
STATUS_DRIVER_INTERNAL_ERROR	Драйвер с именем WdfDriverCreate несколько раз.
STATUS_INVALID_PARAMETER	Драйвер, отличный от Plug and Play (PnP), указал функцию обратного вызова EvtDriverDeviceAdd.

Дополнительные сведения о возвращаемых значениях см. в разделе Ошибки создания объектов платформы.

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

Системная ошибка проверка возникает, если параметр DriverObject, RegistryPath или DriverConfig имеет значение NULL.

Драйвер, использующий платформу Kernel-Mode Driver Framework, должен вызывать WdfDriverCreate из подпрограммы DriverEntry , прежде чем вызывать другие подпрограммы платформы. Дополнительные сведения о DriverEntry см. в разделе DriverEntry для драйверов на основе платформы.

Прежде чем драйвер вызовет WdfDriverCreate, драйвер должен вызвать WDF_DRIVER_CONFIG_INIT , чтобы инициализировать свою WDF_DRIVER_CONFIG структуру.

Объект драйвера платформы является верхней частью дерева драйвера объектов платформы и, следовательно, не имеет родительского объекта.

Если драйвер предоставляет функции обратного вызова EvtCleanupCallback или EvtDegradCallback для объекта драйвера, обратите внимание, что платформа вызывает эти функции обратного вызова по адресу IRQL = PASSIVE_LEVEL.

Примеры

Следующий пример кода представляет собой подпрограмму DriverEntry , которая инициализирует структуру WDF_DRIVER_CONFIG, а затем создает объект драйвера платформы.

NTSTATUS
DriverEntry(
    IN PDRIVER_OBJECT  DriverObject,
    IN PUNICODE_STRING  RegistryPath
    )
{
    WDF_DRIVER_CONFIG  config;
    NTSTATUS  status = STATUS_SUCCESS;

    WDF_DRIVER_CONFIG_INIT(
                           &config,
                           MyEvtDeviceAdd
                           );
    config.EvtDriverUnload = MyEvtDriverUnload;
    status = WdfDriverCreate(
                             DriverObject,
                             RegistryPath,
                             WDF_NO_OBJECT_ATTRIBUTES,
                              &config,
                             WDF_NO_HANDLE
                             );
    if (!NT_SUCCESS(status)) {
        TraceEvents(
                    TRACE_LEVEL_ERROR,
                    DBG_PNP,
                    "WdfDriverCreate failed with status %!STATUS!",
                    status
                    );
    }
    return status;
}

Требования

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