Função ObCloseHandle (wdm.h)

A rotina ObCloseHandle fecha um identificador de objeto.

Sintaxe

NTSTATUS ObCloseHandle(
  [in] HANDLE          Handle,
  [in] KPROCESSOR_MODE PreviousMode
);

Parâmetros

[in] Handle

Um identificador para um objeto fornecido pelo sistema de qualquer tipo.

[in] PreviousMode

Especifica o modo de processador anterior do thread que abriu o identificador. Para fechar um identificador de kernel, defina esse parâmetro como KernelMode. Para fechar um identificador de usuário, defina esse parâmetro como UserMode. Para obter mais informações sobre esses dois tipos de identificador, consulte Comentários.

Retornar valor

ObCloseHandle retornará STATUS_SUCCESS se a chamada for bem-sucedida. Os valores de retorno de erro possíveis incluem os seguintes códigos NTSTATUS.

Código de retorno	Descrição
STATUS_INVALID_HANDLE	O identificador não é um identificador válido.
STATUS_HANDLE_NOT_CLOSABLE	O thread de chamada não tem permissão para fechar o identificador.

Comentários

Um driver no modo kernel chama ObCloseHandle para fechar um identificador para qualquer tipo de objeto criado pelo kernel do Windows. Um driver deve fechar todos os identificadores abertos assim que o identificador não for mais necessário.

Depois que ObCloseHandle fechar o identificador de um objeto, o chamador deverá tratar o identificador como inválido e evitar usar o identificador para acessar o objeto. No entanto, outros identificadores podem permanecer abertos no mesmo objeto. Durante uma chamada ObCloseHandle , o sistema diminui a contagem de identificadores do objeto e verifica se o objeto pode ser excluído. O sistema não exclui o objeto até que todos os identificadores do objeto sejam fechados e todos os ponteiros contados por referência para o objeto sejam liberados.

O parâmetro PreviousMode especifica se o identificador a ser fechado é um identificador de kernel ou um identificador de usuário. Para fechar um identificador de kernel, defina PreviousMode como KernelMode. Para fechar um identificador de usuário, defina PreviousMode como UserMode.

Um identificador de kernel é um identificador aberto por um thread do sistema ou por um driver no modo kernel que atribui o atributo OBJ_KERNEL_HANDLE ao identificador. (Por exemplo, consulte a descrição do OBJ_KERNEL_HANDLE em ZwCreateFile.) Se um driver no modo kernel abrir um identificador para seu uso privado e esse driver for executado no contexto de um thread no modo de usuário, o driver deverá abrir o identificador com o atributo OBJ_KERNEL_HANDLE. Esse atributo garante que o identificador esteja inacessível para aplicativos no modo de usuário.

Um identificador de usuário é um identificador aberto por um aplicativo de modo de usuário ou por um driver no modo kernel executado no contexto de um thread no modo de usuário, mas que não abre o identificador com o atributo OBJ_KERNEL_HANDLE. Se um driver criar um identificador de usuário para ser usado por um aplicativo de modo de usuário, mas ocorrer um erro que exija que o driver feche o identificador em nome do aplicativo, o driver poderá chamar ObCloseHandle para fechar o identificador.

A rotina ZwClose é semelhante a ObCloseHandle , mas pode fechar apenas identificadores de kernel. A chamada ZwClose(hObject), que fecha o identificador de kernel hObject, tem o mesmo efeito que a chamada ObCloseHandle(hObject, KernelMode). Para obter mais informações sobre como fechar um identificador de kernel, consulte ZwClose.

Para determinar se um identificador é um identificador de kernel ou um identificador de usuário, um driver que recebe um identificador pode chamar a rotina ExGetPreviousMode . Ou o driver pode ler o campo RequestorMode da estrutura IRP que descreve a solicitação de E/S. O gerenciador de E/S define o campo RequestorMode para o modo de processador anterior do thread que solicitou a operação de E/S.

Os chamadores de ObCloseHandle não devem assumir que essa rotina aguarda automaticamente a conclusão de todas as operações de E/S pendentes antes de retornar.

Para obter mais informações, consulte Identificadores de objeto.

ObCloseHandle não é declarado em um arquivo de cabeçalho antes do Windows 7. Para usar essa rotina no driver, inclua a seguinte declaração de função no código do driver:

#if (NTDDI_VERSION < NTDDI_WIN7)
NTKERNELAPI
NTSTATUS
  ObCloseHandle(
    __in HANDLE Handle,
    __in KPROCESSOR_MODE PreviousMode
    );
#endif

Requisitos

Requisito	Valor
Plataforma de Destino	Universal
Cabeçalho	wdm.h
Biblioteca	Ntoskrnl.lib
DLL	Ntoskrnl.exe
IRQL	PASSIVE_LEVEL

Confira também

ExGetPreviousMode

IRP

ZwClose

ZwCreateFile