Leer en inglés

Compartir a través de


Función WdfDeviceCreate (wdfdevice.h)

[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 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 de device o DeviceInit no válidos.
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 de dispositivo.
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 de .

Observaciones

Antes de llamar a WdfDeviceCreate, el controlador debe llamar a funciones proporcionadas por el marco que inicializan la estructura WDFDEVICE_INIT. Para obtener más información sobre cómo inicializar esta estructura, vea 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 un EvtDriverDeviceAdd devolución de llamada, WdfDeviceCreate crea un FDO.
  • Si el controlador recibió la estructura de WDFDEVICE_INIT de una EvtChildListCreateDevice devolución de llamada, o desde una llamada a WdfPdoInitAllocate, WdfDeviceCreate crea un PDO.
Una vez que el controlador llama a WdfDeviceCreate, ya no puede acceder a la estructura de WDFDEVICE_INIT.

Los controladores de 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. 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 controlar objetos de dispositivo) cuando el administrador plug and play (PnP) determina que se ha quitado el dispositivo.

Si el controlador proporciona EvtCleanupCallback o EvtDestroyCallback funciones de devolución de llamada 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, vea Creación de un objeto de dispositivo marco.

Ejemplos

En el ejemplo de código siguiente se muestra cómo un EvtDriverDeviceAdd función de devolución de llamada 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

Consulte también

WDFDEVICE_INIT

WDF_OBJECT_ATTRIBUTES

WDF_OBJECT_ATTRIBUTES_INIT_CONTEXT_TYPE

WDF_PNPPOWER_EVENT_CALLBACKS_INIT

WdfDeviceInitFree

WdfDeviceInitSetIoType

WdfDeviceInitSetPnpPowerEventCallbacks

WdfDeviceMiniportCreate