Handel HINTERNET di WinHTTP

Microsoft Windows HTTP Services (WinHTTP) menggunakan handel untuk melacak pengaturan dan informasi yang diperlukan saat menggunakan protokol HTTP. Setiap handel mempertahankan informasi yang berkaitan dengan sesi HTTP, koneksi dengan server HTTP, atau sumber daya tertentu. Topik ini menjelaskan berbagai jenis handel, konvensi penamaan untuk handel ini, dan struktur hierarkisnya.

• Tentang handel HINTERNET
• Handel penamaan
• Menangani hierarki
• Penjelasan tentang hierarki handel

Tentang handel HINTERNET

Handel yang dibuat dan digunakan oleh WinHTTP disebut handel HINTERNET . Fungsi WinHTTP mengembalikan handel HINTERNET yang tidak dapat dipertukarkan dengan handel lain, sehingga tidak dapat digunakan dengan fungsi seperti ReadFile atau CloseHandle. Demikian pula, handel lain tidak dapat digunakan dengan fungsi WinHTTP. Misalnya, handel yang dikembalikan oleh CreateFile tidak dapat diteruskan ke WinHttpReadData. Handel HINTERNET ini tidak dapat ditutup saat panggilan API menggunakan handel sedang berlangsung. Untuk menghindari kondisi balapan, aplikasi harus melindungi handel dan mencegahnya ditutup selama panggilan API sedang berlangsung.

Fungsi Microsoft Win32 Internet (WinInet) juga menggunakan handel HINTERNET . Namun, handel yang digunakan dalam fungsi WinInet tidak dapat dipertukarkan dengan handel yang digunakan dalam fungsi WinHTTP. Untuk informasi selengkapnya tentang WinInet, lihat Tentang WinINet.

Fungsi WinHttpCloseHandle menutup handel WinHTTP HINTERNET .

Handel penamaan

Di seluruh dokumentasi WinHTTP, deskripsi fungsi dalam antarmuka pemrograman aplikasi (API) dan kode sampel menunjukkan pembuatan dan penggunaan berbagai jenis handel HINTERNET . Untuk melacak berbagai jenis handel yang tersedia, penamaan handel ini konsisten. Tabel berikut menunjukkan pengidentifikasi yang digunakan oleh konvensi dalam dokumentasi.

Jenis handel	Handel pembuatan fungsi	Pengidentifikasi
Handel generik	WinHttpBuka, WinHttpConnect, atau WinHttpOpenRequest	hInternet
Handel sesi	WinHttpBuka	hSession
Handel koneksi	WinHttpConnect	hConnect
Handel permintaan	WinHttpOpenRequest	hRequest
Handel Soket Web	WinHttpWebSocketCompleteUpgrade	hWebSocket

Menangani hierarki

Handel HINTERNET dipertahankan dalam hierarki. Handel yang dikembalikan oleh WinHttpOpen adalah handel HINTERNET sesi. Memanggil WinHttpBuka menginisialisasi fungsi WinHTTP dan memulai konteks sesi yang mempertahankan informasi dan pengaturan pengguna sepanjang masa pakai handel sesi. WinHttpConnect menentukan server HTTP atau HTTPS target dan membuat handel HINTERNET koneksi. Secara default, handel koneksi mewarisi pengaturan untuk handel sesi. Setiap sumber daya yang ditentukan dengan panggilan ke WinHttpOpenRequest diberi handel HINTERNET permintaan.

Diagram berikut mengilustrasikan hierarki handel HINTERNET . Setiap kotak dalam diagram mewakili fungsi WinHTTP yang mengembalikan gagang HINTERNET .

Setelah menutup handel, aplikasi harus siap untuk menerima pemberitahuan panggilan balik pada handel hingga nilai WINHTTP_CALLBACK_STATUS_HANDLE_CLOSED akhir dikembalikan untuk menunjukkan bahwa handel ditutup sepenuhnya (atau sampai aplikasi melakukan sinkronisasi yang setara sendiri, seperti melacak dan menunggu panggilan balik dari operasi asinkron yang tertunda dan memastikan tidak ada operasi lebih lanjut yang dicoba menggunakan handel tersebut).

Handel sesi disebut induk dari setiap handel koneksi yang digunakan untuk membuat; demikian juga, handel koneksi dan handel sesi induknya disebut induk dari setiap handel permintaan yang digunakan untuk membuat handel koneksi.

Ketika handel induk ditutup, setiap anak yang dimilikinya secara tidak langsung tidak valid meskipun tidak menutup diri, dan permintaan berikutnya yang menggunakannya gagal dengan kesalahan ERROR_INVALID_HANDLE. Permintaan asinkron yang tertunda tidak dapat diandalkan untuk diselesaikan dengan benar.

Diagram berikut ini memperlihatkan fungsi yang menggunakan handel HINTERNET yang dibuat oleh WinHttpOpenRequest. Kotak berbayang mewakili fungsi WinHTTP yang membuat gagang, dan kotak biasa memperlihatkan fungsi yang menggunakan handel HINTERNET tersebut. Diagram juga diatur untuk memperlihatkan urutan fungsi WinHTTP biasanya dipanggil.

Penjelasan tentang hierarki handel

Pertama, handel sesi dibuat dengan WinHttpOpen. WinHttpConnect memerlukan handel sesi sebagai parameter pertamanya dan mengembalikan handel koneksi untuk server tertentu. Handel permintaan dibuat oleh WinHttpOpenRequest, yang menggunakan handel koneksi yang dibuat oleh WinHttpConnect. Jika aplikasi memilih untuk menambahkan header tambahan ke permintaan, atau jika perlu bagi aplikasi untuk mengatur kredensial untuk autentikasi, WinHttpAddRequestHeaders dan WinHttpSetCredentials dapat dipanggil menggunakan handel permintaan ini. Permintaan dikirim oleh WinHttpSendRequest, yang menggunakan handel permintaan. Setelah mengirim permintaan, data tambahan dapat dikirim ke server menggunakan WinHttpWriteData, atau aplikasi dapat langsung melompat ke WinHttpReceiveResponse untuk menentukan bahwa tidak ada informasi lagi yang dikirim ke server. Pada titik ini, tergantung pada tujuan aplikasi, handel permintaan dapat digunakan untuk memanggil WinHttpQueryHeaders, WinHttpQueryAuthSchemes, atau mengambil sumber daya dengan WinHttpQueryDataAvailable dan WinHttpReadData.

Soket web dalam hierarki handel

Handel soket web mewarisi dari pegangan koneksi dan sesi, dan menempati posisi yang sama dalam hierarki handel seperti yang dilakukan handel permintaan. Untuk membuat handel soket web, handel permintaan harus ada; tetapi setelah handel soket web dibuat, permintaan dapat ditutup, dan handel soket web akan terus berfungsi.