Fonction HttpReceiveClientCertificate (http.h)
La fonction HttpReceiveClientCertificate est utilisée par une application serveur pour récupérer un certificat SSL client ou un jeton de liaison de canal (CBT).
Syntaxe
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
);
Paramètres
[in] RequestQueueHandle
Handle de la file d’attente de requêtes à laquelle le client SSL ou CBT spécifié est associé. Une file d’attente de requêtes est créée et son handle est retourné par un appel à la fonction HttpCreateRequestQueue .
Windows Server 2003 avec SP1 et Windows XP avec SP2 : Le handle de la file d’attente de requête est créé par la fonction HttpCreateHttpHandle .
[in] ConnectionId
Valeur qui identifie la connexion au client. Cette valeur est obtenue à partir de l’élément ConnectionId d’une structure HTTP_REQUEST remplie par la fonction HttpReceiveHttpRequest .
[in] Flags
Valeur qui modifie le comportement de la fonction HttpReceiveClientCertificate
[out] SslClientCertInfo
Si le paramètre Flags est 0, ce paramètre pointe vers une structure HTTP_SSL_CLIENT_CERT_INFO dans laquelle la fonction écrit les informations de certificat client demandées. La mémoire tampon pointée par le pSslClientCertInfo doit être suffisamment grande pour contenir la structure HTTP_SSL_CLIENT_CERT_INFO plus la valeur du membre CertEncodedSize de cette structure.
Si le paramètre Flags est HTTP_RECEIVE_SECURE_CHANNEL_TOKEN, ce paramètre pointe vers une structure HTTP_REQUEST_CHANNEL_BIND_STATUS dans laquelle la fonction écrit les informations CBT demandées. La mémoire tampon pointée par le pSslClientCertInfo doit être suffisamment grande pour contenir la structure HTTP_REQUEST_CHANNEL_BIND_STATUS plus la valeur du membre ChannelTokenSize de cette structure.
[in] SslClientCertInfoSize
Taille, en octets, de la mémoire tampon pointée vers le paramètre pSslClientCertInfo .
[out, optional] BytesReceived
Pointeur facultatif vers une variable qui reçoit le nombre d’octets à écrire dans la structure pointée par pSslClientCertInfo. S’il n’est pas utilisé, définissez-le sur NULL.
Lorsque vous effectuez un appel asynchrone à l’aide de pOverlapped, définissez pBytesReceived surNULL. Sinon, lorsque pOverlapped a la valeur NULL, pBytesReceived doit contenir une adresse mémoire valide et ne pas avoir la valeur NULL.
[in, optional] Overlapped
Pour les appels asynchrones, définissez pOverlapped pour qu’il pointe vers une structure CHEVAUCHEMENT OU , pour les appels synchrones, définissez-la sur NULL.
Un appel synchrone se bloque jusqu’à ce que le certificat client soit récupéré, tandis qu’un appel asynchrone retourne immédiatement ERROR_IO_PENDING et que l’application appelante utilise alors les ports d’achèvement GetOverlappedResult ou D’E/S pour déterminer quand l’opération est terminée. Pour plus d’informations sur l’utilisation des structures OVERLAPPED pour la synchronisation, consultez la section Synchronisation et entrées et sorties qui se chevauchent.
Valeur retournée
| Valeur | Signification |
|---|---|
|
La fonction a réussi.
Toutes les données ont été écrites dans la mémoire tampon vers laquelle pointe le paramètre pSslClientCertInfo . NumberOfBytesTransferred indique le nombre d’octets qui ont été écrits dans la mémoire tampon. |
|
La fonction est utilisée de manière asynchrone. L’opération a été lancée et se terminera plus tard par le biais de mécanismes d’achèvement d’E/S qui se chevauchent normalement. |
|
Un ou plusieurs des paramètres fournis ne sont pas valides. |
|
La mémoire tampon pointée vers le paramètre pSslClientCertInfo est trop petite pour recevoir les données et aucune donnée n’a été écrite. |
|
La mémoire tampon pointée vers le paramètre pSslClientCertInfo n’est pas assez grande pour recevoir toutes les données. Seule la structure de base a été écrite et partiellement renseignée.
Lorsque le paramètre Flags a la valeur 0, la structure HTTP_SSL_CLIENT_CERT_INFO a été écrite avec le membre CertEncodedSize renseigné. L’appelant doit à nouveau appeler la fonction avec une mémoire tampon qui correspond au moins à la taille, en octets, de la structure HTTP_SSL_CLIENT_CERT_INFO plus la valeur du membre CertEncodedSize . Lorsque le paramètre Flags est HTTP_RECEIVE_SECURE_CHANNEL_TOKEN, la structure HTTP_REQUEST_CHANNEL_BIND_STATUS a été écrite avec le membre ChannelTokenSize renseigné. L’appelant doit appeler à nouveau la fonction avec une mémoire tampon qui correspond au moins à la taille, en octets, du HTTP_REQUEST_CHANNEL_BIND_STATUS plus la valeur du membre ChannelTokenSize . |
|
La fonction ne trouve pas le certificat client ou le CBT. |
|
Code d’erreur système défini dans le fichier d’en-tête WinError.h . |
Notes
Le comportement de la fonction HttpReceiveClientCertificate varie selon qu’un certificat SSL client ou un jeton de liaison de canal est demandé.
Dans le cas d’un appel synchrone à la fonction HttpReceiveClientCertificate , le nombre d’octets reçus est retourné dans la valeur pointée vers le paramètre pBytesReceived .
Dans le cas d’un appel asynchrone à la fonction HttpReceiveClientCertificate , le nombre d’octets reçus est retourné par les mécanismes standard utilisés pour les appels asynchrones. Le paramètre lpNumberOfBytesTransferred retourné par la fonction GetOverlappedResult contient le nombre d’octets reçus.
Configuration requise
| Client minimal pris en charge | Windows Vista, Windows XP avec SP2 [applications de bureau uniquement] |
| Serveur minimal pris en charge | Windows Server 2003 [applications de bureau uniquement] |
| Plateforme cible | Windows |
| En-tête | http.h |
| Bibliothèque | Httpapi.lib |
| DLL | Httpapi.dll |
Voir aussi
Fonctions API de serveur HTTP version 1.0