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
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 |