Fungsi HttpReceiveClientCertificate (http.h)

Artikel
08/24/2023

Fungsi HttpReceiveClientCertificate digunakan oleh aplikasi server untuk mengambil sertifikat SSL klien atau token pengikatan saluran (CBT).

Sintaks

HTTPAPI_LINKAGE ULONG HttpReceiveClientCertificate(
  [in]            HANDLE                     RequestQueueHandle,
  [in]            HTTP_CONNECTION_ID         ConnectionId,
  [in]            ULONG                      Flags,
  [out]           PHTTP_SSL_CLIENT_CERT_INFO SslClientCertInfo,
  [in]            ULONG                      SslClientCertInfoSize,
  [out, optional] PULONG                     BytesReceived,
  [in, optional]  LPOVERLAPPED               Overlapped
);

Parameter

[in] RequestQueueHandle

Handel ke antrean permintaan yang terkait dengan klien SSL atau CBT yang ditentukan. 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] ConnectionId

Nilai yang mengidentifikasi koneksi ke klien. Nilai ini diperoleh dari elemen ConnectionId dari struktur HTTP_REQUEST yang diisi oleh fungsi HttpReceiveHttpRequest .

[in] Flags

Nilai yang memodifikasi perilaku fungsi HttpReceiveClientCertificate

Nilai	Makna
HTTP_RECEIVE_SECURE_CHANNEL_TOKEN 0x1	Parameter pSslClientCertInfo akan diisi dengan data CBT. Nilai ini didukung pada Windows 7, Windows Server 2008 R2, dan yang lebih baru.

[out] SslClientCertInfo

Jika parameter Bendera adalah 0, parameter ini menunjuk ke struktur HTTP_SSL_CLIENT_CERT_INFO tempat fungsi menulis informasi sertifikat klien yang diminta. Buffer yang ditunjukkan oleh pSslClientCertInfo harus cukup besar untuk menahan struktur HTTP_SSL_CLIENT_CERT_INFO ditambah nilai anggota CertEncodedSize dari struktur ini.

Jika parameter BenderaHTTP_RECEIVE_SECURE_CHANNEL_TOKEN, parameter ini menunjuk ke struktur HTTP_REQUEST_CHANNEL_BIND_STATUS tempat fungsi menulis informasi CBT yang diminta. Buffer yang ditunjukkan oleh pSslClientCertInfo harus cukup besar untuk menahan struktur HTTP_REQUEST_CHANNEL_BIND_STATUS ditambah nilai anggota ChannelTokenSize dari struktur ini.

[in] SslClientCertInfoSize

Ukuran, dalam byte, dari buffer yang diacu oleh parameter pSslClientCertInfo .

[out, optional] BytesReceived

Penunjuk opsional ke variabel yang menerima jumlah byte yang akan ditulis ke struktur yang diacu oleh pSslClientCertInfo. Jika tidak digunakan, atur ke NULL.

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 TUMPANG TINDIH , atau untuk panggilan sinkron, atur ke NULL.

Panggilan sinkron memblokir hingga sertifikat klien 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 TUMPANG TINDIH untuk sinkronisasi, lihat bagian Sinkronisasi dan Input dan Output yang Tumpang Tindih.

Menampilkan nilai

Nilai	Makna
NO_ERROR	Fungsi berhasil. Semua data telah ditulis ke dalam buffer yang ditujukkan oleh parameter pSslClientCertInfo . NumberOfBytesTransferred menunjukkan berapa banyak byte yang ditulis ke dalam buffer.
ERROR_IO_PENDING	Fungsi ini digunakan secara asinkron. Operasi telah dimulai dan akan selesai nanti melalui mekanisme penyelesaian I/O yang tumpang tindih normal.
ERROR_INVALID_PARAMETER	Satu atau beberapa parameter yang disediakan tidak valid.
ERROR_INSUFFICIENT_BUFFER	Buffer yang ditujukkan oleh parameter pSslClientCertInfo terlalu kecil untuk menerima data dan tidak ada data yang ditulis.
ERROR_MORE_DATA	Buffer yang ditujukkan oleh parameter pSslClientCertInfo tidak cukup besar untuk menerima semua data. Hanya struktur dasar yang telah ditulis dan hanya diisi sebagian. Ketika parameter Bendera adalah 0, struktur HTTP_SSL_CLIENT_CERT_INFO telah ditulis dengan anggota CertEncodedSize yang diisi. Pemanggil harus memanggil fungsi lagi dengan buffer yang setidaknya berukuran, dalam byte, dari struktur HTTP_SSL_CLIENT_CERT_INFO ditambah nilai anggota CertEncodedSize . Saat parameter BenderaHTTP_RECEIVE_SECURE_CHANNEL_TOKEN, struktur HTTP_REQUEST_CHANNEL_BIND_STATUS telah ditulis dengan anggota ChannelTokenSize yang diisi. Pemanggil harus memanggil fungsi lagi dengan buffer yang setidaknya berukuran, dalam byte, dari HTTP_REQUEST_CHANNEL_BIND_STATUS ditambah nilai anggota ChannelTokenSize .
ERROR_NOT_FOUND	Fungsi tidak dapat menemukan sertifikat klien atau CBT.
Lainnya	Kode kesalahan sistem yang ditentukan dalam file header WinError.h.

Keterangan

Perilaku fungsi HttpReceiveClientCertificate bervariasi berdasarkan apakah sertifikat SSL klien atau token pengikatan saluran diminta.

Dalam kasus panggilan sinkron ke fungsi HttpReceiveClientCertificate , jumlah byte yang diterima dikembalikan dalam nilai yang ditunjukkan oleh parameter pBytesReceived .

Dalam kasus panggilan asinkron ke fungsi HttpReceiveClientCertificate , jumlah byte yang diterima dikembalikan oleh mekanisme standar yang digunakan untuk panggilan asinkron. Parameter lpNumberOfBytesTransferred yang dikembalikan oleh fungsi GetOverlappedResult berisi jumlah byte yang diterima.

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