Fungsi WinHttpAddRequestHeaders (winhttp.h)
Fungsi WinHttpAddRequestHeaders menambahkan satu atau beberapa header permintaan HTTP ke handel permintaan HTTP.
Sintaks
WINHTTPAPI BOOL WinHttpAddRequestHeaders(
[in] HINTERNET hRequest,
[in] LPCWSTR lpszHeaders,
[in] DWORD dwHeadersLength,
[in] DWORD dwModifiers
);
Parameter
[in] hRequest
Handel HINTERNET yang dikembalikan oleh panggilan ke fungsi WinHttpOpenRequest .
[in] lpszHeaders
Penunjuk ke variabel string yang berisi header untuk ditambahkan ke permintaan. Setiap header kecuali yang terakhir harus dihentikan oleh umpan kembali/baris pengangkutan (CR/LF).
[in] dwHeadersLength
Nilai bilangan bulat panjang yang tidak ditandatangani yang berisi panjang, dalam karakter, pwszHeaders. Jika parameter ini adalah -1L, fungsi mengasumsikan bahwa pwszHeaders dihentikan nol (ASCIIZ), dan panjangnya dihitung.
[in] dwModifiers
Nilai bilangan bulat panjang yang tidak ditandatangani yang berisi bendera yang digunakan untuk memodifikasi semantik fungsi ini. Dapat berupa satu atau beberapa bendera berikut.
Nilai kembali
Mengembalikan TRUE jika berhasil, atau FALSE sebaliknya. Untuk informasi kesalahan yang diperluas, hubungi GetLastError. Di antara kode kesalahan yang dikembalikan adalah sebagai berikut.
| Kode Kesalahan | Deskripsi |
|---|---|
|
Operasi yang diminta tidak dapat dilakukan karena handel yang disediakan tidak dalam keadaan yang benar. |
|
Jenis handel yang disediakan salah untuk operasi ini. |
|
Terjadi kesalah internal. |
|
Memori tidak cukup tersedia untuk menyelesaikan operasi yang diminta. |
Keterangan
Header ditransfer di seluruh pengalihan. Ini bisa menjadi masalah keamanan. Untuk menghindari header yang ditransfer saat pengalihan terjadi, gunakan panggilan balik WINHTTP_STATUS_CALLBACK untuk memperbaiki header tertentu saat pengalihan terjadi.
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.
Fungsi WinHttpAddRequestHeaders menambahkan header format bebas tambahan ke handel permintaan HTTP dan dimaksudkan untuk digunakan oleh klien canggih yang memerlukan kontrol terperinci atas permintaan yang tepat yang dikirim ke server HTTP.
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.
Jika Anda mengirim header Permintaan Tanggal: , Anda bisa menggunakan fungsi WinHttpTimeFromSystemTime untuk membuat struktur header.
Untuk WinHttpAddRequestHeaders dasar, aplikasi dapat meneruskan beberapa header dalam satu buffer.
Aplikasi juga bisa menggunakan WinHttpSendRequest untuk menambahkan header tambahan ke handel permintaan HTTP sebelum mengirim permintaan.
Contoh
Contoh kode berikut menyertakan header If-Modified-Since dalam permintaan. Header respons ditafsirkan untuk menentukan apakah dokumen target telah diperbarui.
DWORD dwSize = sizeof(DWORD);
DWORD dwStatusCode = 0;
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 );
// Add a request header.
if( hRequest )
bResults = WinHttpAddRequestHeaders( hRequest,
L"If-Modified-Since: Mon, 20 Nov 2000 20:00:00 GMT",
(ULONG)-1L,
WINHTTP_ADDREQ_FLAG_ADD );
// Send a Request.
if( bResults )
bResults = WinHttpSendRequest( hRequest,
WINHTTP_NO_ADDITIONAL_HEADERS,
0,
WINHTTP_NO_REQUEST_DATA,
0,
0,
0 );
// End the request.
if( bResults )
bResults = WinHttpReceiveResponse( hRequest, NULL);
// Use WinHttpQueryHeaders to obtain the header buffer.
if( bResults )
bResults = WinHttpQueryHeaders( hRequest,
WINHTTP_QUERY_STATUS_CODE | WINHTTP_QUERY_FLAG_NUMBER,
NULL,
&dwStatusCode,
&dwSize,
WINHTTP_NO_HEADER_INDEX );
// Based on the status code, determine whether
// the document was recently updated.
if( bResults )
{
if( dwStatusCode == 304 )
printf( "Document has not been updated.\n" );
else if( dwStatusCode == 200 )
printf( "Document has been updated.\n" );
else
printf( "Status code = %u.\n",dwStatusCode );
}
// 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. |