Función IoAttachDevice (wdm.h)

Artículo
08/08/2023

La rutina IoAttachDevice asocia el objeto de dispositivo del autor de la llamada a un objeto de dispositivo de destino con nombre, de modo que las solicitudes de E/S enlazadas al dispositivo de destino se enrutan primero al autor de la llamada.

Sintaxis

NTSTATUS IoAttachDevice(
  [in]  PDEVICE_OBJECT  SourceDevice,
  [in]  PUNICODE_STRING TargetDevice,
  [out] PDEVICE_OBJECT  *AttachedDevice
);

Parámetros

[in] SourceDevice

Puntero al objeto de dispositivo creado por el autor de la llamada.

[in] TargetDevice

Puntero a un búfer que contiene el nombre del objeto de dispositivo al que se va a adjuntar el sourceDevice especificado.

[out] AttachedDevice

Puntero al almacenamiento asignado por el autor de la llamada para un puntero. En la devolución, contiene un puntero al objeto de dispositivo de destino si los datos adjuntos se realizan correctamente.

Valor devuelto

IoAttachDevice puede devolver uno de los siguientes valores NTSTATUS:

Comentarios

IoAttachDevice establece la capa entre los controladores para que se puedan enviar los mismos IRP a cada controlador de la cadena.

Esta rutina la usan los controladores intermedios durante la inicialización. Permite que un controlador de este tipo conecte su propio objeto de dispositivo a otro dispositivo de forma que las solicitudes realizadas al dispositivo original se proporcionan primero al controlador intermedio.

El autor de la llamada solo se puede colocar en capas en la parte superior de una cadena existente de controladores superpuestas. IoAttachDevice busca el objeto de dispositivo más alto en capas sobre TargetDevice y se asocia a ese objeto (que puede ser targetDevice). Por lo tanto, no se debe llamar a esta rutina si un controlador que debe ser de nivel superior ya se ha superpuesta sobre el dispositivo de destino.

Tenga en cuenta que para los controladores y controladores del sistema de archivos de la pila de almacenamiento, IoAttachDevice abre el dispositivo de destino con FILE_READ_ATTRIBUTES y, a continuación, llama a IoGetRelatedDeviceObject. Esto no hace que se monte un sistema de archivos. Por lo tanto, una llamada correcta a IoAttachDevice devuelve el objeto de dispositivo del controlador de almacenamiento, no el del controlador del sistema de archivos.

Esta rutina establece AlignmentRequirement en SourceDevice en el valor del objeto de dispositivo siguiente inferior y establece StackSize en el valor del objeto siguiente inferior más uno.

Advertencia

AttachedDevice debe apuntar a una ubicación de memoria global, como la extensión del dispositivo del controlador. IoAttachDevice abre el objeto de archivo para el dispositivo de destino, actualiza AttachedDevice, realiza la asociación y, a continuación, cierra el objeto de archivo. Por lo tanto, el dispositivo de origen recibe las solicitudes de IRP_MJ_CLEANUP y IRP_MJ_CLOSE para el objeto de archivo antes de que IoAttachDevice devuelva. El controlador debe reenviar estas solicitudes al dispositivo de destino y AttachedDevice debe ser una ubicación de memoria accesible para las rutinas DispatchCleanup y DispatchClose del controlador.

Requisitos

Requisito	Value
Plataforma de destino	Universal
Encabezado	wdm.h (incluya Wdm.h, Ntddk.h, Ntifs.h)
Library	NtosKrnl.lib
Archivo DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL
Reglas de cumplimiento de DDI	HwStorPortProhibitedDIs(storport), IrqlIoPassive1(wdm)