httpReceiveClientCertificate 函数 (http.h)
服务器应用程序使用 HttpReceiveClientCertificate 函数 (CBT) 检索客户端 SSL 证书或通道绑定令牌。
语法
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
);
parameters
[in] RequestQueueHandle
与指定的 SSL 客户端或 CBT 关联的请求队列的句柄。 创建请求队列，并通过调用 HttpCreateRequestQueue 函数返回其句柄。
带 SP1 的 Windows Server 2003 和 SP2 的 Windows XP： 请求队列的句柄由 HttpCreateHttpHandle 函数创建。
[in] ConnectionId
一个 值，该值标识与客户端的连接。 此值是从由 HttpReceiveHttpRequest 函数填充的 HTTP_REQUEST 结构的 ConnectionId 元素获取的。
[in] Flags
修改 HttpReceiveClientCertificate 函数行为的值
| 值 | 含义 |
|---|---|
|
pSslClientCertInfo 参数将填充 CBT 数据。
Windows 7、Windows Server 2008 R2 及更高版本支持此值。 |
[out] SslClientCertInfo
如果 Flags 参数为 0，则此参数指向 HTTP_SSL_CLIENT_CERT_INFO 结构，函数在其中写入请求的客户端证书信息。 pSslClientCertInfo 指向的缓冲区应足够大，足以容纳HTTP_SSL_CLIENT_CERT_INFO结构以及此结构的 CertEncodedSize 成员的值。
如果 Flags 参数 HTTP_RECEIVE_SECURE_CHANNEL_TOKEN，则此参数指向函数将请求的 CBT 信息写入到的 HTTP_REQUEST_CHANNEL_BIND_STATUS 结构。 pSslClientCertInfo 指向的缓冲区应足够大，足以容纳HTTP_REQUEST_CHANNEL_BIND_STATUS结构以及此结构的 ChannelTokenSize 成员的值。
[in] SslClientCertInfoSize
pSslClientCertInfo 参数指向的缓冲区的大小（以字节为单位）。
[out, optional] BytesReceived
指向变量的可选指针，该变量接收要写入 pSslClientCertInfo 所指向的结构的字节数。 如果未使用，请将其设置为 NULL。
使用 pOverlapped 进行异步调用时，请将 pBytesReceived 设置为 NULL。 否则，当 pOverlapped 设置为 NULL 时， pBytesReceived 必须包含有效的内存地址，并且不能设置为 NULL。
[in, optional] Overlapped
对于异步调用，请将 pOverlapped 设置为指向 OVERLAPPED 结构;对于同步调用，将其设置为 NULL。
同步调用会阻止，直到检索到客户端证书，而异步调用会立即返回 ERROR_IO_PENDING 然后调用应用程序使用 GetOverlappedResult 或 I/O 完成端口来确定操作何时完成。 有关使用 OVERLAPPED 结构进行同步的详细信息，请参阅 同步和重叠输入和输出部分。
返回值
| 值 | 含义 |
|---|---|
|
函数成功。
所有数据都已写入 pSslClientCertInfo 参数指向的缓冲区。 NumberOfBytesTransferred 指示已写入缓冲区的字节数。 |
|
函数正在异步使用。 操作已启动，稍后将通过正常的重叠 I/O 完成机制完成。 |
|
提供的一个或多个参数无效。 |
|
pSslClientCertInfo 参数指向的缓冲区太小，无法接收数据，并且未写入任何数据。 |
|
pSslClientCertInfo 参数指向的缓冲区不够大，无法接收所有数据。 仅编写了基本结构，并且仅部分填充。
当 Flags 参数为 0 时， HTTP_SSL_CLIENT_CERT_INFO 结构已使用 填充的 CertEncodedSize 成员编写。 调用方应再次调用函数，缓冲区至少为 HTTP_SSL_CLIENT_CERT_INFO 结构的大小（以字节为单位）加上 CertEncodedSize 成员的值。 HTTP_RECEIVE_SECURE_CHANNEL_TOKENFlags 参数时，HTTP_REQUEST_CHANNEL_BIND_STATUS结构已填充 ChannelTokenSize 成员。 调用方应再次调用函数，其缓冲区至少为 HTTP_REQUEST_CHANNEL_BIND_STATUS 的大小（以字节为单位 ） 加上 ChannelTokenSize 成员的值。 |
|
函数找不到客户端证书或 CBT。 |
|
WinError.h 头文件中定义的系统错误代码。 |
注解
HttpReceiveClientCertificate 函数的行为因请求的是客户端 SSL 证书还是通道绑定令牌而异。
在对 HttpReceiveClientCertificate 函数进行同步调用的情况下，接收的字节数在 pBytesReceived 参数指向的值中返回。
在对 HttpReceiveClientCertificate 函数进行异步调用时，接收的字节数由用于异步调用的标准机制返回。 GetOverlappedResult 函数返回的 lpNumberOfBytesTransferred 参数包含接收的字节数。
要求
| 最低受支持的客户端 | Windows Vista、Windows XP 和 SP2 [仅限桌面应用] |
| 最低受支持的服务器 | Windows Server 2003 [仅限桌面应用] |
| 目标平台 | Windows |
| 标头 | http.h |
| Library | Httpapi.lib |
| DLL | Httpapi.dll |