Fungsi WinHttpSetStatusCallback (winhttp.h)

Artikel
03/15/2023

Fungsi WinHttpSetStatusCallback menyiapkan fungsi panggilan balik yang bisa dipanggil WinHTTP saat kemajuan dibuat selama operasi.

Sintaks

WINHTTPAPI WINHTTP_STATUS_CALLBACK WinHttpSetStatusCallback(
  [in] HINTERNET               hInternet,
  [in] WINHTTP_STATUS_CALLBACK lpfnInternetCallback,
  [in] DWORD                   dwNotificationFlags,
  [in] DWORD_PTR               dwReserved
);

Parameter

[in] hInternet

HINTERNET menangani panggilan balik yang akan diatur.

[in] lpfnInternetCallback

Arahkan ke fungsi panggilan balik untuk memanggil saat kemajuan dibuat. Atur ini ke NULL untuk menghapus fungsi panggilan balik yang ada. Untuk informasi selengkapnya tentang fungsi panggilan balik, lihat WINHTTP_STATUS_CALLBACK.

[in] dwNotificationFlags

Nilai bilangan bulat panjang yang tidak ditandatangani yang menentukan bendera untuk menunjukkan peristiwa mana yang mengaktifkan fungsi panggilan balik.

Nilai yang mungkin adalah sebagai berikut.

Nilai	Makna
WINHTTP_CALLBACK_FLAG_ALL_COMPLETIONS	Mengaktifkan setelah pemberitahuan penyelesaian apa pun. Bendera ini menentukan bahwa semua pemberitahuan yang diperlukan untuk operasi baca atau tulis digunakan. Lihat WINHTTP_STATUS_CALLBACK untuk daftar penyelesaian.
WINHTTP_CALLBACK_FLAG_ALL_NOTIFICATIONS	Mengaktifkan pemberitahuan perubahan status apa pun termasuk penyelesaian. Lihat WINHTTP_STATUS_CALLBACK untuk daftar pemberitahuan.
WINHTTP_CALLBACK_FLAG_RESOLVE_NAME	Mengaktifkan pada awal dan menyelesaikan resolusi nama.
WINHTTP_CALLBACK_FLAG_CONNECT_TO_SERVER	Aktifkan saat memulai dan menyelesaikan koneksi ke server.
WINHTTP_CALLBACK_FLAG_DETECTING_PROXY	Mengaktifkan saat mendeteksi server proksi.
WINHTTP_CALLBACK_FLAG_DATA_AVAILABLE	Mengaktifkan saat menyelesaikan kueri untuk data.
WINHTTP_CALLBACK_FLAG_HEADERS_AVAILABLE	Aktifkan ketika header respons tersedia untuk diambil.
WINHTTP_CALLBACK_FLAG_READ_COMPLETE	Mengaktifkan setelah menyelesaikan operasi baca data.
WINHTTP_CALLBACK_FLAG_REQUEST_ERROR	Mengaktifkan ketika terjadi kesalahan asinkron.
WINHTTP_CALLBACK_FLAG_SEND_REQUEST	Mengaktifkan saat memulai dan menyelesaikan pengiriman header permintaan dengan WinHttpSendRequest.
WINHTTP_CALLBACK_FLAG_SENDREQUEST_COMPLETE	Mengaktifkan saat header permintaan telah dikirim dengan WinHttpSendRequest.
WINHTTP_CALLBACK_FLAG_WRITE_COMPLETE	Mengaktifkan setelah menyelesaikan operasi posting data.
WINHTTP_CALLBACK_FLAG_RECEIVE_RESPONSE	Mengaktifkan pada awal dan menyelesaikan penerimaan sumber daya dari server HTTP.
WINHTTP_CALLBACK_FLAG_CLOSE_CONNECTION	Mengaktifkan saat memulai dan menyelesaikan penutupan koneksi HTTP.
WINHTTP_CALLBACK_FLAG_HANDLES	Mengaktifkan saat handel HINTERNET dibuat atau ditutup.
WINHTTP_CALLBACK_FLAG_REDIRECT	Mengaktifkan saat permintaan dialihkan.
WINHTTP_CALLBACK_FLAG_INTERMEDIATE_RESPONSE	Mengaktifkan saat menerima pesan kode status perantara (tingkat 100) dari server.
WINHTTP_CALLBACK_FLAG_SECURE_FAILURE	Mengaktifkan pada kegagalan koneksi yang aman.

[in] dwReserved

Parameter ini dicadangkan dan harus NULL.

Nilai kembali

Jika berhasil, mengembalikan penunjuk ke fungsi panggilan balik status yang ditentukan sebelumnya atau NULL jika tidak ada fungsi panggilan balik status yang ditentukan sebelumnya. Mengembalikan WINHTTP_INVALID_STATUS_CALLBACK jika fungsi panggilan balik tidak dapat diinstal. Untuk informasi kesalahan yang diperluas, hubungi GetLastError. Di antara kode kesalahan yang dikembalikan adalah sebagai berikut.

