DRIVER_ADD_DEVICE función de devolución de llamada (wdm.h)

La rutina AddDevice es responsable de crear objetos de dispositivo funcionales (FDO) o filtrar objetos de dispositivo (DO de filtro) para dispositivos enumerados por el administrador plug and play (PnP).

Sintaxis

DRIVER_ADD_DEVICE DriverAddDevice;

NTSTATUS DriverAddDevice(
  [in] _DRIVER_OBJECT *DriverObject,
  [in] _DEVICE_OBJECT *PhysicalDeviceObject
)
{...}

Parámetros

[in] DriverObject

Puntero proporcionado por el autor de la llamada a una estructura de DRIVER_OBJECT. Este es el objeto driver del controlador.

[in] PhysicalDeviceObject

Puntero proporcionado por el autor de la llamada a una estructura DEVICE_OBJECT que representa un objeto de dispositivo físico (PDO) creado por un controlador de nivel inferior.

Valor devuelto

Si la rutina se realiza correctamente, debe devolver STATUS_SUCCESS. De lo contrario, debe devolver uno de los valores de estado de error definidos en Ntstatus.h.

Observaciones

Todos los controladores en modo kernel que admiten PnP deben proporcionar una rutina de AddDevice.

La rutina AddDevice de un controlador debe denominarse XxxAddDevice, donde Xxx es un prefijo específico del controlador. La rutina del controlador DriverEntry debe almacenar la dirección de la rutina AddDevice en DriverObject->DriverExtension->AddDevice.

Las responsabilidades principales de AddDevice rutina llaman a ioCreateDevice para crear un objeto de dispositivo y, a continuación, llamar a IoAttachDeviceToDeviceStack para asociar el objeto de dispositivo a la pila de dispositivos. Para obtener información detallada sobre cómo implementar la rutina de addDevice de un controlador, consulte Escribir una rutina AddDevice.

Una rutina addDevice se ejecuta en un contexto de subproceso del sistema en IRQL = PASSIVE_LEVEL.

Ejemplos

Para definir un AddDevice rutina de devolución de llamada, primero debe proporcionar una declaración de función que identifique el tipo de rutina de devolución de llamada que está definiendo. Windows proporciona un conjunto de tipos de función de devolución de llamada para controladores. Declarar una función mediante los tipos de función de devolución de llamada ayuda a Análisis de código para controladores, comprobador de controladores estáticos (SDV) y otras herramientas de comprobación encuentran errores y es un requisito para escribir controladores para el sistema operativo Windows.

Por ejemplo, para definir una rutina de devolución de llamada de AddDevice denominada MyAddDevice<, use el tipo DRIVER_ADD_DEVICE como se muestra en este ejemplo de código:

DRIVER_ADD_DEVICE MyAddDevice;

A continuación, implemente la rutina de devolución de llamada de la siguiente manera:

_Use_decl_annotations_
NTSTATUS
  MyAddDevice(
    struct _DRIVER_OBJECT  *DriverObject,
    struct _DEVICE_OBJECT  *PhysicalDeviceObject 
    )
  {
      // Function body
  }

El tipo de función DRIVER_ADD_DEVICE se define en el archivo de encabezado Wdm.h. Para identificar con mayor precisión los errores al ejecutar las herramientas de análisis de código, asegúrese de agregar la anotación _Use_decl_annotations_ a la definición de función. La anotación _Use_decl_annotations_ garantiza que se usen las anotaciones que se aplican al tipo de función DRIVER_ADD_DEVICE en el archivo de encabezado. Para obtener más información sobre los requisitos de las declaraciones de función, vea Declarar funciones mediante tipos de rol de función para controladores WDM. Para obtener información sobre _Use_decl_annotations_, vea Anotación del comportamiento de la función.

Requisitos

Requisito	Valor
de la plataforma de destino de	Escritorio
encabezado de	wdm.h (include Wdm.h, Ntddk.h, Ntifs.h)
irQL	Se llama en PASSIVE_LEVEL (consulte la sección Comentarios).