HttpReceiveClientCertificate 函式 (HTTP.h)
伺服器應用程式會使用 HttpReceiveClientCertificate 函式來擷取用戶端 SSL 憑證或通道系結權杖， (CBT) 。
語法
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
);
參數
[in] RequestQueueHandle
與指定的 SSL 用戶端或 CBT 相關聯的要求佇列控制碼。 系統會建立要求佇列，並透過呼叫 HttpCreateRequestQueue 函式所傳回的控制碼。
Windows Server 2003 SP1 和 Windows XP SP2： 要求佇列的控制碼是由 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 設定為指向 重迭 結構，或針對同步呼叫，將它設定為 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 成員的值，再次呼叫函式。 當Flags參數HTTP_RECEIVE_SECURE_CHANNEL_TOKEN時，已使用填入ChannelTokenSize成員來撰寫HTTP_REQUEST_CHANNEL_BIND_STATUS結構。 呼叫端應該使用至少大小，以位元組為單位的緩衝區來呼叫函式， 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 |
| 程式庫 | Httpapi.lib |
| Dll | Httpapi.dll |