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 de 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 de controlador del controlador.

[in] PhysicalDeviceObject

Puntero proporcionado por el autor de la llamada a una estructura de 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.

Comentarios

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

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

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

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

Ejemplos

Para definir una rutina de devolución de llamada AddDevice , 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 Code Analysis for Drivers, Static Driver Verifier (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 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 más precisión los errores al ejecutar las herramientas de análisis de código, asegúrese de agregar la anotación a la _Use_decl_annotations_ definición de la función. La _Use_decl_annotations_ anotación 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 roles de función para controladores WDM. Para obtener información sobre _Use_decl_annotations_, consulte Anotación del comportamiento de la función.

Requisitos

Requisito	Value
Plataforma de destino	Escritorio
Encabezado	wdm.h (incluya Wdm.h, Ntddk.h, Ntifs.h)
IRQL	Se llama en PASSIVE_LEVEL (consulte la sección Comentarios).