Fungsi HttpReceiveHttpRequest (http.h)
Fungsi HttpReceiveHttpRequest mengambil permintaan HTTP berikutnya yang tersedia dari antrean permintaan yang ditentukan baik secara sinkron atau asinkron.
Sintaks
HTTPAPI_LINKAGE ULONG HttpReceiveHttpRequest(
[in] HANDLE RequestQueueHandle,
[in] HTTP_REQUEST_ID RequestId,
[in] ULONG Flags,
[out] PHTTP_REQUEST RequestBuffer,
[in] ULONG RequestBufferLength,
[out, optional] PULONG BytesReturned,
[in, optional] LPOVERLAPPED Overlapped
);
Parameter
[in] RequestQueueHandle
Handel ke antrean permintaan untuk mengambil permintaan berikutnya yang tersedia. Antrean permintaan dibuat dan handelnya dikembalikan oleh panggilan ke fungsi HttpCreateRequestQueue .
Windows Server 2003 dengan SP1 dan Windows XP dengan SP2: Handel ke antrean permintaan dibuat oleh fungsi HttpCreateHttpHandle .
[in] RequestId
Pada panggilan pertama untuk mengambil permintaan, parameter ini harus HTTP_NULL_ID. Kemudian, jika lebih dari satu panggilan diperlukan untuk mengambil seluruh permintaan, HttpReceiveHttpRequest atau HttpReceiveRequestEntityBody dapat dipanggil dengan RequestID diatur ke nilai yang dikembalikan dalam anggota RequestId dari struktur HTTP_REQUEST yang ditunjukkan oleh pRequestBuffer.
[in] Flags
Parameter yang bisa menjadi salah satu nilai berikut.
| Nilai | Makna |
|---|---|
|
Hanya header permintaan yang diambil; isi entitas tidak disalin. |
|
Isi entitas yang tersedia disalin bersama dengan header permintaan. Anggota pEntityChunks dari struktur HTTP_REQUEST menunjuk ke badan entitas. |
|
Semua badan entitas disalin bersama dengan header permintaan. Anggota pEntityChunks dari struktur HTTP_REQUEST menunjuk ke badan entitas. |
[out] RequestBuffer
Penunjuk ke buffer tempat fungsi menyalin struktur HTTP_REQUEST dan badan entitas untuk permintaan HTTP. HTTP_REQUEST. RequestId berisi pengidentifikasi untuk permintaan HTTP ini, yang dapat digunakan aplikasi dalam panggilan berikutnya HttpReceiveRequestEntityBody, HttpSendHttpResponse, atau HttpSendResponseEntityBody.
[in] RequestBufferLength
Ukuran, dalam byte, dari buffer pRequestBuffer .
[out, optional] BytesReturned
Pilihan. Penunjuk ke variabel yang menerima ukuran, dalam byte, dari isi entitas, atau dari bagian isi entitas yang tersisa.
Saat melakukan panggilan asinkron menggunakan pOverlapped, atur pBytesReceived ke NULL. Jika tidak, ketika pOverlapped diatur ke NULL, pBytesReceived harus berisi alamat memori yang valid, dan tidak diatur ke NULL.
[in, optional] Overlapped
Untuk panggilan asinkron, atur pOverlapped untuk menunjuk ke struktur yang TUMPANG TINDIH ; untuk panggilan sinkron, atur ke NULL.
Panggilan sinkron memblokir hingga permintaan tiba dalam antrean yang ditentukan dan beberapa atau semua panggilan telah diambil, sedangkan panggilan asinkron segera mengembalikan ERROR_IO_PENDING dan aplikasi panggilan kemudian menggunakan port penyelesaian GetOverlappedResult atau I/O untuk menentukan kapan operasi selesai. Untuk informasi selengkapnya tentang menggunakan struktur yang TUMPANG TINDIH untuk sinkronisasi, lihat
Sinkronisasi dan Input dan Output yang Tumpang Tindih.
Menampilkan nilai
Jika fungsi berhasil, nilai yang dikembalikan adalah NO_ERROR.
Jika fungsi sedang digunakan secara asinkron, nilai pengembalian ERROR_IO_PENDING menunjukkan bahwa permintaan berikutnya belum siap dan akan diambil nanti melalui mekanisme penyelesaian I/O yang tumpang tindih normal.
Jika fungsi gagal, nilai yang dikembalikan adalah salah satu kode kesalahan berikut.
| Nilai | Makna |
|---|---|
|
Satu atau beberapa parameter yang disediakan dalam bentuk yang tidak dapat digunakan. |
|
Satu atau beberapa parameter yang disediakan menunjuk ke buffer memori yang tidak valid atau tidak ditandatangani. Parameter pRequestBuffer harus menunjuk ke buffer memori yang valid dengan perataan memori yang sama atau lebih besar dengan persyaratan perataan memori untuk struktur HTTP_REQUEST . |
|
Nilai RequestBufferLength lebih besar dari atau sama dengan ukuran header permintaan yang diterima, tetapi tidak sebesar ukuran gabungan struktur permintaan dan badan entitas. Ukuran buffer yang diperlukan untuk membaca bagian isi entitas yang tersisa dikembalikan dalam parameter pBytesReceived jika ini bukan NULL dan jika panggilan sinkron. Panggil fungsi lagi dengan buffer yang cukup besar untuk mengambil semua data. |
|
Permintaan yang ditentukan telah diambil sepenuhnya; dalam hal ini, nilai yang ditujukan oleh pBytesReceived tidak bermakna, dan pRequestBuffer tidak boleh diperiksa. |
|
Kode kesalahan sistem yang ditentukan dalam WinError.h. |
Keterangan
Lebih dari satu panggilan dapat diperlukan untuk mengambil permintaan tertentu. Saat parameter Bendera diatur ke nol, misalnya, HttpReceiveHttpRequest hanya menyalin struktur header permintaan ke dalam buffer, dan tidak mencoba menyalin salah satu isi entitas. Dalam hal ini, fungsi HttpReceiveRequestEntityBody dapat digunakan untuk mengambil isi entitas, atau panggilan kedua dapat dilakukan ke HttpReceiveHttpRequest.
Atau, buffer yang disediakan oleh aplikasi mungkin tidak cukup besar untuk menerima semua atau sebagian permintaan. Untuk memastikan menerima setidaknya sebagian dari permintaan, disarankan agar aplikasi menyediakan setidaknya buffer 4 KB, yang mengakomodasi sebagian besar permintaan HTTP. Secara bergantian, header autentikasi, diurai sebagai header yang tidak diketahui, dapat menambahkan hingga 12 KB ke dalamnya, jadi jika autentikasi/otorisasi digunakan, ukuran buffer setidaknya 16 KB direkomendasikan.
Jika HttpReceiveHttpRequest mengembalikan ERROR_MORE_DATA, aplikasi terus melakukan panggilan tambahan, mengidentifikasi permintaan di setiap panggilan tambahan dengan meneruskan HTTP_REQUEST. Nilai RequestId yang dikembalikan oleh panggilan pertama hingga ERROR_HANDLE_EOF dikembalikan.
Persyaratan
| Klien minimum yang didukung | Windows Vista, Windows XP dengan SP2 [hanya aplikasi desktop] |
| Server minimum yang didukung | Windows Server 2003 [hanya aplikasi desktop] |
| Target Platform | Windows |
| Header | http.h |
| Pustaka | Httpapi.lib |
| DLL | Httpapi.dll |