Fungsi WinHttpOpen (winhttp.h)

Artikel
03/15/2023

Fungsi WinHttpOpen menginisialisasi, untuk aplikasi, penggunaan fungsi WinHTTP dan mengembalikan handel sesi WinHTTP.

Sintaks

WINHTTPAPI HINTERNET WinHttpOpen(
  [in, optional] LPCWSTR pszAgentW,
  [in]           DWORD   dwAccessType,
  [in]           LPCWSTR pszProxyW,
  [in]           LPCWSTR pszProxyBypassW,
  [in]           DWORD   dwFlags
);

Parameter

[in, optional] pszAgentW

Penunjuk ke variabel string yang berisi nama aplikasi atau entitas yang memanggil fungsi WinHTTP. Nama ini digunakan sebagai agen pengguna dalam protokol HTTP.

[in] dwAccessType

Jenis akses yang diperlukan. Ini bisa menjadi salah satu nilai berikut.

Nilai	Makna
WINHTTP_ACCESS_TYPE_NO_PROXY	Menyelesaikan semua nama host secara langsung tanpa proksi.
WINHTTP_ACCESS_TYPE_DEFAULT_PROXY	Penting Penggunaan opsi ini tidak digunakan lagi pada Windows 8.1 dan yang lebih baru. Gunakan WINHTTP_ACCESS_TYPE_AUTOMATIC_PROXY sebagai gantinya. Mengambil proksi statis atau konfigurasi langsung dari registri. WINHTTP_ACCESS_TYPE_DEFAULT_PROXY tidak mewarisi pengaturan proksi browser. Konfigurasi proksi WinHTTP diatur oleh salah satu mekanisme ini. PerintahNetsh.exe pada Windows Vista dan Windows Server 2008 atau yang lebih baru. Utilitas proxycfg.exe pada Windows XP dan Windows Server 2003 atau yang lebih lama. WinHttpSetDefaultProxyConfiguration di semua platform.
WINHTTP_ACCESS_TYPE_NAMED_PROXY	Meneruskan permintaan ke proksi kecuali daftar bypass proksi disediakan dan nama yang akan diselesaikan melewati proksi. Dalam hal ini, fungsi ini menggunakan nilai yang diteruskan untuk pwszProxyName dan pwszProxyBypass.
WINHTTP_ACCESS_TYPE_AUTOMATIC_PROXY	Menggunakan pengaturan proksi sistem dan per pengguna (termasuk konfigurasi proksi Internet Explorer) untuk menentukan proksi/proksi mana yang akan digunakan. Secara otomatis mencoba menangani failover antara beberapa proksi, konfigurasi proksi yang berbeda per antarmuka, dan autentikasi. Didukung di Windows 8.1 dan yang lebih baru.

[in] pszProxyW

Penunjuk ke variabel string yang berisi nama server proksi yang akan digunakan saat akses proksi ditentukan dengan mengatur dwAccessType ke WINHTTP_ACCESS_TYPE_NAMED_PROXY. Fungsi WinHTTP hanya mengenali proksi jenis CERN untuk HTTP. Jika dwAccessType tidak diatur ke WINHTTP_ACCESS_TYPE_NAMED_PROXY, parameter ini harus diatur ke WINHTTP_NO_PROXY_NAME.

[in] pszProxyBypassW

Penunjuk ke variabel string yang berisi daftar nama host atau alamat IP yang dibatasi titik koma opsional, atau keduanya, yang tidak boleh dirutekan melalui proksi ketika dwAccessType diatur ke WINHTTP_ACCESS_TYPE_NAMED_PROXY. Daftar dapat berisi karakter kartubebas. Jangan gunakan string kosong, karena fungsi WinHttpOpen menggunakannya sebagai daftar bypass proksi. Jika parameter ini menentukan makro "<lokal>" dalam daftar sebagai satu-satunya entri, fungsi ini melewati nama host apa pun yang tidak berisi titik. Jika dwAccessType tidak diatur ke WINHTTP_ACCESS_TYPE_NAMED_PROXY, parameter ini harus diatur ke WINHTTP_NO_PROXY_BYPASS.

[in] dwFlags

Nilai bilangan bulat panjang yang tidak ditandatangani yang berisi bendera yang menunjukkan berbagai opsi yang memengaruhi perilaku fungsi ini. Parameter ini dapat memiliki nilai berikut.

