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

[Относится к 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.

Драйверы 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;
}

Требования

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

WDFDEVICE_INIT

WDF_OBJECT_ATTRIBUTES

WDF_OBJECT_ATTRIBUTES_INIT_CONTEXT_TYPE

WDF_PNPPOWER_EVENT_CALLBACKS_INIT

WdfDeviceInitFree

WdfDeviceInitSetIoType

WdfDeviceInitSetPnpPowerEventCallbacks

WdfDeviceMiniportCreate