Kode Kesalahan	Deskripsi
ERROR_WINHTTP_INCORRECT_HANDLE_TYPE	Jenis handel yang disediakan salah untuk operasi ini.
ERROR_WINHTTP_INTERNAL_ERROR	Terjadi kesalah internal.
ERROR_NOT_ENOUGH_MEMORY	Tidak tersedia cukup memori untuk menyelesaikan operasi yang diminta. (Kode galat Windows)

Keterangan

Jika Anda mengatur panggilan balik pada handel sesi sebelum membuat handel permintaan, handel permintaan mewarisi penunjuk fungsi panggilan balik dari sesi induknya.

Bahkan ketika WinHTTP digunakan dalam mode asinkron (yaitu, ketika WINHTTP_FLAG_ASYNC telah diatur di WinHttpOpen), fungsi ini beroperasi secara sinkron. Nilai yang dikembalikan menunjukkan keberhasilan atau kegagalan. Untuk mendapatkan informasi kesalahan yang diperluas, hubungi GetLastError.

Fungsi sinkron dan asinkron menggunakan fungsi panggilan balik untuk menunjukkan kemajuan permintaan, seperti menyelesaikan nama, menyambungkan ke server, dan sebagainya. Fungsi panggilan balik diperlukan untuk operasi asinkron.

Fungsi panggilan balik dapat diatur pada handel apa pun dan diwarisi oleh handel turunan. Fungsi panggilan balik dapat diubah menggunakan WinHttpSetStatusCallback, asalkan tidak ada permintaan tertunda yang perlu menggunakan nilai panggilan balik sebelumnya. Namun, mengubah fungsi panggilan balik pada handel tidak mengubah panggilan balik pada handel turunan, seperti yang dikembalikan oleh WinHttpConnect. Anda harus mengubah fungsi panggilan balik di setiap tingkat.

Banyak fungsi WinHTTP melakukan beberapa operasi di jaringan. Setiap operasi dapat memakan waktu untuk diselesaikan dan masing-masing dapat gagal.

Setelah memulai fungsi WinHttpSetStatusCallback , fungsi panggilan balik dapat diakses dari dalam WinHTTP untuk memantau operasi jaringan intensif waktu.

Pada akhir pemrosesan asinkron, aplikasi dapat mengatur fungsi panggilan balik ke NULL. Ini mencegah aplikasi klien menerima pemberitahuan tambahan.

Cuplikan kode berikut menunjukkan metode yang direkomendasikan untuk mengatur fungsi panggilan balik ke NULL.

WinHttpSetStatusCallback( hOpen,
                          NULL,
                          WINHTTP_CALLBACK_FLAG_ALL_NOTIFICATIONS,
                          NULL );

Namun, perhatikan bahwa WinHTTP tidak menyinkronkan WinHttpSetStatusCallback dengan utas pekerja. Jika panggilan balik yang berasal dari utas lain sedang berlangsung saat aplikasi memanggil WinHttpSetStatusCallback, aplikasi masih menerima pemberitahuan panggilan balik bahkan setelah WinHttpSetStatusCallback berhasil mengatur fungsi panggilan balik ke NULL dan kembali.

Catatan Untuk Windows XP dan Windows 2000, lihat bagian Persyaratan Run-Time di halaman mulai WinHttp.

Contoh

Contoh berikut menunjukkan cara menginstal fungsi panggilan balik untuk fungsi WinHTTP asinkron. Contoh mengasumsikan bahwa fungsi WINHTTP_STATUS_CALLBACK bernama "AsyncCallback( )" sebelumnya telah diimplementasikan:

    // Use WinHttpOpen to obtain an HINTERNET handle.
    HINTERNET hSession = WinHttpOpen(L"A WinHTTP Example Program/1.0", 
                                    WINHTTP_ACCESS_TYPE_DEFAULT_PROXY,
                                    WINHTTP_NO_PROXY_NAME, 
                                    WINHTTP_NO_PROXY_BYPASS, 0);
    if (hSession)
    {
        // Install the status callback function.
        WINHTTP_STATUS_CALLBACK isCallback = WinHttpSetStatusCallback( hSession,
                                               (WINHTTP_STATUS_CALLBACK)AsyncCallback,
                                               WINHTTP_CALLBACK_FLAG_ALL_NOTIFICATIONS, 
                                               NULL);
                                               
        // Place additional code here.
    
        // When finished, release the HINTERNET handle.
        WinHttpCloseHandle(hSession);
    }
    else
    {
        printf("Error %u in WinHttpOpen.\n", GetLastError());
    }

Persyaratan

Persyaratan	Nilai
Klien minimum yang didukung	Windows XP, Windows 2000 Professional dengan SP3 [hanya aplikasi desktop]
Server minimum yang didukung	Windows Server 2003, Windows 2000 Server dengan SP3 [hanya aplikasi desktop]
Target Platform	Windows
Header	winhttp.h
Pustaka	Winhttp.lib
DLL	Winhttp.dll
Redistribusi	WinHTTP 5.0 dan Internet Explorer 5.01 atau yang lebih baru pada Windows XP dan Windows 2000.