Nilai	Makna
WINHTTP_FLAG_ASYNC	Gunakan fungsi WinHTTP secara asinkron. Secara default, semua fungsi WinHTTP yang menggunakan handel HINTERNET yang dikembalikan dilakukan secara sinkron. Saat bendera ini diatur, pemanggil perlu menentukan fungsi panggilan balik melalui WinHttpSetStatusCallback.
WINHTTP_FLAG_SECURE_DEFAULTS	Saat bendera ini diatur, WinHttp akan memerlukan penggunaan TLS 1.2 atau yang lebih baru. Jika penelepon mencoba mengaktifkan versi TLS yang lebih lama dengan mengatur WINHTTP_OPTION_SECURE_PROTOCOLS, pemanggil akan gagal dengan ERROR_ACCESS_DENIED. Selain itu, fallback TLS akan dinonaktifkan. Perhatikan bahwa mengatur bendera ini juga mengatur bendera WINHTTP_FLAG_ASYNC.

Nilai kembali

Mengembalikan handel sesi yang valid jika berhasil, atau NULL sebaliknya. Untuk mengambil informasi kesalahan yang diperluas, panggil GetLastError. Di antara kode kesalahan yang dikembalikan adalah sebagai berikut.

Kode Kesalahan	Deskripsi
ERROR_WINHTTP_INTERNAL_ERROR	Terjadi kesalah internal.
ERROR_NOT_ENOUGH_MEMORY	Memori tidak cukup tersedia untuk menyelesaikan operasi yang diminta. (Kode galat Windows)

Keterangan

Kami sangat menyarankan Anda menggunakan WinHTTP dalam mode asinkron (yaitu, ketika WINHTTP_FLAG_ASYNC telah diatur di WinHttpOpen, sehingga penggunaan HINTERNET yang dikembalikan menjadi asinkron). Nilai yang dikembalikan menunjukkan keberhasilan atau kegagalan. Untuk mengambil informasi kesalahan yang diperluas, panggil GetLastError.

Fungsi WinHttpOpen adalah fungsi WinHTTP pertama yang dipanggil oleh aplikasi. Ini menginisialisasi struktur data WinHTTP internal dan mempersiapkan panggilan di masa mendatang dari aplikasi. Ketika aplikasi selesai menggunakan fungsi WinHTTP, aplikasi harus memanggil WinHttpCloseHandle untuk membebaskan handel sesi dan sumber daya terkait.

Aplikasi dapat melakukan sejumlah panggilan ke WinHttpOpen, meskipun satu panggilan biasanya cukup. Setiap panggilan ke WinHttpBuka membuka konteks sesi baru. Karena data pengguna tidak dibagi antara beberapa konteks sesi, aplikasi yang membuat permintaan atas nama beberapa pengguna harus membuat sesi terpisah untuk setiap pengguna, sehingga tidak berbagi cookie dan status autentikasi khusus pengguna. Aplikasi harus menentukan perilaku terpisah untuk setiap instans WinHttpOpen , seperti server proksi yang berbeda yang dikonfigurasi untuk masing-masing instans.

Setelah aplikasi panggilan selesai menggunakan handel HINTERNET yang dikembalikan oleh WinHttpOpen, aplikasi harus ditutup menggunakan fungsi WinHttpCloseHandle .

Catatan Untuk Windows XP dan Windows 2000, lihat Persyaratan Run-Time.

Contoh

Contoh kode berikut menunjukkan cara mengambil nilai batas waktu koneksi default.


    DWORD data;
    DWORD dwSize = sizeof(DWORD);

    // 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)
    {


        // Use WinHttpQueryOption to retrieve internet options.
        if (WinHttpQueryOption( hSession, 
                                WINHTTP_OPTION_CONNECT_TIMEOUT, 
                                &data, &dwSize))
        {
            printf("Connection timeout: %u ms\n\n",data);
        }
        else
        {
            printf( "Error %u in WinHttpQueryOption.\n", 
                    GetLastError());
        }        
        
        // When finished, release the HINTERNET handle.
        WinHttpCloseHandle(hSession);
    }
    else
    {
        printf("Error %u in WinHttpOpen.\n", GetLastError());
    }

Persyaratan


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.

Lihat juga

Tentang Microsoft Windows HTTP Services (WinHTTP)

Versi WinHTTP

WinHttpCloseHandle

Bagikan melalui