Función WdfDriverCreate (wdfdriver.h)

Artículo
08/08/2023

[Se aplica a KMDF y UMDF]

El método WdfDriverCreate crea un objeto de controlador de marco para el controlador que realiza la llamada.

Sintaxis

NTSTATUS WdfDriverCreate(
  [in]            PDRIVER_OBJECT         DriverObject,
  [in]            PCUNICODE_STRING       RegistryPath,
  [in, optional]  PWDF_OBJECT_ATTRIBUTES DriverAttributes,
  [in]            PWDF_DRIVER_CONFIG     DriverConfig,
  [out, optional] WDFDRIVER              *Driver
);

Parámetros

[in] DriverObject

Puntero a una estructura de DRIVER_OBJECT que representa un objeto de controlador del modelo de controlador de Windows (WDM). El controlador recibe este puntero como entrada para su rutina DriverEntry .

[in] RegistryPath

Puntero a una estructura de UNICODE_STRING que contiene la cadena de ruta de acceso del Registro que el controlador recibió como entrada en su rutina DriverEntry .

[in, optional] DriverAttributes

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

[in] DriverConfig

Puntero a una estructura de WDF_DRIVER_CONFIG asignada por el autor de la llamada.

[out, optional] Driver

Puntero a una ubicación que recibe un identificador para el nuevo objeto de controlador de marco. Este parámetro es opcional y puede ser WDF_NO_HANDLE.

Valor devuelto

WdfDriverCreate devuelve STATUS_SUCCESS si la operación se realiza correctamente. De lo contrario, este método podría devolver uno de los siguientes valores:

Código devuelto	Descripción
STATUS_DRIVER_INTERNAL_ERROR	El controlador llamado WdfDriverCreate más de una vez.
STATUS_INVALID_PARAMETER	Un controlador que no es de Plug and Play (PnP) especificó una función de devolución de llamada EvtDriverDeviceAdd.

Para obtener más información sobre los valores devueltos, vea Errores de creación de objetos de marco.

Este método también podría devolver otros valores NTSTATUS.

Se produce una comprobación de errores del sistema si el parámetro DriverObject, RegistryPath o DriverConfig es NULL.

Comentarios

Un controlador que use Kernel-Mode Driver Framework debe llamar a WdfDriverCreate desde su rutina DriverEntry , antes de llamar a cualquier otra rutina de marco. Para obtener más información sobre DriverEntry, vea DriverEntry for Framework-based Drivers.

Antes de que el controlador llame a WdfDriverCreate, el controlador debe llamar a WDF_DRIVER_CONFIG_INIT para inicializar su estructura de WDF_DRIVER_CONFIG .

El objeto del controlador de marco es la parte superior del árbol del controlador de objetos de marco y, por lo tanto, no tiene un objeto primario.

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

Ejemplos

El ejemplo de código siguiente es una rutina DriverEntry que inicializa una estructura de WDF_DRIVER_CONFIG y, a continuación, crea un objeto de controlador de marco.

NTSTATUS
DriverEntry(
    IN PDRIVER_OBJECT  DriverObject,
    IN PUNICODE_STRING  RegistryPath
    )
{
    WDF_DRIVER_CONFIG  config;
    NTSTATUS  status = STATUS_SUCCESS;

    WDF_DRIVER_CONFIG_INIT(
                           &config,
                           MyEvtDeviceAdd
                           );
    config.EvtDriverUnload = MyEvtDriverUnload;
    status = WdfDriverCreate(
                             DriverObject,
                             RegistryPath,
                             WDF_NO_OBJECT_ATTRIBUTES,
                              &config,
                             WDF_NO_HANDLE
                             );
    if (!NT_SUCCESS(status)) {
        TraceEvents(
                    TRACE_LEVEL_ERROR,
                    DBG_PNP,
                    "WdfDriverCreate failed with status %!STATUS!",
                    status
                    );
    }
    return status;
}

Requisitos

Requisito	Value
Plataforma de destino	Universal
Versión mínima de KMDF	1.0
Versión mínima de UMDF	2.0
Encabezado	wdfdriver.h (incluir Wdf.h)
Library	Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF)
IRQL	PASSIVE_LEVEL
Reglas de cumplimiento de DDI	ChangeQueueState(kmdf), DriverAttributeChanged(kmdf), DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf), MiniportOnlyWdmDevice(kmdf)