Função IoAttachDevice (wdm.h)

Artigo
02/27/2024

A rotina IoAttachDevice anexa o objeto de dispositivo do chamador a um objeto de dispositivo de destino nomeado, para que as solicitações de E/S associadas ao dispositivo de destino sejam roteadas primeiro para o chamador.

Sintaxe

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

Parâmetros

[in] SourceDevice

Ponteiro para o objeto de dispositivo criado pelo chamador.

[in] TargetDevice

Ponteiro para um buffer que contém o nome do objeto de dispositivo ao qual o SourceDevice especificado deve ser anexado.

[out] AttachedDevice

Ponteiro para o armazenamento alocado pelo chamador para um ponteiro. No retorno, contém um ponteiro para o objeto de dispositivo de destino se o anexo for bem-sucedido.

Retornar valor

IoAttachDevice pode retornar um dos seguintes valores NTSTATUS:

Comentários

IoAttachDevice estabelece camadas entre drivers para que os mesmos IRPs possam ser enviados para cada driver na cadeia.

Essa rotina é usada por drivers intermediários durante a inicialização. Ele permite que esse driver anexe seu próprio objeto de dispositivo a outro dispositivo de forma que todas as solicitações feitas ao dispositivo original sejam fornecidas primeiro ao driver intermediário.

O chamador só pode ser colocado em camadas na parte superior de uma cadeia existente de drivers em camadas. IoAttachDevice pesquisa o objeto de dispositivo mais alto em camadas sobre TargetDevice e se conecta a esse objeto (que pode ser o TargetDevice). Portanto, essa rotina não deve ser chamada se um driver que deve ser de nível mais alto já tiver se sobressoido sobre o dispositivo de destino.

Observe que, para drivers e drivers do sistema de arquivos na pilha de armazenamento, IoAttachDevice abre o dispositivo de destino com FILE_READ_ATTRIBUTES e, em seguida, chama IoGetRelatedDeviceObject. Isso não faz com que um sistema de arquivos seja montado. Assim, uma chamada bem-sucedida para IoAttachDevice retorna o objeto de dispositivo do driver de armazenamento, não o do driver do sistema de arquivos.

Essa rotina define AlignmentRequirement em SourceDevice como o valor no objeto de dispositivo mais baixo e define StackSize como o valor no objeto mais um.

Aviso

AttachedDevice deve apontar para um local de memória global, como a extensão de dispositivo do driver. IoAttachDevice abre o objeto de arquivo para o dispositivo de destino, atualiza AttachedDevice, executa a anexação e fecha o objeto de arquivo. Assim, o dispositivo de origem recebe as solicitações IRP_MJ_CLEANUP e IRP_MJ_CLOSE para o objeto de arquivo antes que IoAttachDevice retorne. O driver deve encaminhar essas solicitações para o dispositivo de destino e AttachedDevice deve ser um local de memória acessível para as rotinas DispatchCleanup e DispatchClose do driver.

Requisitos

Requisito	Valor
Plataforma de Destino	Universal
Cabeçalho	wdm.h (include Wdm.h, Ntddk.h, Ntifs.h)
Biblioteca	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL
Regras de conformidade de DDI	HwStorPortProhibitedDIs(storport), IrqlIoPassive1(wdm)