estructura DRIVER_OBJECT (wdm.h)

Cada objeto de controlador representa la imagen de un controlador en modo kernel cargado. El administrador de E/S asigna la estructura de DRIVER_OBJECT y la pasa como parámetro de entrada a driver's DriverEntry, AddDevice y opcional Reinitialize rutinas y a su rutina Unload , si existe.

Un objeto de controlador es parcialmente opaco. Los escritores de controladores deben conocer determinados miembros de un objeto de controlador para inicializar un controlador y descargarlo si el controlador es descargable. Los siguientes miembros del objeto driver son accesibles para los controladores.

Sintaxis

typedef struct _DRIVER_OBJECT {
  CSHORT             Type;
  CSHORT             Size;
  PDEVICE_OBJECT     DeviceObject;
  ULONG              Flags;
  PVOID              DriverStart;
  ULONG              DriverSize;
  PVOID              DriverSection;
  PDRIVER_EXTENSION  DriverExtension;
  UNICODE_STRING     DriverName;
  PUNICODE_STRING    HardwareDatabase;
  PFAST_IO_DISPATCH  FastIoDispatch;
  PDRIVER_INITIALIZE DriverInit;
  PDRIVER_STARTIO    DriverStartIo;
  PDRIVER_UNLOAD     DriverUnload;
  PDRIVER_DISPATCH   MajorFunction[IRP_MJ_MAXIMUM_FUNCTION + 1];
} DRIVER_OBJECT, *PDRIVER_OBJECT;

Miembros

Type

Especifica el identificador de tipo de objeto para el objeto de controlador. El administrador de E/S establece este campo cuando asigna el objeto de controlador. Los controladores no deben usar ni modificar este campo.

Size

Especifica el tamaño, en bytes, de la estructura de objetos del controlador. El administrador de E/S establece este campo cuando asigna el objeto de controlador. Los controladores no deben usar ni modificar este campo.

DeviceObject

Puntero al primer objeto de dispositivo de una lista vinculada de objetos de dispositivo creados por el controlador. Este campo vincula todos los dispositivos creados por un solo controlador en una lista. El administrador de E/S actualiza automáticamente este miembro cuando el controlador llama a IoCreateDevice correctamente. Un controlador puede usar este miembro y el miembro NextDevice de DEVICE_OBJECT para recorrer la lista completa de todos los objetos de dispositivo que el controlador ha creado. Esto es especialmente útil durante la descarga del controlador para asegurarse de que todos los objetos del dispositivo se limpian correctamente.

Flags

Contiene marcas definidas por el sistema que describen varios atributos y estados del controlador. Este campo proporciona una ubicación extensible de marca para los objetos de controlador. Estas marcas se establecen y mantienen mediante el administrador de E/S y otros componentes del sistema. Los controladores no deben modificar directamente este campo.

DriverStart

Apunta a la dirección virtual base donde se carga la imagen del controlador en la memoria del sistema. Esta dirección representa el principio de la sección de código del controlador en el espacio de direcciones del kernel. El administrador de E/S establece este valor cuando se carga el controlador.

DriverSize

Especifica el tamaño, en bytes, de la imagen del controlador en memoria. Este valor representa la superficie de memoria total del controlador cargado, incluido el código, los datos y otras secciones. El administrador de E/S establece este valor cuando se carga el controlador.

DriverSection

Apunta al objeto de sección del controlador, que representa la imagen del controlador en el administrador de memoria. Se trata de una estructura de sistema opaca utilizada internamente por el administrador de memoria y el cargador. Los controladores no deben tener acceso a este miembro ni modificarlo.

DriverExtension

Puntero a la extensión del controlador. El único miembro accesible de la extensión del controlador es DriverExtension-AddDevice>, en el que la rutina DriverEntry de un controlador almacena la rutina AddDevice del controlador.

DriverName

Contiene el nombre de cadena Unicode del controlador. El subproceso del registro de errores usa este campo para determinar el nombre del controlador al que está o enlazada una solicitud de E/S. Normalmente se trata del formato \Driver\DriverName, donde DriverName corresponde al nombre del servicio del controlador en el Registro. El administrador de E/S establece este valor en función de la configuración del registro del controlador.

HardwareDatabase

Puntero a la ruta de acceso \Registry\Machine\Hardware a la información de configuración de hardware del Registro.

FastIoDispatch

Puntero a una estructura de FAST_IO_DISPATCH que define los puntos de entrada de E/S rápidos del controlador. Este puntero opcional apunta a una matriz de puntos de entrada alternativos a un controlador para la compatibilidad con "E/S rápida". La E/S rápida se realiza invocando la rutina del controlador directamente con parámetros independientes, en lugar de usar el mecanismo de llamada IRP estándar. Tenga en cuenta que estas funciones solo se pueden usar para E/S sincrónicas y cuando el archivo se almacena en caché. Este miembro solo lo usan los controladores del sistema de archivos (FSD) y los controladores de transporte de red.

DriverInit

