Fungsi WinHttpQueryHeaders (winhttp.h)

Artikel
08/27/2023

Fungsi WinHttpQueryHeaders mengambil informasi header yang terkait dengan permintaan HTTP.

Lihat juga WinHttpQueryHeadersEx, yang menawarkan cara untuk mengambil nama header dan string nilai yang diurai.

Sintaks

WINHTTPAPI BOOL WinHttpQueryHeaders(
  [in]           HINTERNET hRequest,
  [in]           DWORD     dwInfoLevel,
  [in, optional] LPCWSTR   pwszName,
  [out]          LPVOID    lpBuffer,
  [in, out]      LPDWORD   lpdwBufferLength,
  [in, out]      LPDWORD   lpdwIndex
);

Parameter

[in] hRequest

Handel permintaan HINTERNET yang dikembalikan oleh WinHttpOpenRequest. WinHttpReceiveResponse harus sudah dipanggil untuk handel ini dan telah selesai sebelum WinHttpQueryHeaders dipanggil.

[in] dwInfoLevel

Nilai tipe DWORD yang menentukan kombinasi atribut dan bendera pengubah yang tercantum di halaman Bendera Info Kueri . Atribut dan bendera pengubah ini menunjukkan bahwa informasi sedang diminta dan bagaimana informasi tersebut akan diformat.

[in, optional] pwszName

Penunjuk ke string yang berisi nama header. Jika bendera di dwInfoLevel tidak WINHTTP_QUERY_CUSTOM, atur parameter ini ke WINHTTP_HEADER_NAME_BY_INDEX.

[out] lpBuffer

Arahkan ke buffer yang menerima informasi. Mengatur parameter ini ke WINHTTP_NO_OUTPUT_BUFFER 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 nilai jenis DWORD yang menentukan panjang buffer data, dalam byte. Saat fungsi kembali, parameter ini berisi penunjuk ke nilai yang menentukan panjang informasi yang ditulis ke buffer. Saat fungsi mengembalikan string, aturan berikut berlaku.

Jika fungsi berhasil, lpdwBufferLength menentukan panjang string, dalam byte, dikurangi 2 untuk null yang mengakhiri.
Jika fungsi gagal dan ERROR_INSUFFICIENT_BUFFER dikembalikan, lpdwBufferLength menentukan jumlah byte yang harus dialokasikan aplikasi untuk menerima string.

[in, out] lpdwIndex

Penunjuk ke indeks header berbasis nol yang digunakan untuk menghitung beberapa header dengan nama yang sama. Saat memanggil fungsi, parameter ini adalah indeks header yang ditentukan untuk dikembalikan. Ketika fungsi kembali, parameter ini adalah indeks header berikutnya. Jika indeks berikutnya tidak dapat ditemukan, ERROR_WINHTTP_HEADER_NOT_FOUND dikembalikan. Atur parameter ini ke WINHTTP_NO_HEADER_INDEX untuk menentukan bahwa hanya kemunculan pertama header yang harus dikembalikan.

Mengembalikan nilai

Mengembalikan TRUE jika berhasil, atau FALSE sebaliknya. Untuk mendapatkan informasi kesalahan yang diperluas, hubungi GetLastError. Di antara kode kesalahan yang dikembalikan adalah sebagai berikut.

Kode Kesalahan	Deskripsi
ERROR_WINHTTP_HEADER_NOT_FOUND	Header yang diminta tidak dapat ditemukan.
ERROR_WINHTTP_INCORRECT_HANDLE_STATE	Operasi yang diminta tidak dapat dilakukan karena handel yang diberikan tidak dalam keadaan yang benar.
ERROR_WINHTTP_INCORRECT_HANDLE_TYPE	Jenis handel yang disediakan salah untuk operasi ini.
ERROR_WINHTTP_INTERNAL_ERROR	Terjadi kesalah internal.
ERROR_NOT_ENOUGH_MEMORY	Memori tidak cukup tersedia 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.

