Fungsi WinHttpQueryDataAvailable (winhttp.h)

Artikel
03/15/2023

Fungsi WinHttpQueryDataAvailable mengembalikan jumlah data, dalam byte, tersedia untuk dibaca dengan WinHttpReadData.

Sintaks

WINHTTPAPI BOOL WinHttpQueryDataAvailable(
  [in]  HINTERNET hRequest,
  [out] LPDWORD   lpdwNumberOfBytesAvailable
);

Parameter

[in] hRequest

Handel HINTERNET valid yang dikembalikan oleh WinHttpOpenRequest. WinHttpReceiveResponse harus dipanggil untuk handel ini dan telah selesai sebelum WinHttpQueryDataAvailable dipanggil.

[out] lpdwNumberOfBytesAvailable

Penunjuk ke variabel bilangan bulat panjang yang tidak ditandatangani yang menerima jumlah byte yang tersedia. Ketika WinHTTP digunakan dalam mode asinkron, selalu atur parameter ini ke NULL dan ambil data dalam fungsi panggilan balik; tidak melakukannya dapat menyebabkan kesalahan memori.

Menampilkan nilai

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

Kode Kesalahan	Deskripsi
ERROR_WINHTTP_CONNECTION_ERROR	Koneksi dengan server telah direset atau dihentikan, atau protokol SSL yang tidak kompatibel ditemukan. Misalnya, WinHTTP versi 5.1 tidak mendukung SSL2 kecuali klien secara khusus mengaktifkannya.
ERROR_WINHTTP_INCORRECT_HANDLE_STATE	Operasi yang diminta tidak dapat diselesaikan karena handel yang disediakan 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_WINHTTP_OPERATION_CANCELLED	Operasi dibatalkan, biasanya karena handel tempat permintaan beroperasi ditutup sebelum operasi selesai.
ERROR_WINHTTP_TIMEOUT	Waktu permintaan habis.
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 dapat beroperasi secara sinkron atau asinkron. Jika mengembalikan FALSE, kesalahan gagal dan Anda dapat memanggil GetLastError untuk mendapatkan informasi kesalahan yang diperluas. Jika mengembalikan TRUE, gunakan penyelesaian WINHTTP_CALLBACK_STATUS_DATA_AVAILABLE untuk menentukan apakah fungsi ini berhasil dan nilai parameter. Penyelesaian WINHTTP_CALLBACK_STATUS_REQUEST_ERROR menunjukkan bahwa operasi selesai secara asinkron, tetapi gagal.

Peringatan Ketika WinHTTP digunakan dalam mode asinkron, selalu atur parameter lpdwNumberOfBytesAvailable ke NULL dan ambil byte yang tersedia dalam fungsi panggilan balik; jika tidak, kesalahan memori dapat terjadi.

Fungsi ini mengembalikan jumlah byte data yang tersedia untuk segera dibaca oleh panggilan berikutnya ke WinHttpReadData. Jika tidak ada data yang tersedia dan akhir file belum tercapai, salah satu dari dua hal terjadi. Jika sesi sinkron, permintaan menunggu hingga data tersedia. Jika sesi tidak sinkron, fungsi mengembalikan TRUE, dan ketika data tersedia, memanggil fungsi panggilan balik dengan WINHTTP_STATUS_CALLBACK_DATA_AVAILABLE dan menunjukkan jumlah byte yang segera tersedia untuk dibaca dengan memanggil WinHttpReadData.

Jumlah data yang tersisa tidak dihitung ulang sampai semua data yang tersedia yang ditunjukkan oleh panggilan ke WinHttpQueryDataAvailable dibaca.

Gunakan nilai pengembalian WinHttpReadData untuk menentukan kapan respons telah dibaca sepenuhnya.

