Fungsi WinHttpQueryOption (winhttp.h)

Artikel
03/15/2023

Fungsi WinHttpQueryOption meminta opsi Internet pada handel yang ditentukan.

Sintaks

WINHTTPAPI BOOL WinHttpQueryOption(
  [in]      HINTERNET hInternet,
  [in]      DWORD     dwOption,
  [out]     LPVOID    lpBuffer,
  [in, out] LPDWORD   lpdwBufferLength
);

Parameter

[in] hInternet

Handel HINTERNET untuk mengkueri informasi. Perhatikan bahwa ini dapat berupa handel Sesi atau handel Permintaan, tergantung pada opsi apa yang sedang dikueri; lihat topik Bendera Opsi untuk menentukan handel mana yang sesuai untuk digunakan dalam mengkueri opsi tertentu.

[in] dwOption

Nilai bilangan bulat panjang yang tidak ditandatangani yang berisi opsi Internet untuk kueri. Ini bisa menjadi salah satu nilai Bendera Opsi .

[out] lpBuffer

Penunjuk ke buffer yang menerima pengaturan opsi. String yang dikembalikan oleh fungsi WinHttpQueryOption dialokasikan secara global, sehingga aplikasi panggilan harus membebaskan string secara global saat selesai menggunakannya. Mengatur parameter ini ke NULL menyebabkan fungsi ini mengembalikan FALSE. Memanggil GetLastError kemudian mengembalikan ERROR_INSUFFICIENT_BUFFER dan lpdwBufferLength berisi jumlah byte yang diperlukan untuk menyimpan informasi yang diminta.

[in, out] lpdwBufferLength

Penunjuk ke variabel bilangan bulat panjang yang tidak ditandatangani yang berisi panjang lpBuffer, dalam byte. Ketika fungsi kembali, variabel menerima panjang data yang ditempatkan ke dalam lpBuffer. Jika GetLastError mengembalikan ERROR_INSUFFICIENT_BUFFER, parameter ini menerima jumlah byte yang diperlukan untuk menyimpan informasi yang diminta.

Mengembalikan nilai

Mengembalikan TRUE jika berhasil, atau FALSE sebaliknya. Untuk mendapatkan pesan kesalahan tertentu, panggil GetLastError. Di antara kode kesalahan yang dikembalikan adalah sebagai berikut:

Kode Kesalahan	Deskripsi
ERROR_WINHTTP_INCORRECT_HANDLE_STATE	Operasi yang diminta tidak dapat dilakukan karena handel yang diberikan tidak dalam keadaan benar.
ERROR_WINHTTP_INCORRECT_HANDLE_TYPE	Jenis handel yang disediakan salah untuk operasi ini.
ERROR_WINHTTP_INTERNAL_ERROR	Terjadi kesalah internal.
ERROR_WINHTTP_INVALID_OPTION	Nilai opsi yang tidak valid ditentukan.
ERROR_NOT_ENOUGH_MEMORY	Tidak tersedia cukup memori untuk menyelesaikan operasi yang diminta. (Kode galat Windows)

Keterangan

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.

GetLastError mengembalikan ERROR_INVALID_PARAMETER jika bendera opsi yang tidak valid untuk jenis handel yang ditentukan diteruskan ke parameter dwOption .

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

Contoh

Contoh ini menunjukkan pengambilan nilai batas waktu koneksi:

    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 di Windows XP dan Windows 2000.