Función WdfDeviceCreate (wdfdevice.h)
[Se aplica a KMDF y UMDF]
El método WdfDeviceCreate crea un objeto de dispositivo de marco.
NTSTATUS WdfDeviceCreate(
[in, out] PWDFDEVICE_INIT *DeviceInit,
[in, optional] PWDF_OBJECT_ATTRIBUTES DeviceAttributes,
[out] WDFDEVICE *Device
);
[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.
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 .
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.
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.
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;
}
Requisito | Valor |
---|---|
de la plataforma de destino de | Universal |
versión mínima de KMDF | 1.0 |
versión mínima de UMDF | 2.0 |
encabezado de | wdfdevice.h (incluya Wdf.h) |
biblioteca de | Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF) |
irQL | PASSIVE_LEVEL |
reglas de cumplimiento de DDI | AccessHardwareKey(kmdf), AddPdoToStaticChildList(kmdf), ChangeQueueState(kmdf), ChildDeviceInitAPI(km), ChildListConfiguration(kmdf), ControlDeviceDeleted(kmdf), ControlDeviceInitAllocate(kmdf), ControlDeviceInitAPI(kmdf), CtlDeviceFinishInitDeviceAdd(kmdf), CtlDeviceFinishInitDr, 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) |
WDF_OBJECT_ATTRIBUTES_INIT_CONTEXT_TYPE
WDF_PNPPOWER_EVENT_CALLBACKS_INIT