Função IoGetDeviceObjectPointer (wdm.h)

Artigo
02/27/2024

A rotina IoGetDeviceObjectPointer retorna um ponteiro para o objeto superior na pilha do objeto de dispositivo nomeado e um ponteiro para o objeto de arquivo correspondente, se o acesso solicitado aos objetos puder ser concedido.

Sintaxe

NTSTATUS IoGetDeviceObjectPointer(
  [in]  PUNICODE_STRING ObjectName,
  [in]  ACCESS_MASK     DesiredAccess,
  [out] PFILE_OBJECT    *FileObject,
  [out] PDEVICE_OBJECT  *DeviceObject
);

Parâmetros

[in] ObjectName

Ponteiro para um buffer que contém uma cadeia de caracteres Unicode que é o nome do objeto do dispositivo.

[in] DesiredAccess

Especifica o valor ACCESS_MASK que representa o acesso desejado. Normalmente , DesiredAccess é FILE_READ_DATA. Raramente, os direitos de acesso FILE_WRITE_DATA ou FILE_ALL_ACCESS são especificados.

[out] FileObject

Ponteiro para o objeto de arquivo que representa o objeto de dispositivo correspondente para o código de modo de usuário se a chamada for bem-sucedida.

[out] DeviceObject

Ponteiro para o objeto de dispositivo que representa o dispositivo lógico, virtual ou físico nomeado se a chamada for bem-sucedida.

Retornar valor

IoGetDeviceObjectPointer retornará STATUS_SUCCESS se for bem-sucedido. Os possíveis valores retornados por erro incluem os seguintes códigos de status:

STATUS_OBJECT_TYPE_MISMATCH

STATUS_INVALID_PARAMETER

STATUS_PRIVILEGE_NOT_HELD

STATUS_INSUFFICIENT_RESOURCES

STATUS_OBJECT_NAME_INVALID

Comentários

IoGetDeviceObjectPointer estabelece uma "conexão" entre o chamador e o driver de nível inferior seguinte. Um chamador bem-sucedido pode usar o ponteiro do objeto de dispositivo retornado para inicializar seus próprios objetos de dispositivo. Ele também pode ser usado como um argumento para IoAttachDeviceToDeviceStack, IoCallDriver e qualquer rotina que crie IRPs para drivers inferiores. O ponteiro retornado é um argumento necessário para IoCallDriver.

Essa rotina também retorna um ponteiro para o objeto de arquivo correspondente. Ao descarregar, um driver pode desreferenciar o objeto de arquivo como um meio de desreferenciar indiretamente o objeto do dispositivo. Para fazer isso, o driver chama ObDereferenceObject de sua rotina Unload, passando o ponteiro do objeto de arquivo retornado por IoGetDeviceObjectPointer. A falha ao desreferenciar o objeto de dispositivo na rotina Unload de um driver impede que o driver inferior seja descarregado. No entanto, os drivers que fecham o objeto de arquivo antes do processo de descarregamento devem fazer uma referência extra no objeto do dispositivo antes de desreferenciar o objeto de arquivo. Caso contrário, desreferenciar o objeto de arquivo pode levar a uma exclusão prematura do objeto do dispositivo.

Para obter um ponteiro para o driver de nível mais alto na pilha de driver do sistema de arquivos, um driver deve garantir que o sistema de arquivos esteja montado; se não estiver, essa rotina percorrerá a pilha do dispositivo de armazenamento. Para garantir que o sistema de arquivos esteja montado no dispositivo de armazenamento, o driver deve especificar uma máscara de acesso apropriada, como FILE_READ_DATA ou FILE_WRITE_ATTRIBUTES, no parâmetro DesiredAccess . Especificar FILE_READ_ATTRIBUTES não faz com que o sistema de arquivos seja montado.

Depois que qualquer driver de nível superior tiver se encadeado por outro driver chamando essa rotina com êxito, o driver de nível superior deve definir o campo StackSize em seu objeto de dispositivo como o do objeto de dispositivo do próximo driver de nível inferior mais um.

Os chamadores de IoGetDeviceObjectPointer devem estar em execução em IRQL = PASSIVE_LEVEL.

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Disponível a partir do Windows 2000.
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 da DDI	HwStorPortProhibitedDIs(storport), IrqlIoPassive5(wdm), PowerIrpDDis(wdm)