Función WdfDeviceCreate (wdfdevice.h)

Artículo
08/08/2023

[Se aplica a KMDF y UMDF]

El método WdfDeviceCreate crea un objeto de dispositivo de marco.

Sintaxis

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

Parámetros

[in, out] DeviceInit

Dirección de un puntero a una estructura de WDFDEVICE_INIT . Si WdfDeviceCreate no encuentra ningún error, establece el puntero en NULL.

[in, optional] DeviceAttributes

Puntero a una estructura de WDF_OBJECT_ATTRIBUTES asignada por el autor de la llamada que contiene atributos para el nuevo objeto. (El miembro ParentObject de la estructura debe ser NULL). Este parámetro es opcional y se puede WDF_NO_OBJECT_ATTRIBUTES.

[out] Device

Puntero a una ubicación que recibe un identificador para el nuevo objeto de dispositivo de marco.

Valor devuelto

Si el método WdfDeviceCreate no encuentra ningún error, devuelve STATUS_SUCCESS. Entre los valores devueltos adicionales se incluyen:

Código devuelto	Descripción
STATUS_INVALID_PARAMETER	Se proporciona un identificador Device o DeviceInit no válido.
STATUS_INVALID_DEVICE_STATE	El controlador ya ha creado un objeto de dispositivo para el dispositivo.
STATUS_INVALID_SECURITY_DESCR	el controlador llamado WdfDeviceInitAssignSDDLString o WdfDeviceInitSetDeviceClass , pero no proporcionó un nombre para el objeto device.
STATUS_INSUFFICIENT_RESOURCES	No se pudo asignar un objeto de dispositivo.
STATUS_OBJECT_NAME_COLLISION	El nombre del dispositivo especificado por una llamada a WdfDeviceInitAssignName ya existe. El controlador puede llamar a WdfDeviceInitAssignName de nuevo para asignar un nuevo nombre.

Para obtener una lista de otros valores devueltos que WdfDeviceCreate puede devolver, consulte Errores de creación de objetos de marco.

El método podría devolver otros valores NTSTATUS.

Comentarios

Antes de llamar a WdfDeviceCreate, el controlador debe llamar a funciones proporcionadas por el marco que inicializan la estructura de WDFDEVICE_INIT. Para obtener más información sobre cómo inicializar esta estructura, consulte WDFDEVICE_INIT. Si el controlador encuentra errores al llamar a las funciones de inicialización, no debe llamar a WdfDeviceCreate. En este caso, es posible que el controlador tenga que llamar a WdfDeviceInitFree. Para obtener información sobre cuándo llamar a WdfDeviceInitFree, vea WdfDeviceInitFree.

Una llamada a WdfDeviceCreate crea un objeto de dispositivo de marco que representa un objeto de dispositivo funcional (FDO) o un objeto de dispositivo físico (PDO). El tipo de objeto de dispositivo que crea la función depende de cómo obtuvo el controlador la estructura WDFDEVICE_INIT:

Si el controlador recibió la estructura de WDFDEVICE_INIT de una devolución de llamada EvtDriverDeviceAdd , WdfDeviceCreate crea un FDO.
Si el controlador recibió la estructura WDFDEVICE_INIT de una devolución de llamada EvtChildListCreateDevice o de una llamada a WdfPdoInitAllocate, WdfDeviceCreate crea un PDO.

Una vez que el controlador llama a WdfDeviceCreate, ya no puede acceder a la estructura WDFDEVICE_INIT.

Los controladores miniport que usan el marco deben llamar a WdfDeviceMiniportCreate en lugar de WdfDeviceCreate.

El elemento primario de cada objeto de dispositivo de marco es el objeto de controlador del marco de trabajo del controlador. El controlador no puede cambiar este elemento primario y el miembro ParentObject de la estructura WDF_OBJECT_ATTRIBUTES debe ser NULL. El marco elimina cada objeto de dispositivo de marco (excepto algunos objetos de dispositivo de control) cuando el administrador de Plug and Play (PnP) determina que se ha quitado el dispositivo.

Si el controlador proporciona funciones de devolución de llamada EvtCleanupCallback o EvtDestroyCallback para el objeto de dispositivo de marco, tenga en cuenta que el marco llama a estas funciones de devolución de llamada en IRQL = PASSIVE_LEVEL.

Para obtener más información sobre cómo crear objetos de dispositivo, consulte Creación de un objeto de dispositivo framework.

Ejemplos

En el ejemplo de código siguiente se muestra cómo una función de devolución de llamada EvtDriverDeviceAdd podría inicializar y crear un objeto de dispositivo.

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;
}

Requisitos

Requisito	Value
Plataforma de destino	Universal
Versión mínima de KMDF	1.0
Versión mínima de UMDF	2.0
Encabezado	wdfdevice.h (incluya Wdf.h)
Library	Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF)
IRQL	PASSIVE_LEVEL
Reglas de cumplimiento de 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)