Fonction HttpReceiveClientCertificate (http.h)

Article
08/24/2023

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

Valeur	Signification
HTTP_RECEIVE_SECURE_CHANNEL_TOKEN 0x1	Le paramètre pSslClientCertInfo sera rempli avec des données CBT. Cette valeur est prise en charge sur Windows 7, Windows Server 2008 R2 et versions ultérieures.

[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
NO_ERROR	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.
ERROR_IO_PENDING	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.
ERROR_INVALID_PARAMETER	Un ou plusieurs des paramètres fournis ne sont pas valides.
ERROR_INSUFFICIENT_BUFFER	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.
ERROR_MORE_DATA	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 .
ERROR_NOT_FOUND	La fonction ne trouve pas le certificat client ou le CBT.
Autres	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