Funzione HttpReceiveClientCertificate (http.h)

Articolo
08/24/2023

La funzione HttpReceiveClientCertificate viene usata da un'applicazione server per recuperare un certificato SSL client o un token di associazione del canale (CBT).

Sintassi

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
);

Parametri

[in] RequestQueueHandle

Handle per la coda di richieste a cui è associato il client SSL specificato o CBT. Viene creata una coda di richieste e il relativo handle restituito da una chiamata alla funzione HttpCreateRequestQueue .

Windows Server 2003 con SP1 e Windows XP con SP2: L'handle per la coda di richieste viene creato dalla funzione HttpCreateHttpHandle .

[in] ConnectionId

Valore che identifica la connessione al client. Questo valore viene ottenuto dall'elemento ConnectionId di una struttura HTTP_REQUEST compilata dalla funzione HttpReceiveHttpRequest .

[in] Flags

Valore che modifica il comportamento della funzione HttpReceiveClientCertificate

Valore	Significato
HTTP_RECEIVE_SECURE_CHANNEL_TOKEN 0x1	Il parametro pSslClientCertInfo verrà popolato con i dati CBT. Questo valore è supportato in Windows 7, Windows Server 2008 R2 e versioni successive.

[out] SslClientCertInfo

Se il parametro Flags è 0, questo parametro punta a una struttura HTTP_SSL_CLIENT_CERT_INFO in cui la funzione scrive le informazioni sul certificato client richieste. Il buffer a cui punta pSslClientCertInfo deve essere sufficientemente grande da contenere la struttura HTTP_SSL_CLIENT_CERT_INFO più il valore del membro CertEncodedSize di questa struttura.

Se il parametro Flags è HTTP_RECEIVE_SECURE_CHANNEL_TOKEN, questo parametro punta a una struttura HTTP_REQUEST_CHANNEL_BIND_STATUS in cui la funzione scrive le informazioni CBT richieste. Il buffer a cui punta pSslClientCertInfo deve essere sufficientemente grande da contenere la struttura HTTP_REQUEST_CHANNEL_BIND_STATUS più il valore del membro ChannelTokenSize di questa struttura.

[in] SslClientCertInfoSize

Dimensione, in byte, del buffer a cui punta il parametro pSslClientCertInfo .

[out, optional] BytesReceived

Puntatore facoltativo a una variabile che riceve il numero di byte da scrivere nella struttura a cui punta pSslClientCertInfo. Se non viene usato, impostarlo su NULL.

Quando si effettua una chiamata asincrona tramite pOverlapped, impostare pBytesReceived su NULL. In caso contrario, quando pOverlapped è impostato su NULL, pBytesReceived deve contenere un indirizzo di memoria valido e non essere impostato su NULL.

[in, optional] Overlapped

Per le chiamate asincrone, impostare pOverlapped in modo che punti a una struttura OVERLAPPED o per le chiamate sincrone, impostarla su NULL.

Una chiamata sincrona si blocca finché non viene recuperato il certificato client, mentre una chiamata asincrona restituisce immediatamente ERROR_IO_PENDING e l'applicazione chiamante usa quindi le porte di completamento GetOverlappedResult o I/O per determinare quando l'operazione viene completata. Per altre informazioni sull'uso di strutture OVERLAPPED per la sincronizzazione, vedere la sezione Sincronizzazione e input e output sovrapposti.

Valore restituito

Valore	Significato
NO_ERROR	Funzione completata. Tutti i dati sono stati scritti nel buffer a cui punta il parametro pSslClientCertInfo . NumberOfBytesTransferred indica il numero di byte scritti nel buffer.
ERROR_IO_PENDING	La funzione viene usata in modo asincrono. L'operazione è stata avviata e verrà completata in un secondo momento tramite normali meccanismi di completamento di I/O sovrapposti.
ERROR_INVALID_PARAMETER	Uno o più parametri forniti non sono validi.
ERROR_INSUFFICIENT_BUFFER	Il buffer a cui punta il parametro pSslClientCertInfo è troppo piccolo per ricevere i dati e non sono stati scritti dati.
ERROR_MORE_DATA	Il buffer a cui punta il parametro pSslClientCertInfo non è sufficiente per ricevere tutti i dati. Solo la struttura di base è stata scritta e popolata solo parzialmente. Quando il parametro Flags è 0, la struttura HTTP_SSL_CLIENT_CERT_INFO è stata scritta con il membro CertEncodedSize popolato. Il chiamante deve chiamare di nuovo la funzione con un buffer con almeno le dimensioni, in byte, della struttura HTTP_SSL_CLIENT_CERT_INFO più il valore del membro CertEncodedSize . Quando il parametro Flags è HTTP_RECEIVE_SECURE_CHANNEL_TOKEN, la struttura HTTP_REQUEST_CHANNEL_BIND_STATUS è stata scritta con il membro ChannelTokenSize popolato. Il chiamante deve chiamare di nuovo la funzione con un buffer con almeno le dimensioni, in byte, del HTTP_REQUEST_CHANNEL_BIND_STATUS più il valore del membro ChannelTokenSize .
ERROR_NOT_FOUND	La funzione non riesce a trovare il certificato client o CBT.
Altri	Codice di errore di sistema definito nel file di intestazione WinError.h.

Commenti

Il comportamento della funzione HttpReceiveClientCertificate varia a seconda che venga richiesto un certificato SSL client o un token di associazione del canale.

Nel caso di una chiamata sincrona alla funzione HttpReceiveClientCertificate , il numero di byte ricevuti viene restituito nel valore a cui punta il parametro pBytesReceived .

Nel caso di una chiamata asincrona alla funzione HttpReceiveClientCertificate , il numero di byte ricevuti viene restituito dai meccanismi standard usati per le chiamate asincrone. Il parametro lpNumberOfBytesTransferred restituito dalla funzione GetOverlappedResult contiene il numero di byte ricevuti.

Requisiti


Client minimo supportato	Windows Vista, Windows XP con SP2 [solo app desktop]
Server minimo supportato	Windows Server 2003 [solo app desktop]
Piattaforma di destinazione	Windows
Intestazione	http.h
Libreria	Httpapi.lib
DLL	Httpapi.dll