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 を OVERLAPPED 構造体を指すように設定するか、同期呼び出しの場合は NULL に設定 します。
同期呼び出しは、クライアント証明書が取得されるまでブロックしますが、非同期呼び出しはすぐに ERROR_IO_PENDING を返し、呼び出し元のアプリケーションは GetOverlappedResult または I/O 完了ポートを使用して、操作がいつ完了するかを判断します。 同期に OVERLAPPED 構造体を使用する方法の詳細については、「 同期」および「重複入力と出力」セクションを参照してください。
戻り値
| 値 | 説明 |
|---|---|
|
関数が正常に実行されました。
すべてのデータは、 pSslClientCertInfo パラメーターによって指されるバッファーに書き込まれています。 NumberOfBytesTransferred は、バッファーに書き込まれたバイト数を示します。 |
|
関数は非同期的に使用されています。 操作は開始され、通常の重複した I/O 完了メカニズムを使用して後で完了します。 |
|
指定されたパラメーターの 1 つ以上が無効です。 |
|
pSslClientCertInfo パラメーターが指すバッファーが小さすぎてデータを受信せず、データが書き込まれなかった。 |
|
pSslClientCertInfo パラメーターが指すバッファーは、すべてのデータを受信するのに十分な大きさではありません。 基本構造のみが書き込まれ、部分的にしか設定されていません。
Flags パラメーターが 0 の場合、CertEncodedSize メンバーが設定されたHTTP_SSL_CLIENT_CERT_INFO構造体が書き込まれています。 呼び出し元は、 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 |
| Library | Httpapi.lib |
| [DLL] | Httpapi.dll |