Fungsi CloseHandle (handleapi.h)

Artikel
08/24/2023

Menutup handel objek terbuka.

Sintaks

BOOL CloseHandle(
  [in] HANDLE hObject
);

Parameter

[in] hObject

Handel yang valid ke objek yang terbuka.

Mengembalikan nilai

Jika fungsi berhasil, nilai yang dikembalikan bukan nol.

Jika fungsi gagal, nilai yang dikembalikan adalah nol. Untuk mendapatkan informasi kesalahan yang diperluas, hubungi GetLastError.

Jika aplikasi berjalan di bawah debugger, fungsi akan memberikan pengecualian jika menerima nilai handel yang tidak valid atau nilai handel semu. Ini dapat terjadi jika Anda menutup handel dua kali, atau jika Anda memanggil CloseHandle pada handel yang dikembalikan oleh fungsi FindFirstFile alih-alih memanggil fungsi FindClose .

Keterangan

Fungsi CloseHandle menutup handel ke objek berikut:

Token akses
Perangkat komunikasi
Input konsol
Buffer layar konsol
Kejadian
File
Pemetaan file
Port penyelesaian I/O
Tugas
Mailslot
Pemberitahuan sumber daya memori
Mutex
Pipa yang dinamai
Pipa
Proses
Semaphore
Rangkaian
Transaksi
Timer yang dapat ditunda

Dokumentasi untuk fungsi yang membuat objek ini menunjukkan bahwa CloseHandle harus digunakan ketika Anda selesai dengan objek , dan apa yang terjadi pada operasi yang tertunda pada objek setelah handel ditutup. Secara umum, CloseHandle membatalkan handel objek yang ditentukan, mengurangi jumlah handel objek, dan melakukan pemeriksaan retensi objek. Setelah handel terakhir ke objek ditutup, objek dihapus dari sistem. Untuk ringkasan fungsi pembuat untuk objek ini, lihat Objek Kernel.

Umumnya, aplikasi harus memanggil CloseHandle sekali untuk setiap handel yang terbuka. Biasanya tidak perlu memanggil CloseHandle jika fungsi yang menggunakan handel gagal dengan ERROR_INVALID_HANDLE, karena kesalahan ini biasanya menunjukkan bahwa handel sudah tidak valid. Namun, beberapa fungsi menggunakan ERROR_INVALID_HANDLE untuk menunjukkan bahwa objek itu sendiri tidak lagi valid. Misalnya, fungsi yang mencoba menggunakan handel ke file pada jaringan mungkin gagal dengan ERROR_INVALID_HANDLE jika koneksi jaringan terputus, karena objek file tidak lagi tersedia. Dalam hal ini, aplikasi harus menutup handel.

Jika handel ditransaksikan, semua handel yang terikat ke transaksi harus ditutup sebelum transaksi dilakukan. Jika handel yang ditransaksikan dibuka dengan memanggil CreateFileTransacted dengan bendera FILE_FLAG_DELETE_ON_CLOSE, file tidak dihapus sampai aplikasi menutup handel dan memanggil CommitTransaction. Untuk informasi selengkapnya tentang objek yang ditransaksikan, lihat Bekerja Dengan Transaksi.

Menutup handel utas tidak mengakhiri utas terkait atau menghapus objek utas. Menutup handel proses tidak menghentikan proses terkait atau menghapus objek proses. Untuk menghapus objek utas, Anda harus mengakhiri utas, lalu menutup semua handel ke utas. Untuk informasi selengkapnya, lihat Mengakhiri Utas. Untuk menghapus objek proses, Anda harus menghentikan proses, lalu menutup semua handel ke proses. Untuk informasi selengkapnya, lihat Mengakhiri Proses.

Menutup handel ke pemetaan file dapat berhasil bahkan ketika ada tampilan file yang masih terbuka. Untuk informasi selengkapnya, lihat Menutup Objek Pemetaan File.

Jangan gunakan fungsi CloseHandle untuk menutup soket. Sebagai gantinya, gunakan fungsi closesocket , yang merilis semua sumber daya yang terkait dengan soket termasuk handel ke objek soket. Untuk informasi selengkapnya, lihat Penutupan Soket.

Jangan gunakan fungsi CloseHandle untuk menutup handel ke kunci registri terbuka. Sebagai gantinya, gunakan fungsi RegCloseKey . CloseHandle tidak menutup handel ke kunci registri, tetapi tidak mengembalikan kesalahan untuk menunjukkan kegagalan ini.

Contoh

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 );
}

Untuk melihat contoh ini dalam konteks, lihat Mengambil Rekam Jepret dan Menampilkan Proses.

Persyaratan

Persyaratan	Nilai
Klien minimum yang didukung	Windows 2000 Professional [aplikasi desktop \| Aplikasi UWP]
Server minimum yang didukung	Windows 2000 Server [aplikasi desktop \| Aplikasi UWP]
Target Platform	Windows
Header	handleapi.h (sertakan Windows.h)
Pustaka	Kernel32.lib
DLL	Kernel32.dll