Функция WdfDeviceCreate (wdfdevice.h)

Статья
08/08/2023

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

Метод WdfDeviceCreate создает объект устройства платформы.

Синтаксис

NTSTATUS WdfDeviceCreate(
  [in, out]      PWDFDEVICE_INIT        *DeviceInit,
  [in, optional] PWDF_OBJECT_ATTRIBUTES DeviceAttributes,
  [out]          WDFDEVICE              *Device
);

Параметры

[in, out] DeviceInit

Адрес указателя на структуру WDFDEVICE_INIT . Если wdfDeviceCreate не обнаруживает ошибок, он задает для указателя значение NULL.

[in, optional] DeviceAttributes

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

[out] Device

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

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

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

Код возврата	Описание
STATUS_INVALID_PARAMETER	Указан недопустимый дескриптор Device или DeviceInit .
STATUS_INVALID_DEVICE_STATE	Драйвер уже создал объект устройства для устройства.
STATUS_INVALID_SECURITY_DESCR	драйвер с именем WdfDeviceInitAssignSDDLString или WdfDeviceInitSetDeviceClass , но не предоставил имя для объекта устройства.
STATUS_INSUFFICIENT_RESOURCES	Не удалось выделить объект устройства.
STATUS_OBJECT_NAME_COLLISION	Имя устройства, указанное при вызове WdfDeviceInitAssignName , уже существует. Драйвер может снова вызвать WdfDeviceInitAssignName , чтобы назначить новое имя.

Список других возвращаемых значений, которые может возвращать WdfDeviceCreate, см. в разделе Ошибки создания объектов платформы.

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

Перед вызовом WdfDeviceCreate драйвер должен вызвать предоставляемые платформой функции, которые инициализируют структуру WDFDEVICE_INIT. Дополнительные сведения об инициализации этой структуры см. в разделе WDFDEVICE_INIT. Если драйвер обнаруживает ошибки при вызове функций инициализации, он не должен вызывать WdfDeviceCreate. В этом случае драйверу может потребоваться вызвать WdfDeviceInitFree. Сведения о том, когда следует вызывать WdfDeviceInitFree, см. в разделе WdfDeviceInitFree.

Вызов WdfDeviceCreate создает объект устройства платформы, который представляет либо объект функционального устройства (FDO), либо объект физического устройства (PDO). Тип объекта устройства, создаваемого функцией, зависит от того, как драйвер получил структуру WDFDEVICE_INIT:

Если драйвер получил структуру WDFDEVICE_INIT из обратного вызова EvtDriverDeviceAdd , WdfDeviceCreate создает FDO.
Если драйвер получил структуру WDFDEVICE_INIT из обратного вызова EvtChildListCreateDevice или из вызова WdfPdoInitAllocate, WdfDeviceCreate создает PDO.

После вызова WdfDeviceCreate драйвер больше не сможет получить доступ к WDFDEVICE_INIT структуре.

Драйверы miniport, использующие платформу, должны вызывать WdfDeviceMiniportCreate вместо WdfDeviceCreate.

Родительским объектом каждого объекта устройства платформы является объект драйвера платформы драйвера. Драйвер не может изменить этот родительский элемент, а элемент ParentObjectструктуры WDF_OBJECT_ATTRIBUTES должен иметь значение NULL. Платформа удаляет каждый объект устройства платформы (за исключением некоторых объектов управляющего устройства), когда диспетчер Plug and Play (PnP) определяет, что устройство было удалено.

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

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

Примеры

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

NTSTATUS
MyEvtDeviceAdd(
    IN WDFDRIVER  Driver,
    IN PWDFDEVICE_INIT  DeviceInit
    )
{
    WDF_PNPPOWER_EVENT_CALLBACKS  pnpPowerCallbacks;
    WDF_OBJECT_ATTRIBUTES  attributes;
    NTSTATUS  status;
    WDFDEVICE  device;
 
    //
    // Initialize the WDF_PNPPOWER_EVENT_CALLBACKS structure.
    //
    WDF_PNPPOWER_EVENT_CALLBACKS_INIT(&pnpPowerCallbacks);
    pnpPowerCallbacks.EvtDevicePrepareHardware = MyEvtDevicePrepareHardware;
    pnpPowerCallbacks.EvtDeviceD0Entry = MyEvtDeviceD0Entry;
    pnpPowerCallbacks.EvtDeviceD0Exit  = MyEvtDeviceD0Exit;
    WdfDeviceInitSetPnpPowerEventCallbacks(
                                           DeviceInit,
                                           &pnpPowerCallbacks
                                           );
    //
    // This driver uses buffered I/O.
    //
    WdfDeviceInitSetIoType(
                           DeviceInit,
                           WdfDeviceIoBuffered
                           );
 
    //
    // Specify the device object's context space by
    // using a driver-defined DEVICE_CONTEXT structure.
 //
    WDF_OBJECT_ATTRIBUTES_INIT_CONTEXT_TYPE(
                                            &attributes,
                                            DEVICE_CONTEXT
                                            );
 //
    // Create the device object.
    //
    status = WdfDeviceCreate(
                             &DeviceInit,
                             &attributes,
                             &device
                             );
    if (!NT_SUCCESS(status)) {
        return status;
    }
    return STATUS_SUCCESS;
}

Требования

Требование	Значение
Целевая платформа	Универсальное
Минимальная версия KMDF	1,0
Минимальная версия UMDF	2,0
Верхняя часть	wdfdevice.h (включая Wdf.h)
Библиотека	Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF)
IRQL	PASSIVE_LEVEL
Правила соответствия DDI	AccessHardwareKey(kmdf), AddPdoToStaticChildList(kmdf), ChangeQueueState(kmdf), ChildDeviceInitAPI(kmdf), ChildListConfiguration(kmdf), ControlDeviceDeleted(kmdf), ControlDeviceInitAllocate(kmdf), ControlDeviceInitAPI(kmdf), CtlDeviceFinishInitDeviceAdd(kmdf), CtlDeviceFinishInitDrEntry(kmdf), DeviceCreateFail(kmdf), DeviceInitAllocate(kmdf), DeviceInitAPI(kmdf), DriverCreate(kmdf), InitFreeDeviceCreate(kmdf), InitFreeDeviceCreateType2(kmdf), InitFreeDeviceCreateType4(kmdf), InitFreeNull(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf), PdoDeviceInitAPI(kmdf), PdoInitFreeDeviceCreate(kmdf), PdoInitFreeDeviceCreateType2(kmdf), PdoInitFreeDeviceCreateType4(kmdf)