Función CloseHandle (handleapi.h)

Artículo
08/24/2023

Cierra un identificador de objeto abierto.

Sintaxis

BOOL CloseHandle(
  [in] HANDLE hObject
);

Parámetros

[in] hObject

Identificador válido para un objeto abierto.

Valor devuelto

Si la función se realiza correctamente, el valor devuelto es distinto de cero.

Si la función no se realiza correctamente, el valor devuelto es cero. Para obtener información de error extendida, llame a GetLastError.

Si la aplicación se ejecuta en un depurador, la función producirá una excepción si recibe un valor de identificador que no es válido o un valor de pseudo-handle. Esto puede ocurrir si cierra un identificador dos veces, o si llama a CloseHandle en un identificador devuelto por la función FindFirstFile en lugar de llamar a la función FindClose .

Comentarios

La función CloseHandle cierra los identificadores de los objetos siguientes:

Access token
Dispositivo de comunicaciones
Entrada de consola
Búfer de pantalla de la consola
Evento
Archivo
Asignación de archivos
Puerto de finalización de E/S
Trabajo
Mailslot
Notificación de recursos de memoria
Mutex
Canalización con nombre
Pipe
Proceso
Semaphore
Thread
Transacción
Temporizador que se puede esperar

La documentación de las funciones que crean estos objetos indica que CloseHandle debe usarse cuando haya terminado con el objeto y lo que sucede con las operaciones pendientes en el objeto después de cerrar el identificador. En general, CloseHandle invalida el identificador de objeto especificado, disminuye el número de identificadores del objeto y realiza comprobaciones de retención de objetos. Una vez cerrado el último identificador de un objeto, el objeto se quita del sistema. Para obtener un resumen de las funciones de creador de estos objetos, consulte Objetos kernel.

Por lo general, una aplicación debe llamar a CloseHandle una vez para cada identificador que se abra. Normalmente no es necesario llamar a CloseHandle si una función que usa un identificador produce un error con ERROR_INVALID_HANDLE, ya que este error suele indicar que el identificador ya está invalidado. Sin embargo, algunas funciones usan ERROR_INVALID_HANDLE para indicar que el propio objeto ya no es válido. Por ejemplo, una función que intenta usar un identificador para un archivo de una red podría producir un error con ERROR_INVALID_HANDLE si la conexión de red está grave, ya que el objeto de archivo ya no está disponible. En este caso, la aplicación debe cerrar el identificador.

Si se realiza una transacción de un identificador, todos los identificadores enlazados a una transacción deben cerrarse antes de confirmar la transacción. Si se abrió un identificador de transacción llamando a CreateFileTransact con la marca FILE_FLAG_DELETE_ON_CLOSE, el archivo no se elimina hasta que la aplicación cierra el identificador y llama a CommitTransaction. Para obtener más información sobre los objetos de transacción, vea Trabajar con transacciones.

Cerrar un identificador de subproceso no finaliza el subproceso asociado ni quita el objeto de subproceso. Cerrar un identificador de proceso no finaliza el proceso asociado ni quita el objeto de proceso. Para quitar un objeto de subproceso, debe finalizar el subproceso y, a continuación, cerrar todos los identificadores del subproceso. Para obtener más información, consulte Terminación de un subproceso. Para quitar un objeto de proceso, debe finalizar el proceso y, a continuación, cerrar todos los identificadores del proceso. Para obtener más información, consulte Terminación de un proceso.

El cierre de un identificador a una asignación de archivos puede realizarse correctamente incluso cuando hay vistas de archivo que todavía están abiertas. Para obtener más información, vea Cerrar un objeto de asignación de archivos.

No use la función CloseHandle para cerrar un socket. En su lugar, use la función closesocket , que libera todos los recursos asociados al socket, incluido el identificador del objeto socket. Para obtener más información, consulte Cierre de sockets.

No use la función CloseHandle para cerrar un identificador en una clave del Registro abierta. En su lugar, use la función RegCloseKey . CloseHandle no cierra el identificador de la clave del Registro, pero no devuelve un error para indicar este error.

Ejemplos

dwPriorityClass = 0;
hProcess = OpenProcess( PROCESS_ALL_ACCESS, FALSE, pe32.th32ProcessID );
if( hProcess == NULL )
	printError( TEXT("OpenProcess") );
else
{
	dwPriorityClass = GetPriorityClass( hProcess );
	if( !dwPriorityClass )
	printError( TEXT("GetPriorityClass") );
	CloseHandle( hProcess );
}

Para ver este ejemplo en contexto, consulte Tomar una instantánea y ver procesos.

Requisitos

Requisito	Value
Cliente mínimo compatible	Windows 2000 Professional [aplicaciones de escritorio \| Aplicaciones para UWP]
Servidor mínimo compatible	Windows 2000 Server [aplicaciones de escritorio \| Aplicaciones para UWP]
Plataforma de destino	Windows
Encabezado	handleapi.h (incluya Windows.h)
Library	Kernel32.lib
Archivo DLL	Kernel32.dll