Função IoAttachDeviceToDeviceStackSafe (ntddk.h)

A rotina IoAttachDeviceToDeviceStackSafe anexa o objeto de dispositivo do chamador ao objeto de dispositivo mais alto em uma pilha de driver.

Sintaxe

NTSTATUS IoAttachDeviceToDeviceStackSafe(
  [in]  PDEVICE_OBJECT SourceDevice,
  [in]  PDEVICE_OBJECT TargetDevice,
  [out] PDEVICE_OBJECT *AttachedToDeviceObject
);

Parâmetros

[in] SourceDevice

Ponteiro para um objeto de dispositivo criado pelo chamador.

[in] TargetDevice

Ponteiro para o objeto do dispositivo na pilha à qual o objeto SourceDevice deve ser anexado.

[out] AttachedToDeviceObject

Na entrada, esse parâmetro especifica o endereço de SourceDevice-DeviceExtension-AttachedToDeviceObject>>, que deve conter um ponteiro NULL. Na saída, esse parâmetro recebe um ponteiro para o objeto do dispositivo ao qual o SourceDevice foi anexado.

Retornar valor

IoAttachDeviceToDeviceStackSafe retornará STATUS_SUCCESS se SourceDevice for anexado com êxito acima do TargetDevice; caso contrário, retornará STATUS_NO_SUCH_DEVICE.

Comentários

Como IoAttachDeviceToDeviceStack, IoAttachDeviceToDeviceStackSafe estabelece camadas entre drivers para que os mesmos IRPs sejam enviados para cada driver na pilha. No entanto, ao contrário de IoAttachDeviceToDeviceStack, IoAttachDeviceToDeviceStackSafe tem um parâmetro adicional, AttachedToDeviceObject, que o driver de filtro usa para passar o endereço do campo AttachedToDeviceObject do objeto SourceDevice . IoAttachDeviceToDeviceStackSafe atualiza esse campo enquanto mantém o bloqueio de banco de dados do sistema de E/S. Como ele mantém esse bloqueio, IoAttachDeviceToDeviceStackSafe evita uma condição de corrida que poderia ocorrer de outra forma se o objeto SourceDevice recebesse um IRP antes que seu campo AttachedToDeviceObject fosse atualizado.

Um driver de filtro do sistema de arquivos chama IoAttachDeviceToDeviceStackSafe para anexar seu próprio objeto de dispositivo de filtro (SourceDevice) acima de um objeto de dispositivo (TargetDevice) pertencente a um sistema de arquivos ou outro driver de filtro. As solicitações de E/S subsequentes enviadas para AttachedToDeviceObject são recebidas primeiro pelo driver de filtro, que as processa e as encaminha para o próximo driver na pilha chamando IoCallDriver.

Se o objeto de dispositivo especificado por TargetDevice estiver atualmente na parte superior da pilha do driver, SourceDevice será anexado diretamente ao TargetDevice. Nesse caso, TargetDevice e o ponteiro AttachedToDeviceObject retornado são iguais.

Se um ou mais objetos de dispositivo de filtro já estiverem anexados acima do TargetDevice na pilha do driver, IoAttachDeviceToDeviceStackSafe anexará SourceDevice ao objeto de dispositivo de filtro mais alto. Um ponteiro para o último é retornado em AttachedToDeviceObject.

No momento imediatamente após ser anexado à parte superior da pilha, SourceDevice ocupa a parte superior da pilha de driver. Observe, no entanto, que isso não significa necessariamente que SourceDevice permanecerá na parte superior da pilha do driver. Outros filtros podem anexar seus próprios objetos de dispositivo de filtro acima do SourceDevice na pilha.

IoAttachDeviceToDeviceStackSafe define o membro AlignmentRequirement do objeto de dispositivo apontado por SourceDevice para o valor do correspondente no objeto de dispositivo mais baixo e define o StackSize em SourceDevice como o valor no próximo objeto inferior mais um.

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Essa rotina está disponível no Pacote Cumulativo de Atualizações para Windows 2000 Service Pack 4 (SP4) e no Windows XP e posterior.
Plataforma de Destino	Universal
Cabeçalho	ntddk.h (inclua Ntddk.h)
Biblioteca	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	<= DISPATCH_LEVEL
Regras de conformidade de DDI	HwStorPortProhibitedDDIs(storport)

Confira também

IoAttachDeviceToDeviceStack

IoCallDriver