Dirección del punto de entrada de la rutina DriverEntry del controlador. El administrador de E/S establece este campo para que apunte a la función de inicialización del controlador cuando se carga el controlador. Esta es la primera función a la que se llama en el controlador cuando se carga en la memoria y es responsable de inicializar el objeto de controlador y configurar rutinas de envío.

DriverStartIo

El punto de entrada de la rutina StartIo del controlador, si existe, que establece la rutina DriverEntry cuando se inicializa el controlador. Si un controlador no tiene ninguna rutina StartIo , este miembro es NULL.

DriverUnload

El punto de entrada de la rutina Unload del controlador, si existe, que establece la rutina DriverEntry cuando se inicializa el controlador. Si un controlador no tiene ninguna rutina De descarga , este miembro es NULL.

MajorFunction[IRP_MJ_MAXIMUM_FUNCTION + 1]

Tabla de distribución que consta de una matriz de puntos de entrada para las rutinas DispatchXxx del controlador. Los valores de índice de la matriz son los valores IRP_MJ_XXX que representan cada código de función principal de IRP. Esta tabla de distribución de funciones principales debe ser el último campo del objeto para que permanezca extensible. Cada controlador debe establecer puntos de entrada en esta matriz para las solicitudes IRP_MJ_XXX que controla el controlador. Para obtener más información, vea Escribir rutinas de distribución.

Para ayudar al análisis de código para controladores, el comprobador de controladores estáticos (SDV) y otras herramientas de comprobación, cada rutina DispatchXxx se declara mediante el tipo de DRIVER_DISPATCH, como se muestra en este ejemplo de código:

DRIVER_DISPATCH DispatchXxx;

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

_Use_decl_annotations_
NTSTATUS
  DispatchXxx(
    struct _DEVICE_OBJECT  *DeviceObject,
    struct _IRP  *Irp
    )
  {
      // Function body
  }

El tipo de función DRIVER_DISPATCH 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 _ a la _Use_decl_annotationsdefinición de función. La _Use_decl_annotations_ anotación garantiza que se usen las anotaciones que se aplican al tipo de función DRIVER_DISPATCH 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.

Observaciones

Cada rutina de inicialización del controlador en modo kernel debe denominarse DriverEntry , por lo que el sistema cargará el controlador automáticamente. Si el nombre de esta rutina es algo más, el escritor de controladores debe definir el nombre de la rutina de inicialización para el enlazador; de lo contrario, el cargador del sistema o el administrador de E/S no pueden encontrar la dirección de transferencia del controlador. Los nombres de otras rutinas de controlador estándar se pueden elegir a discreción del escritor de controladores.

Un controlador debe establecer sus puntos de entrada DispatchXxx en el objeto de controlador que se pasa a la rutina DriverEntry cuando se carga el controlador. Un controlador de dispositivo debe establecer uno o varios puntos de entrada DispatchXxx para el IRP_MJ_XXX que se requiere cualquier controlador del mismo tipo de dispositivo para controlar. Un controlador de nivel superior debe establecer uno o varios puntos de entrada DispatchXxx para todos los IRP_MJ_XXX que debe pasar al controlador de dispositivo subyacente. De lo contrario, un controlador no se envía IRP para ningún IRP_MJ_XXX para el que no configura una rutina DispatchXxx en el objeto de controlador. Para obtener más información sobre el conjunto de IRP_MJ_XXX que los controladores para distintos tipos de dispositivos subyacentes son necesarios para controlar, vea IRP Major Function Codes( Códigos de función principales de IRP).

La rutina DriverEntry también establece los puntos de entrada AddDevice, StartIo o Unload del controlador, si los hay, en el objeto driver.

Los controladores de dispositivo pueden usar la cadena HardwareDatabase para obtener información de configuración de hardware del Registro cuando se carga el controlador. A un controlador se le concede acceso de solo lectura a esta cadena.

La entrada RegistryPath de la rutina DriverEntry apunta a la clave \Registry\Machine\System\CurrentControlSet\Services\DriverName , donde la entrada de valor driverName identifica el controlador. Esta clave del Registro contiene la configuración del servicio del controlador, incluidos los valores como:

• Inicio: cuando se debe cargar el controlador (arranque, sistema, automático, demanda o deshabilitado)
• Tipo: el tipo de servicio (controlador de kernel, controlador del sistema de archivos, etc.)
• ErrorControl: cómo debe responder el sistema si el controlador no se puede cargar
• ImagePath: ruta de acceso al archivo binario del controlador

Los controladores pueden almacenar datos de configuración adicionales en la subclave Parameters de su clave de servicio. En cuanto a HardwareDatabase en el objeto de controlador de entrada, se concede acceso de solo lectura a esta cadena.

Los miembros no documentados dentro de un objeto de controlador deben considerarse inaccesibles. Es posible que los controladores con dependencias en ubicaciones de miembros de objeto o en el acceso a miembros no documentados no permanezcan portátiles e interoperables con otros controladores a lo largo del tiempo.

Requisitos

Requisito	Importancia
encabezado	wdm.h (include Wdm.h, Ntddk.h, Ntifs.h)

Consulte también

DriverEntry

ioCreateDevice

IoDeleteDevice

StartIo

descargar