Compartir a través de


Función CloseHandle (handleapi.h)

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

Vea también

CreateFile

CreateFileTransacted

DeleteFile

FindClose

FindFirstFile

Funciones de identificador y objeto

Objetos kernel

Interfaz de objeto