Función ObCloseHandle (wdm.h)

  • Artículo

La rutina ObCloseHandle cierra un identificador de objeto.

Sintaxis

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

Parámetros

[in] Handle

Identificador de un objeto proporcionado por el sistema de cualquier tipo.

[in] PreviousMode

Especifica el modo de procesador anterior del subproceso que abrió el identificador. Para cerrar un identificador de kernel, establezca este parámetro en KernelMode. Para cerrar un identificador de usuario, establezca este parámetro en UserMode. Para obtener más información sobre estos dos tipos de identificadores, vea Comentarios.

Valor devuelto

ObCloseHandle devuelve STATUS_SUCCESS si la llamada es correcta. Entre los posibles valores devueltos de error se incluyen los siguientes códigos NTSTATUS.

Código devuelto Descripción
STATUS_INVALID_HANDLE El identificador no es un identificador válido.
STATUS_HANDLE_NOT_CLOSABLE El subproceso que realiza la llamada no tiene permiso para cerrar el identificador.

Comentarios

Un controlador en modo kernel llama a ObCloseHandle para cerrar un identificador a cualquier tipo de objeto creado por el kernel de Windows. Un controlador debe cerrar todos los identificadores que se abran en cuanto el identificador ya no sea necesario.

Después de que ObCloseHandle cierre el identificador de un objeto, el autor de la llamada debe tratar el identificador como no válido y evitar el uso del identificador para acceder al objeto. Sin embargo, otros identificadores pueden permanecer abiertos en el mismo objeto. Durante una llamada a ObCloseHandle , el sistema disminuye el número de identificadores del objeto y comprueba si el objeto se puede eliminar. El sistema no elimina el objeto hasta que se cierran todos los identificadores del objeto y se liberan todos los punteros con recuento de referencias al objeto.

El parámetro PreviousMode especifica si el identificador que se va a cerrar es un identificador de kernel o un identificador de usuario. Para cerrar un identificador de kernel, establezca PreviousMode en KernelMode. Para cerrar un identificador de usuario, establezca PreviousMode en UserMode.

Un identificador de kernel es un identificador abierto por un subproceso del sistema o por un controlador en modo kernel que asigna el atributo OBJ_KERNEL_HANDLE al identificador. (Por ejemplo, vea la descripción de OBJ_KERNEL_HANDLE en ZwCreateFile). Si un controlador en modo kernel abre un identificador para su uso privado y este controlador se ejecuta en el contexto de un subproceso en modo de usuario, el controlador debe abrir el identificador con el atributo OBJ_KERNEL_HANDLE. Este atributo garantiza que el identificador no sea accesible para las aplicaciones en modo de usuario.

Un identificador de usuario es un identificador abierto por una aplicación en modo de usuario o por un controlador en modo kernel que se ejecuta en el contexto de un subproceso en modo de usuario, pero que no abre el identificador con el atributo OBJ_KERNEL_HANDLE. Si un controlador crea un identificador de usuario para que lo use una aplicación en modo de usuario, pero se produce un error que requiere que el controlador cierre el identificador en nombre de la aplicación, el controlador puede llamar a ObCloseHandle para cerrar el identificador.

La rutina ZwClose es similar a ObCloseHandle , pero solo puede cerrar los identificadores del kernel. La llamada a ZwClose(hObject), que cierra el identificador del kernel hObject, tiene el mismo efecto que la llamada a ObCloseHandle(hObject, KernelMode). Para obtener más información sobre cómo cerrar un identificador de kernel, consulte ZwClose.

Para determinar si un identificador es un identificador de kernel o un identificador de usuario, un controlador que recibe un identificador puede llamar a la rutina ExGetPreviousMode . O bien, el controlador puede leer el campo RequestorMode de la estructura IRP que describe la solicitud de E/S. El administrador de E/S establece el campo RequestorMode en el modo de procesador anterior del subproceso que solicitó la operación de E/S.

Los autores de llamadas de ObCloseHandle no deben suponer que esta rutina espera automáticamente a que se completen todas las operaciones de E/S pendientes antes de que se devuelva.

Para obtener más información, vea Identificadores de objeto.

ObCloseHandle no se declara en un archivo de encabezado anterior a Windows 7. Para usar esta rutina en el controlador, incluya la siguiente declaración de función en el código del controlador:

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

Requisitos

Requisito Value
Plataforma de destino Universal
Encabezado wdm.h
Library Ntoskrnl.lib
Archivo DLL Ntoskrnl.exe
IRQL PASSIVE_LEVEL

Consulte también

ExGetPreviousMode

IRP

ZwClose

ZwCreateFile