Secara default WinHttpQueryHeaders mengembalikan string. Namun, Anda dapat meminta data dalam bentuk struktur SYSTEMTIME atau DWORD dengan menyertakan bendera pengubah yang sesuai di dwInfoLevel. Tabel berikut ini memperlihatkan kemungkinan tipe data yang bisa dikembalikan WinHttpQueryHeaders bersama dengan bendera pengubah yang Anda gunakan untuk memilih tipe data tersebut.

Jenis Data	Bendera pengubah
LPCWSTR	Default. Tidak diperlukan bendera pengubah.
SYSTEMTIME	WINHTTP_QUERY_FLAG_SYSTEMTIME
DWORD	WINHTTP_QUERY_FLAG_NUMBER

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

Contoh

Contoh berikut menunjukkan cara mendapatkan handel HINTERNET , membuka sesi HTTP, membuat dan mengirim header permintaan, dan memeriksa header respons yang dikembalikan.

    DWORD dwSize = 0;
    LPVOID lpOutBuffer = NULL;
    BOOL  bResults = FALSE;
    HINTERNET hSession = NULL,
              hConnect = NULL,
              hRequest = NULL;

    // Use WinHttpOpen to obtain a session handle.
    hSession = WinHttpOpen(  L"A WinHTTP Example Program/1.0",
                             WINHTTP_ACCESS_TYPE_DEFAULT_PROXY,
                             WINHTTP_NO_PROXY_NAME,
                             WINHTTP_NO_PROXY_BYPASS, 0);

    // Specify an HTTP server.
    if (hSession)
        hConnect = WinHttpConnect( hSession, L"www.microsoft.com",
                                   INTERNET_DEFAULT_HTTP_PORT, 0);

    // Create an HTTP request handle.
    if (hConnect)
        hRequest = WinHttpOpenRequest( hConnect, L"GET", NULL,
                                       NULL, WINHTTP_NO_REFERER,
                                       WINHTTP_DEFAULT_ACCEPT_TYPES,
                                       0);

    // Send a request.
    if (hRequest)
        bResults = WinHttpSendRequest( hRequest,
                                       WINHTTP_NO_ADDITIONAL_HEADERS,
                                       0, WINHTTP_NO_REQUEST_DATA, 0,
                                       0, 0);

    // End the request.
    if (bResults)
        bResults = WinHttpReceiveResponse( hRequest, NULL);

    // First, use WinHttpQueryHeaders to obtain the size of the buffer.
    if (bResults)
    {
        WinHttpQueryHeaders( hRequest, WINHTTP_QUERY_RAW_HEADERS_CRLF,
                             WINHTTP_HEADER_NAME_BY_INDEX, NULL,
                             &dwSize, WINHTTP_NO_HEADER_INDEX);

        // Allocate memory for the buffer.
        if( GetLastError( ) == ERROR_INSUFFICIENT_BUFFER )
        {
            lpOutBuffer = new WCHAR[dwSize/sizeof(WCHAR)];

            // Now, use WinHttpQueryHeaders to retrieve the header.
            bResults = WinHttpQueryHeaders( hRequest,
                                       WINHTTP_QUERY_RAW_HEADERS_CRLF,
                                       WINHTTP_HEADER_NAME_BY_INDEX,
                                       lpOutBuffer, &dwSize,
                                       WINHTTP_NO_HEADER_INDEX);
        }
    }

    // Print the header contents.
    if (bResults)
        printf("Header contents: \n%S",lpOutBuffer);

    // Free the allocated memory.
    delete [] lpOutBuffer;

    // Report any errors.
    if (!bResults)
        printf("Error %d has occurred.\n",GetLastError());

    // Close any open handles.
    if (hRequest) WinHttpCloseHandle(hRequest);
    if (hConnect) WinHttpCloseHandle(hConnect);
    if (hSession) WinHttpCloseHandle(hSession);

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.