Fungsi WinHttpReadData (winhttp.h)
Fungsi WinHttpReadData membaca data dari handel yang dibuka oleh fungsi WinHttpOpenRequest .
Lihat juga WinHttpReadDataEx.
Sintaks
WINHTTPAPI BOOL WinHttpReadData(
[in] HINTERNET hRequest,
[out] LPVOID lpBuffer,
[in] DWORD dwNumberOfBytesToRead,
[out] LPDWORD lpdwNumberOfBytesRead
);
Parameter
[in] hRequest
Handel HINTERNET yang valid dikembalikan dari panggilan sebelumnya ke WinHttpOpenRequest. WinHttpReceiveResponse atau WinHttpQueryDataAvailable harus dipanggil untuk handel ini dan harus selesai sebelum WinHttpReadData dipanggil. Meskipun memanggil WinHttpReadData segera setelah penyelesaian WinHttpReceiveResponse menghindari pengeluaran salinan buffer, melakukannya mengharuskan aplikasi menggunakan buffer panjang tetap untuk membaca.
[out] lpBuffer
Penunjuk ke buffer yang menerima data yang dibaca. Pastikan buffer ini tetap valid hingga WinHttpReadData selesai.
[in] dwNumberOfBytesToRead
Nilai bilangan bulat panjang yang tidak ditandatangani yang berisi jumlah byte yang akan dibaca.
[out] lpdwNumberOfBytesRead
Penunjuk ke variabel bilangan bulat panjang yang tidak ditandatangani yang menerima jumlah byte yang dibaca. WinHttpReadData mengatur nilai ini ke nol sebelum melakukan pemeriksaan kesalahan atau pekerjaan apa pun. Saat menggunakan WinHTTP secara asinkron, selalu atur parameter ini ke NULL dan ambil informasi dalam fungsi panggilan balik; tidak melakukannya dapat menyebabkan kesalahan memori.
Mengembalikan nilai
Mengembalikan TRUE jika berhasil, atau FALSE sebaliknya. Untuk informasi kesalahan yang diperluas, hubungi GetLastError. Tabel berikut mengidentifikasi kode kesalahan yang dikembalikan.
| Kode Kesalahan | Deskripsi |
|---|---|
|
Koneksi dengan server telah direset atau dihentikan, atau protokol SSL yang tidak kompatibel ditemukan. Misalnya, WinHTTP 5.1 tidak mendukung SSL2 kecuali klien secara khusus mengaktifkannya. |
|
Operasi yang diminta tidak dapat dilakukan karena handel yang diberikan tidak dalam keadaan benar. |
|
Jenis handel yang disediakan salah untuk operasi ini. |
|
Terjadi kesalah internal. |
|
Operasi dibatalkan, biasanya karena handel tempat permintaan beroperasi ditutup sebelum operasi selesai. |
|
Dikembalikan saat respons masuk melebihi batas ukuran WinHTTP internal. |
|
Waktu permintaan habis. |
|
Tidak tersedia cukup memori untuk menyelesaikan operasi yang diminta. (Kode galat Windows) |
Keterangan
Dimulai di Windows Vista dan Windows Server 2008, WinHttp memungkinkan aplikasi untuk melakukan pengodean transfer terpotong pada data yang dikirim ke server. Saat header Transfer-Encoding ada di respons WinHttp, WinHttpReadData menghapus informasi penggugusan sebelum memberikan data ke aplikasi.
Bahkan ketika WinHTTP digunakan dalam mode asinkron (yaitu, ketika WINHTTP_FLAG_ASYNC telah diatur di WinHttpOpen), fungsi ini dapat beroperasi baik secara sinkron atau asinkron. Jika fungsi ini mengembalikan FALSE, fungsi ini gagal dan Anda dapat memanggil GetLastError untuk mendapatkan informasi kesalahan yang diperluas. Jika fungsi ini mengembalikan TRUE, gunakan penyelesaian WINHTTP_CALLBACK_STATUS_READ_COMPLETE untuk menentukan apakah fungsi ini berhasil dan nilai parameter. Penyelesaian WINHTTP_CALLBACK_STATUS_REQUEST_ERROR menunjukkan bahwa operasi selesai secara asinkron, tetapi gagal.
Jika Anda menggunakan WinHttpReadData secara sinkron, dan nilai yang dikembalikan adalah TRUE dan jumlah byte yang dibaca adalah nol, transfer telah selesai dan tidak ada lagi byte untuk dibaca pada handel. Ini dianalogikan untuk mencapai akhir file dalam file lokal. Jika Anda menggunakan fungsi secara asinkron, panggilan balik WINHTTP_CALLBACK_STATUS_READ_COMPLETE dipanggil dengan parameter dwStatusInformationLength diatur ke nol saat akhir respons ditemukan.
WinHttpReadData mencoba mengisi buffer yang diacu oleh lpBuffer hingga tidak ada lagi data yang tersedia dari respons. Jika data yang memadai belum tiba dari server, buffer tidak terisi.
Untuk handel HINTERNET yang dibuat oleh fungsi WinHttpOpenRequest dan dikirim oleh WinHttpSendRequest, panggilan ke WinHttpReceiveResponse harus dilakukan pada handel sebelum WinHttpReadData dapat digunakan.
Karakter byte tunggal yang diambil dengan WinHttpReadData tidak dikonversi menjadi karakter multi-byte.
Ketika buffer baca sangat kecil, WinHttpReadData dapat selesai secara sinkron, dan jika penyelesaian WINHTTP_CALLBACK_STATUS_READ_COMPLETE maka memicu panggilan lain ke WinHttpReadData, luapan tumpukan dapat menghasilkan. Yang terbaik adalah menggunakan buffer baca yang berukuran 8 Kilobyte atau lebih besar.
Jika data yang memadai belum tiba dari server, WinHttpReadData tidak sepenuhnya mengisi buffer yang ditujukan oleh lpBuffer. Buffer harus cukup besar setidaknya untuk menahan header HTTP pada bacaan pertama, dan ketika membaca entri direktori yang dikodekan HTML, harus cukup besar untuk menahan setidaknya satu entri lengkap.
Jika fungsi panggilan balik status telah diinstal dengan menggunakan 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_CONNECTION_CLOSED
- WINHTTP_CALLBACK_STATUS_READ_COMPLETE
Contoh
Contoh berikut menunjukkan cara menggunakan semantik transaksi aman untuk mengunduh sumber daya dari server Secure Hypertext Transfer Protocol (HTTPS). Kode sampel menginisialisasi antarmuka pemrograman aplikasi 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.
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);
// Keep checking for data until there is nothing left.
if (bResults)
{
do
{
// Check for available data.
dwSize = 0;
if (!WinHttpQueryDataAvailable( hRequest, &dwSize))
{
printf( "Error %u in WinHttpQueryDataAvailable.\n",
GetLastError());
break;
}
// No more available data.
if (!dwSize)
break;
// Allocate space for the buffer.
pszOutBuffer = new char[dwSize+1];
if (!pszOutBuffer)
{
printf("Out of memory\n");
break;
}
// Read the Data.
ZeroMemory(pszOutBuffer, dwSize+1);
if (!WinHttpReadData( hRequest, (LPVOID)pszOutBuffer,
dwSize, &dwDownloaded))
{
printf( "Error %u in WinHttpReadData.\n", GetLastError());
}
else
{
printf("%s", pszOutBuffer);
}
// Free the memory allocated to the buffer.
delete [] pszOutBuffer;
// This condition should never be reached since WinHttpQueryDataAvailable
// reported that there are bits to read.
if (!dwDownloaded)
break;
} while (dwSize > 0);
}
else
{
// Report any errors.
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 di Windows XP dan Windows 2000. |