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 puede ser 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, vea 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, 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 WDFDEVICE_INIT de una devolución de llamada EvtDriverDeviceAdd , WdfDeviceCreate crea un FDO.
- Si el controlador recibió la estructura de WDFDEVICE_INIT de una devolución de llamada EvtChildListCreateDevice o de 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 de marco 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, vea Creating a Framework Device Object.
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 (incluir 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) |
Consulte también
WDF_OBJECT_ATTRIBUTES_INIT_CONTEXT_TYPE
WDF_PNPPOWER_EVENT_CALLBACKS_INIT