HttpReceiveClientCertificate-Funktion (http.h)
Die HttpReceiveClientCertificate-Funktion wird von einer Serveranwendung verwendet, um ein Client-SSL-Zertifikat oder kanalbindungstoken (CBT) abzurufen.
Syntax
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
Ein Handle für die Anforderungswarteschlange, der der angegebene SSL-Client oder CBT zugeordnet ist. Eine Anforderungswarteschlange wird erstellt, und ihr Handle wird durch einen Aufruf der HttpCreateRequestQueue-Funktion zurückgegeben.
Windows Server 2003 mit SP1 und Windows XP mit SP2: Das Handle für die Anforderungswarteschlange wird von der HttpCreateHttpHandle-Funktion erstellt.
[in] ConnectionId
Ein Wert, der die Verbindung mit dem Client identifiziert. Dieser Wert wird vom ConnectionId-Element einer HTTP_REQUEST Struktur abgerufen, die von der HttpReceiveHttpRequest-Funktion ausgefüllt wird.
[in] Flags
Ein Wert, der das Verhalten der HttpReceiveClientCertificate-Funktion ändert
| Wert | Bedeutung |
|---|---|
|
Der Parameter pSslClientCertInfo wird mit CBT-Daten aufgefüllt.
Dieser Wert wird unter Windows 7, Windows Server 2008 R2 und höher unterstützt. |
[out] SslClientCertInfo
Wenn der Flags-Parameter 0 ist, verweist dieser Parameter auf eine HTTP_SSL_CLIENT_CERT_INFO Struktur, in die die Funktion die angeforderten Clientzertifikatinformationen schreibt. Der Puffer, auf den das pSslClientCertInfo verweist, sollte ausreichend groß sein, um die HTTP_SSL_CLIENT_CERT_INFO Struktur plus den Wert des CertEncodedSize-Members dieser Struktur zu enthalten.
Wenn der Flags-ParameterHTTP_RECEIVE_SECURE_CHANNEL_TOKEN ist, verweist dieser Parameter auf eine HTTP_REQUEST_CHANNEL_BIND_STATUS-Struktur , in die die Funktion die angeforderten CBT-Informationen schreibt. Der Puffer, auf den das pSslClientCertInfo verweist, sollte ausreichend groß sein, um die HTTP_REQUEST_CHANNEL_BIND_STATUS-Struktur plus den Wert des ChannelTokenSize-Members dieser Struktur zu enthalten.
[in] SslClientCertInfoSize
Die Größe des Puffers in Bytes, auf die der pSslClientCertInfo-Parameter verweist.
[out, optional] BytesReceived
Ein optionaler Zeiger auf eine Variable, die die Anzahl der Bytes empfängt, die in die Struktur geschrieben werden sollen, auf die pSslClientCertInfo verweist. Wenn nicht verwendet, legen Sie es auf NULL fest.
Wenn Sie einen asynchronen Aufruf mithilfe von pOverlapped ausführen, legen Sie pBytesReceived auf NULL fest. Andernfalls muss pBytesReceived eine gültige Speicheradresse enthalten und nicht auf NULL festgelegt werden, wenn pOverlapped auf NULL festgelegt ist.
[in, optional] Overlapped
Legen Sie bei asynchronen Aufrufen pOverlapped auf eine OVERLAPPED-Struktur fest, oder legen Sie sie bei synchronen Aufrufen auf NULL fest.
Ein synchroner Aufruf blockiert, bis das Clientzertifikat abgerufen wird, während ein asynchroner Aufruf sofort ERROR_IO_PENDING zurückgibt, und die aufrufende Anwendung verwendet dann GetOverlappedResult - oder E/A-Vervollständigungsports, um zu bestimmen, wann der Vorgang abgeschlossen ist. Weitere Informationen zur Verwendung von OVERLAPPED-Strukturen für die Synchronisierung finden Sie im Abschnitt Synchronisierung und überlappende Eingabe und Ausgabe.
Rückgabewert
| Wert | Bedeutung |
|---|---|
|
Die Funktion wurde erfolgreich ausgeführt.
Alle Daten wurden in den Puffer geschrieben, auf den der pSslClientCertInfo-Parameter verweist. NumberOfBytesTransferred gibt an, wie viele Bytes in den Puffer geschrieben wurden. |
|
Die Funktion wird asynchron verwendet. Der Vorgang wurde initiiert und wird später über normale überlappende E/A-Vervollständigungsmechanismen abgeschlossen. |
|
Mindestens ein der angegebenen Parameter ist ungültig. |
|
Der Puffer, auf den der pSslClientCertInfo-Parameter verweist, ist zu klein, um die Daten zu empfangen, und es wurden keine Daten geschrieben. |
|
Der Puffer, auf den der pSslClientCertInfo-Parameter verweist, ist nicht groß genug, um alle Daten zu empfangen. Nur die Grundstruktur wurde geschrieben und nur teilweise aufgefüllt.
Wenn der Flags-Parameter 0 ist, wurde die HTTP_SSL_CLIENT_CERT_INFO-Struktur mit aufgefülltem CertEncodedSize-Member geschrieben. Der Aufrufer sollte die Funktion erneut mit einem Puffer aufrufen, der mindestens die Größe der HTTP_SSL_CLIENT_CERT_INFO-Struktur in Bytes und den Wert des CertEncodedSize-Members aufweist. Wenn der Flags-ParameterHTTP_RECEIVE_SECURE_CHANNEL_TOKEN ist, wurde die HTTP_REQUEST_CHANNEL_BIND_STATUS-Struktur mit aufgefülltem ChannelTokenSize-Member geschrieben. Der Aufrufer sollte die Funktion erneut mit einem Puffer aufrufen, der mindestens die Größe des HTTP_REQUEST_CHANNEL_BIND_STATUS in Bytes plus den Wert des ChannelTokenSize-Elements aufweist. |
|
Die Funktion kann das Clientzertifikat oder CBT nicht finden. |
|
Ein Systemfehlercode , der in der WinError.h-Headerdatei definiert ist. |
Hinweise
Das Verhalten der HttpReceiveClientCertificate-Funktion variiert je nachdem, ob ein Client-SSL-Zertifikat oder ein Kanalbindungstoken angefordert wird.
Bei einem synchronen Aufruf der HttpReceiveClientCertificate-Funktion wird die Anzahl der empfangenen Bytes im Wert zurückgegeben, auf den der pBytesReceived-Parameter verweist.
Bei einem asynchronen Aufruf der HttpReceiveClientCertificate-Funktion wird die Anzahl der empfangenen Bytes von den Standardmechanismen zurückgegeben, die für asynchrone Aufrufe verwendet werden. Der lpNumberOfBytesTransferred-Parameter , der von der GetOverlappedResult-Funktion zurückgegeben wird, enthält die Anzahl der empfangenen Bytes.
Anforderungen
| Unterstützte Mindestversion (Client) | Windows Vista, Windows XP mit SP2 [nur Desktop-Apps] |
| Unterstützte Mindestversion (Server) | Windows Server 2003 [nur Desktop-Apps] |
| Zielplattform | Windows |
| Kopfzeile | http.h |
| Bibliothek | Httpapi.lib |
| DLL | Httpapi.dll |
Weitere Informationen
Funktionen der HTTP-Server-API, Version 1.0