Функция HttpReceiveClientCertificate (http.h)

Статья
08/24/2023

Функция 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 с пакетом обновления 1 (SP1) и Windows XP с пакетом обновления 2 (SP2): Дескриптор очереди запросов создается функцией HttpCreateHttpHandle .

[in] ConnectionId

Значение типа , определяющее подключение к клиенту. Это значение получается из элемента ConnectionIdструктуры HTTP_REQUEST , заполненной функцией HttpReceiveHttpRequest .

[in] Flags

Значение , изменяющее поведение функции HttpReceiveClientCertificate .

Значение	Значение
HTTP_RECEIVE_SECURE_CHANNEL_TOKEN 0x1	Параметр pSslClientCertInfo будет заполнен данными CBT. Это значение поддерживается в Windows 7, Windows Server 2008 R2 и более поздних версиях.

[out] SslClientCertInfo

Если параметр Flags равен 0, то этот параметр указывает на структуру HTTP_SSL_CLIENT_CERT_INFO , в которую функция записывает запрошенные сведения о сертификате клиента. Буфер, на который указывает pSslClientCertInfo , должен быть достаточно большим, чтобы вместить структуру HTTP_SSL_CLIENT_CERT_INFO плюс значение члена CertEncodedSize этой структуры.

Если параметр FlagsHTTP_RECEIVE_SECURE_CHANNEL_TOKEN, то этот параметр указывает на HTTP_REQUEST_CHANNEL_BIND_STATUS структуру, в которую функция записывает запрошенные данные CBT. Буфер, на который указывает 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 или завершения ввода-вывода, чтобы определить, когда операция завершена. Дополнительные сведения об использовании структур OVERLAPPED для синхронизации см. в разделе Синхронизация и перекрытие входных и выходных данных.

Возвращаемое значение

Значение	Значение
NO_ERROR	Функция выполнена успешно. Все данные записаны в буфер, на который указывает параметр pSslClientCertInfo . NumberOfBytesTransferred указывает, сколько байтов было записано в буфер.
ERROR_IO_PENDING	Функция используется асинхронно. Операция была инициирована и будет завершена позже с помощью обычных перекрывающихся механизмов завершения ввода-вывода.
ERROR_INVALID_PARAMETER	Один или несколько предоставленных параметров являются недопустимыми.
ERROR_INSUFFICIENT_BUFFER	Буфер, на который указывает параметр pSslClientCertInfo , слишком мал для получения данных, и данные не были записаны.
ERROR_MORE_DATA	Буфер, на который указывает параметр pSslClientCertInfo , недостаточно велик для получения всех данных. Написана и частично заполнена только базовая структура. Если параметр Flags равен 0, структура HTTP_SSL_CLIENT_CERT_INFO написана с заполненным элементом CertEncodedSize . Вызывающий объект должен снова вызвать функцию с буфером, размером по крайней мере в байтах структуры HTTP_SSL_CLIENT_CERT_INFO плюс значением члена CertEncodedSize . Если параметр FlagsHTTP_RECEIVE_SECURE_CHANNEL_TOKEN, структура HTTP_REQUEST_CHANNEL_BIND_STATUS написана с заполненным элементом ChannelTokenSize . Вызывающий объект должен снова вызвать функцию с буфером, равным по крайней мере размеру (в байтах) HTTP_REQUEST_CHANNEL_BIND_STATUS плюс значение члена ChannelTokenSize .
ERROR_NOT_FOUND	Функция не может найти сертификат клиента или CBT.
Другое	Код системной ошибки, определенный в файле заголовка WinError.h.

В случае асинхронного вызова функции HttpReceiveClientCertificate число полученных байтов возвращается стандартными механизмами, используемыми для асинхронных вызовов. Параметр lpNumberOfBytesTransferred , возвращаемый функцией GetOverlappedResult , содержит количество полученных байтов.

Требования


Минимальная версия клиента	Windows Vista, Windows XP с пакетом обновления 2 (SP2) [только классические приложения]
Минимальная версия сервера	Windows Server 2003 [только классические приложения]
Целевая платформа	Windows
Header	http.h
Библиотека	Httpapi.lib
DLL	Httpapi.dll