Função IoGetDeviceObjectPointer (wdm.h)
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) |