Fungsi WinHttpSendRequest (winhttp.h)
Fungsi WinHttpSendRequest mengirimkan permintaan yang ditentukan ke server HTTP.
Sintaks
WINHTTPAPI BOOL WinHttpSendRequest(
[in] HINTERNET hRequest,
[in, optional] LPCWSTR lpszHeaders,
[in] DWORD dwHeadersLength,
[in, optional] LPVOID lpOptional,
[in] DWORD dwOptionalLength,
[in] DWORD dwTotalLength,
[in] DWORD_PTR dwContext
);
Parameter
[in] hRequest
Handel HINTERNET yang dikembalikan oleh WinHttpOpenRequest.
[in, optional] lpszHeaders
Penunjuk ke string yang berisi header tambahan untuk ditambahkan ke permintaan. Parameter ini dapat WINHTTP_NO_ADDITIONAL_HEADERS jika tidak ada header tambahan untuk ditambahkan.
[in] dwHeadersLength
Nilai bilangan bulat panjang yang tidak ditandatangani yang berisi panjang, dalam karakter, dari header tambahan. Jika parameter ini adalah -1L dan pwszHeaders bukan NULL, fungsi ini mengasumsikan bahwa pwszHeadersdihentikan null, dan panjangnya dihitung.
[in, optional] lpOptional
Penunjuk ke buffer yang berisi data opsional apa pun untuk dikirim segera setelah header permintaan. Parameter ini umumnya digunakan untuk operasi POST dan PUT. Data opsional dapat menjadi sumber daya atau data yang diposting ke server. Parameter ini dapat WINHTTP_NO_REQUEST_DATA jika tidak ada data opsional untuk dikirim.
Jika parameter dwOptionalLength adalah 0, parameter ini diabaikan dan diatur ke NULL.
Buffer ini harus tetap tersedia sampai handel permintaan ditutup atau panggilan ke WinHttpReceiveResponse telah selesai.
[in] dwOptionalLength
Nilai bilangan bulat panjang yang tidak ditandatangani yang berisi panjang, dalam byte, dari data opsional. Parameter ini bisa nol jika tidak ada data opsional untuk dikirim.
Parameter ini harus berisi panjang yang valid ketika parameter lpOptional bukan NULL. Jika tidak, lpOptional diabaikan dan diatur ke NULL.
[in] dwTotalLength
Nilai bilangan bulat panjang yang tidak ditandatangani yang berisi panjang, dalam byte, dari total data yang dikirim. Parameter ini menentukan header Content-Length dari permintaan. Jika nilai parameter ini lebih besar dari panjang yang ditentukan oleh dwOptionalLength, maka WinHttpWriteData dapat digunakan untuk mengirim data tambahan.
dwTotalLength tidak boleh mengubah antara panggilan ke WinHttpSendRequest untuk permintaan yang sama. Jika dwTotalLength perlu diubah, pemanggil harus membuat permintaan baru.
[in] dwContext
Pointer ke variabel berukuran pointer yang berisi nilai yang ditentukan aplikasi yang diteruskan, dengan handel permintaan, ke fungsi panggilan balik apa pun.
Mengembalikan nilai
Mengembalikan TRUE jika berhasil, atau FALSE sebaliknya. Untuk informasi kesalahan yang diperluas, hubungi GetLastError. Kode kesalahan tercantum dalam tabel berikut.
| Kode Kesalahan | Deskripsi |
|---|---|
|
Dikembalikan jika koneksi ke server gagal. |
|
Server HTTP aman memerlukan sertifikat klien. Aplikasi mengambil daftar penerbit sertifikat dengan memanggil WinHttpQueryOption dengan opsi WINHTTP_OPTION_CLIENT_CERT_ISSUER_LIST .
Jika server meminta sertifikat klien, tetapi tidak memerlukannya, aplikasi dapat memanggil WinHttpSetOption secara bergantian dengan opsi WINHTTP_OPTION_CLIENT_CERT_CONTEXT . Dalam hal ini, aplikasi menentukan makro WINHTTP_NO_CLIENT_CERT_CONTEXT dalam parameter lpBufferWinHttpSetOption. Untuk informasi selengkapnya, lihat opsi WINHTTP_OPTION_CLIENT_CERT_CONTEXT . Windows Server 2003 dengan SP1, Windows XP dengan SP2 dan Windows 2000: Kesalahan ini tidak didukung. |
|
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. |
|
Operasi yang diminta tidak dapat dilakukan karena handel yang diberikan tidak dalam keadaan yang benar. |
|
Jenis handel yang disediakan salah untuk operasi ini. |
|
Terjadi kesalah internal. |
|
URL tidak valid. |
|
Upaya masuk gagal. Ketika kesalahan ini ditemui, handel permintaan harus ditutup dengan WinHttpCloseHandle. Handel permintaan baru harus dibuat sebelum mencoba kembali fungsi yang awalnya menghasilkan kesalahan ini. |
|
Nama server tidak dapat diatasi. |
|
Operasi dibatalkan, biasanya karena handel tempat permintaan beroperasi ditutup sebelum operasi selesai. |
|
Dikembalikan saat respons masuk melebihi batas ukuran WinHTTP internal. |
|
Satu atau beberapa kesalahan ditemukan di sertifikat Secure Sockets Layer (SSL) yang dikirim oleh server. Untuk menentukan jenis kesalahan apa yang ditemui, verifikasi melalui pemberitahuan WINHTTP_CALLBACK_STATUS_SECURE_FAILURE dalam fungsi panggilan balik status. Untuk informasi selengkapnya, lihat WINHTTP_STATUS_CALLBACK. |
|
Dukungan fungsi WinHTTP dimatikan atau dibongkar. |
|
Waktu permintaan habis. |
|
URL menentukan skema selain "http:" atau "https:". |
|
Memori tidak cukup tersedia untuk menyelesaikan operasi yang diminta. (Kode galat Windows) Windows Server 2003, Windows XP, dan Windows 2000: Rentang reservasi TCP yang diatur dengan opsi WINHTTP_OPTION_PORT_RESERVATION tidak cukup besar untuk mengirim permintaan ini. |
|
Panjang konten yang ditentukan dalam parameter dwTotalLength tidak cocok dengan panjang yang ditentukan di header Content-Length.
Parameter lpOptional harus NULL dan parameter dwOptionalLength harus nol ketika header Transfer-Encoding ada. Header Content-Length tidak dapat ada ketika header Transfer-Encoding ada. |
|
Aplikasi harus memanggil WinHttpSendRequest lagi karena tantangan pengalihan atau autentikasi.
Windows Server 2003 dengan SP1, Windows XP dengan SP2 dan Windows 2000: Kesalahan ini tidak didukung. |
Keterangan
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. Dalam kedua kasus, jika permintaan berhasil dikirim, aplikasi dipanggil kembali dengan status penyelesaian diatur ke WINHTTP_CALLBACK_STATUS_SENDREQUEST_COMPLETE. Penyelesaian WINHTTP_CALLBACK_STATUS_REQUEST_ERROR menunjukkan bahwa operasi selesai secara asinkron, tetapi gagal. Setelah menerima panggilan balik status WINHTTP_CALLBACK_STATUS_SENDREQUEST_COMPLETE , aplikasi dapat mulai menerima respons dari server dengan WinHttpReceiveResponse. Sebelum itu, tidak ada fungsi asinkron lain yang dapat dipanggil, jika tidak, ERROR_WINHTTP_INCORRECT_HANDLE_STATE dikembalikan.
Aplikasi tidak boleh menghapus atau mengubah buffer yang ditunjukkan oleh lpOptional sampai handel permintaan ditutup atau panggilan ke WinHttpReceiveResponse telah selesai, karena tantangan autentikasi atau pengalihan yang memerlukan data opsional dapat ditemui selama menerima respons. Jika operasi harus dibatalkan dengan WinHttpCloseHandle, aplikasi harus menjaga buffer tetap valid sampai menerima panggilan balik WINHTTP_CALLBACK_STATUS_REQUEST_ERROR dengan kode kesalahan ERROR_WINHTTP_OPERATION_CANCELLED .
Jika WinHTTP digunakan secara sinkron, yaitu, ketika WINHTP_FLAG_ASYNC tidak diatur di WinHttpOpen, aplikasi tidak dipanggil dengan status penyelesaian meskipun fungsi panggilan balik terdaftar. Saat dalam mode ini, aplikasi dapat memanggil WinHttpReceiveResponse saat WinHttpSendRequest kembali.
Fungsi WinHttpSendRequest mengirimkan permintaan yang ditentukan ke server HTTP dan memungkinkan klien menentukan header tambahan untuk dikirim bersama dengan permintaan.
Fungsi ini juga memungkinkan klien menentukan data opsional untuk dikirim ke server HTTP segera mengikuti header permintaan. Fitur ini umumnya digunakan untuk operasi tulis seperti PUT dan POST.
Aplikasi dapat menggunakan handel permintaan HTTP yang sama dalam beberapa panggilan ke WinHttpSendRequest untuk mengirim ulang permintaan yang sama, tetapi aplikasi harus membaca semua data yang dikembalikan dari panggilan sebelumnya sebelum memanggil fungsi ini lagi.
Nama dan nilai header permintaan yang ditambahkan dengan fungsi ini divalidasi. Header harus terbentuk dengan baik. Untuk informasi selengkapnya tentang header HTTP yang valid, lihat RFC 2616. Jika header yang tidak valid digunakan, fungsi ini gagal dan GetLastError mengembalikan ERROR_INVALID_PARAMETER. Header tidak valid tidak ditambahkan.
Windows 2000: Saat mengirim permintaan dari beberapa utas, mungkin ada penurunan performa jaringan dan CPU yang signifikan.
Windows XP dan Windows 2000: Lihat Persyaratan Run-Time.
WinHttpSetStatusCallback
Jika fungsi panggilan balik status telah diinstal dengan WinHttpSetStatusCallback, maka pemberitahuan berikut yang telah diatur dalam parameter dwNotificationFlags dari WinHttpSetStatusCallback menunjukkan kemajuan dalam mengirim permintaan:- WINHTTP_CALLBACK_STATUS_DETECTING_PROXY (tidak diimplementasikan)
- WINHTTP_CALLBACK_STATUS_SENDREQUEST_COMPLETE (hanya dalam mode asinkron)
- WINHTTP_CALLBACK_STATUS_REDIRECT
- WINHTTP_CALLBACK_STATUS_SECURE_FAILURE
- WINHTTP_CALLBACK_STATUS_INTERMEDIATE_RESPONSE
- WINHTTP_CALLBACK_STATUS_RESOLVING_NAME
- WINHTTP_CALLBACK_STATUS_NAME_RESOLVED
- WINHTTP_CALLBACK_STATUS_CONNECTING_TO_SERVER
- WINHTTP_CALLBACK_STATUS_CONNECTED_TO_SERVER
- WINHTTP_CALLBACK_STATUS_SENDING_REQUEST
- WINHTTP_CALLBACK_STATUS_REQUEST_SENT
- WINHTTP_CALLBACK_STATUS_RECEIVING_RESPONSE
- WINHTTP_CALLBACK_STATUS_RESPONSE_RECEIVED
- WINHTTP_CALLBACK_STATUS_CLOSING_CONNECTION
- WINHTTP_CALLBACK_STATUS_CONNECTION_CLOSED
Dukungan untuk Unggahan lebih besar dari 4 GB
Dimulai di Windows Vista dan Windows Server 2008, WinHttp mendukung pengunggahan file hingga ukuran LARGE_INTEGER (2^64 byte) menggunakan header Content-Length. Panjang payload yang ditentukan dalam panggilan ke WinHttpSendRequest terbatas pada ukuran DWORD (2^32 byte). Untuk mengunggah data ke URL yang lebih besar dari DWORD, aplikasi harus menyediakan panjang di header Content-Length permintaan. Dalam hal ini, aplikasi klien WinHttp memanggil WinHttpSendRequest dengan parameter dwTotalLength diatur ke WINHTTP_IGNORE_REQUEST_TOTAL_LENGTH.Jika header Content-Length menentukan panjang kurang dari 2^32, aplikasi juga harus menentukan panjang konten dalam panggilan ke WinHttpSendRequest. Jika parameter dwTotalLength tidak cocok dengan panjang yang ditentukan di header Content-Length, panggilan gagal dan mengembalikan ERROR_INVALID_PARAMETER.
Header Content-Length dapat ditambahkan dalam panggilan ke WinHttpAddRequestHeaders, atau dapat ditentukan dalam parameter lpszHeader dari WinHttpSendRequest seperti yang diperlihatkan dalam contoh kode berikut.
BOOL fRet = WinHttpSendRequest(
hReq,
L"Content-Length: 68719476735\r\n",
-1L,
WINHTTP_NO_REQUEST_DATA,
0,
WINHTTP_IGNORE_REQUEST_TOTAL_LENGTH,
pMyContent);
Header Pengodean Transfer
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 pada permintaan WinHttp, parameter dwTotalLength dalam panggilan ke WinHttpSendRequest diatur ke WINHTTP_IGNORE_REQUEST_TOTAL_LENGTH dan aplikasi mengirim isi entitas dalam satu atau beberapa panggilan ke WinHttpWriteData. Parameter lpOptional dari WinHttpSendRequest harus NULL dan parameter dwOptionLength harus nol, jika tidak, kesalahan ERROR_WINHTTP_INVALID_PARAMETER dikembalikan. Untuk mengakhiri transfer data yang dipotong, aplikasi menghasilkan gugus panjang nol dan mengirimkannya dalam panggilan terakhir ke WinHttpWriteData.Contoh
Contoh kode berikut menunjukkan cara mendapatkan handel HINTERNET , membuka sesi HTTP, membuat header permintaan, dan mengirim header tersebut ke server.
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.wingtiptoys.com",
INTERNET_DEFAULT_HTTP_PORT, 0);
// Create an HTTP Request handle.
if (hConnect)
hRequest = WinHttpOpenRequest( hConnect, L"PUT",
L"/writetst.txt",
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);
// Place additional code here.
// Report 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
| 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. |
Lihat juga
Tentang Microsoft Windows HTTP Services (WinHTTP)
WINHTTP_STATUS_CALLBACK