Fungsi WinHttpOpenRequest (winhttp.h)

Artikel
08/27/2023

Fungsi WinHttpOpenRequest membuat handel permintaan HTTP.

Sintaks

WINHTTPAPI HINTERNET WinHttpOpenRequest(
  [in] HINTERNET hConnect,
  [in] LPCWSTR   pwszVerb,
  [in] LPCWSTR   pwszObjectName,
  [in] LPCWSTR   pwszVersion,
  [in] LPCWSTR   pwszReferrer,
  [in] LPCWSTR   *ppwszAcceptTypes,
  [in] DWORD     dwFlags
);

Parameter

[in] hConnect

Handel koneksi HINTERNET ke sesi HTTP yang dikembalikan oleh WinHttpConnect.

[in] pwszVerb

Penunjuk ke string yang berisi kata kerja HTTP untuk digunakan dalam permintaan. Jika parameter ini NULL, fungsi menggunakan GET sebagai kata kerja HTTP. Catatan String ini harus dalam huruf besar semua. Banyak server memperlakukan kata kerja HTTP sebagai peka huruf besar/kecil, dan Permintaan Untuk Komentar (RFC) Internet Engineering Task Force (IETF) mengeja kata kerja ini hanya menggunakan karakter huruf besar.

[in] pwszObjectName

Penunjuk ke string yang berisi nama sumber daya target kata kerja HTTP yang ditentukan. Ini umumnya adalah nama file, modul yang dapat dieksekusi, atau penentu pencarian.

[in] pwszVersion

Penunjuk ke string yang berisi versi HTTP. Jika parameter ini ADALAH NULL, fungsi menggunakan HTTP/1.1.

[in] pwszReferrer

Penunjuk ke string yang menentukan URL dokumen tempat URL dalam permintaan pwszObjectName diperoleh. Jika parameter ini diatur ke WINHTTP_NO_REFERER, tidak ada dokumen rujukan yang ditentukan.

[in] ppwszAcceptTypes

Penunjuk ke array penunjuk string yang dihentikan null yang menentukan jenis media yang diterima oleh klien. Jika parameter ini diatur ke WINHTTP_DEFAULT_ACCEPT_TYPES, tidak ada jenis yang diterima oleh klien. Biasanya, server menangani kurangnya jenis yang diterima sebagai indikasi bahwa klien hanya menerima dokumen jenis "text/*"; yaitu, hanya dokumen teks—tidak ada gambar atau file biner lainnya. Untuk daftar jenis media yang valid, lihat Jenis Media yang ditentukan oleh IANA di http://www.iana.org/assignments/media-types/.

[in] dwFlags

Nilai bilangan bulat panjang yang tidak ditandatangani yang berisi nilai bendera Internet. Ini bisa berupa satu atau beberapa nilai berikut ini:

Nilai	Makna
WINHTTP_FLAG_BYPASS_PROXY_CACHE	Bendera ini menyediakan perilaku yang sama dengan WINHTTP_FLAG_REFRESH.
WINHTTP_FLAG_ESCAPE_DISABLE	Karakter tidak aman dalam URL yang diteruskan untuk pwszObjectName tidak dikonversi ke urutan escape.
WINHTTP_FLAG_ESCAPE_DISABLE_QUERY	Karakter tidak aman dalam komponen kueri URL yang diteruskan untuk pwszObjectName tidak dikonversi ke urutan escape.
WINHTTP_FLAG_ESCAPE_PERCENT	String yang diteruskan untuk pwszObjectName dikonversi dari LPCWSTR ke LPSTR. Semua karakter yang tidak aman dikonversi ke urutan escape termasuk simbol persen. Secara default, semua karakter tidak aman kecuali simbol persen dikonversi ke urutan escape.
WINHTTP_FLAG_NULL_CODEPAGE	String yang diteruskan untuk pwszObjectName diasumsikan terdiri dari karakter ANSI yang valid yang diwakili oleh WCHAR. Tidak ada pemeriksaan yang dilakukan untuk karakter yang tidak aman. Windows 7: Opsi ini kedaluarsa.
WINHTTP_FLAG_REFRESH	Menunjukkan bahwa permintaan harus diteruskan ke server asal daripada mengirim versi cache sumber daya dari server proksi. Ketika bendera ini digunakan, header "Pragma: no-cache" ditambahkan ke handel permintaan. Saat membuat header permintaan HTTP/1.1, "Cache-Control: no-cache" juga ditambahkan.
WINHTTP_FLAG_SECURE	Menggunakan semantik transaksi yang aman. Ini diterjemahkan menggunakan Secure Sockets Layer (SSL)/Transport Layer Security (TLS).

Mengembalikan nilai

Mengembalikan handel permintaan HTTP yang valid jika berhasil, atau NULL jika tidak. Untuk informasi kesalahan yang diperluas, hubungi GetLastError. Di antara kode kesalahan yang dikembalikan adalah sebagai berikut.

Kode Kesalahan	Deskripsi
ERROR_WINHTTP_INCORRECT_HANDLE_TYPE	Jenis handel yang disediakan salah untuk operasi ini.
ERROR_WINHTTP_INTERNAL_ERROR	Terjadi kesalah internal.
ERROR_WINHTTP_INVALID_URL	URL tidak valid.
ERROR_WINHTTP_OPERATION_CANCELLED	Operasi dibatalkan, biasanya karena handel tempat permintaan beroperasi ditutup sebelum operasi selesai.
ERROR_WINHTTP_UNRECOGNIZED_SCHEME	URL menentukan skema selain "http:" atau "https:".
ERROR_NOT_ENOUGH_MEMORY	Tidak tersedia cukup memori untuk menyelesaikan operasi yang diminta. (Kode galat Windows)

Keterangan

Nilai yang dikembalikan menunjukkan keberhasilan atau kegagalan. Untuk mendapatkan informasi kesalahan yang diperluas, hubungi GetLastError.

Fungsi WinHttpOpenRequest membuat handel permintaan HTTP baru dan menyimpan parameter yang ditentukan dalam handel tersebut. Handel permintaan HTTP menyimpan permintaan untuk dikirim ke server HTTP dan berisi semua header RFC822/MIME/HTTP untuk dikirim sebagai bagian dari permintaan.

Jika pwszVerb diatur ke "HEAD", header Content-Length diabaikan.

Jika fungsi panggilan balik status telah diinstal dengan WinHttpSetStatusCallback, pemberitahuan WINHTTP_CALLBACK_STATUS_HANDLE_CREATED menunjukkan bahwa WinHttpOpenRequest telah membuat handel permintaan.

Setelah aplikasi panggilan selesai menggunakan handel HINTERNET yang dikembalikan oleh WinHttpOpenRequest, aplikasi harus ditutup menggunakan fungsi WinHttpCloseHandle .

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

Contoh

Contoh ini 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 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 di Windows XP dan Windows 2000.