Penting Jangan gunakan nilai pengembalian WinHttpQueryDataAvailable untuk menentukan apakah akhir respons telah tercapai, karena tidak semua server menghentikan respons dengan benar, dan respons yang tidak dihentikan secara tidak benar menyebabkan WinHttpQueryDataAvailable untuk mengantisipasi lebih banyak data.

Untuk handel HINTERNET yang dibuat oleh fungsi WinHttpOpenRequest dan dikirim oleh WinHttpSendRequest, panggilan ke WinHttpReceiveResponse harus dilakukan pada handel sebelum WinHttpQueryDataAvailable dapat digunakan.

Jika fungsi panggilan balik status telah diinstal dengan WinHttpSetStatusCallback, pemberitahuan berikut yang telah diatur dalam parameter dwNotificationFlags dari WinHttpSetStatusCallback menunjukkan kemajuan dalam memeriksa data yang tersedia:

WINHTTP_CALLBACK_STATUS_RECEIVING_RESPONSE
WINHTTP_CALLBACK_STATUS_RESPONSE_RECEIVED
WINHTTP_CALLBACK_STATUS_DATA_AVAILABLE

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

Contoh

Contoh berikut menunjukkan cara menggunakan semantik transaksi aman untuk mengunduh sumber daya dari server HTTPS. Kode sampel menginisialisasi WINHTTP API, memilih server HTTPS target, lalu membuka dan mengirim permintaan untuk sumber daya aman ini.
WinHttpQueryDataAvailable digunakan dengan handel permintaan untuk menentukan berapa banyak data yang tersedia untuk diunduh, lalu WinHttpReadData digunakan untuk membaca data tersebut. Proses ini berulang hingga seluruh dokumen diambil dan ditampilkan.

Penting

Jika Anda menginginkan beberapa data secepat mungkin (yaitu, Anda memproses dan mengurai data saat menerimanya), maka Anda harus memanggil WinHttpQueryDataAvailable dan WinHttpReadData. Jika Anda mencoba mengunduh seluruh respons secepat mungkin, hubungi WinHttpReadData secara langsung, karena WinHttpReadData mencoba mengisi buffer Anda sebelum menyelesaikan.

Selain itu, contoh kode di bawah ini mengalokasikan pada setiap iterasi perulangan. Untuk kode produksi, di mana performa penting, Anda dapat memulai dengan buffer berukuran tepat (mungkin 1 megabyte), dan mengubah ukurannya jika perlu. Dalam praktiknya, WinHttpQueryDataAvailable mengembalikan tidak lebih dari 8 kilobyte.


    DWORD dwSize = 0;
    DWORD dwDownloaded = 0;
    LPSTR pszOutBuffer;
    BOOL  bResults = FALSE;
    HINTERNET  hSession = NULL, 
               hConnect = NULL,
               hRequest = NULL;

    // Use WinHttpOpen to obtain a session handle.
    hSession = WinHttpOpen( L"WinHTTP Example/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_HTTPS_PORT, 0);

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

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

    // Continue to verify data until there is nothing left.
    if (bResults)
        do 
        {

            // Verify available data.
            dwSize = 0;
            if (!WinHttpQueryDataAvailable( hRequest, &dwSize))
                printf( "Error %u in WinHttpQueryDataAvailable.\n",
                        GetLastError());

            // Allocate space for the buffer.
            pszOutBuffer = new char[dwSize+1];
            if (!pszOutBuffer)
            {
                printf("Out of memory\n");
                dwSize=0;
            }
            else
            {
                // Read the Data.
                ZeroMemory(pszOutBuffer, dwSize+1);

                if (!WinHttpReadData( hRequest, (LPVOID)pszOutBuffer, 
                                      dwSize, &dwDownloaded))
                    printf( "Error %u in WinHttpReadData.\n", GetLastError());
                else
                    printf( "%s\n", pszOutBuffer);
            
                // Free the memory allocated to the buffer.
                delete [] pszOutBuffer;
            }

        } while (dwSize > 0);


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

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

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.