функция обратного вызова WINHTTP_STATUS_CALLBACK (winhttp.h)

Статья
03/15/2023

Тип WINHTTP_STATUS_CALLBACK представляет функцию обратного вызова состояния, определяемую приложением.

Синтаксис

WINHTTP_STATUS_CALLBACK WinhttpStatusCallback;

void WinhttpStatusCallback(
  [in] HINTERNET hInternet,
  [in] DWORD_PTR dwContext,
  [in] DWORD dwInternetStatus,
  [in] LPVOID lpvStatusInformation,
  [in] DWORD dwStatusInformationLength
)
{...}

Параметры

[in] hInternet

Дескриптор, для которого вызывается функция обратного вызова.

[in] dwContext

Указатель на DWORD , указывающий определяемое приложением контекстное значение, связанное с дескриптором в параметре hInternet .

Значение контекста можно назначить дескриптору Session, Connect или Request, вызвав WinHttpSetOption с параметром WINHTTP_OPTION_CONTEXT_VALUE . Кроме того, winHttpSendRequest можно использовать для связывания значения контекста с дескриптором запроса.

[in] dwInternetStatus

Указывает на DWORD , указывающий код состояния, указывающий, почему вызывается функция обратного вызова. Может иметь одно из следующих значений:

WINHTTP_CALLBACK_STATUS_CLOSING_CONNECTION

Закрытие подключения к серверу. Параметр lpvStatusInformation имеет значение NULL.

WINHTTP_CALLBACK_STATUS_CONNECTED_TO_SERVER

Успешно подключено к серверу. Параметр lpvStatusInformation содержит указатель на LPWSTR , который указывает IP-адрес сервера в пунктирной нотации.

WINHTTP_CALLBACK_STATUS_CONNECTING_TO_SERVER

Подключение к серверу. Параметр lpvStatusInformation содержит указатель на LPWSTR , который указывает IP-адрес сервера в пунктирной нотации.

WINHTTP_CALLBACK_STATUS_CONNECTION_CLOSED

Подключение к серверу успешно закрыто. Параметр lpvStatusInformation имеет значение NULL.

WINHTTP_CALLBACK_STATUS_DATA_AVAILABLE

Данные доступны для извлечения с помощью WinHttpReadData. Параметр lpvStatusInformation указывает на DWORD , содержащий количество доступных байтов данных. Сам параметр dwStatusInformationLength равен 4 (размер DWORD).

WINHTTP_CALLBACK_STATUS_HANDLE_CREATED

Создан дескриптор HINTERNET . Параметр lpvStatusInformation содержит указатель на дескриптор HINTERNET .

WINHTTP_CALLBACK_STATUS_HANDLE_CLOSING

Это значение дескриптора завершено. Параметр lpvStatusInformation содержит указатель на дескриптор HINTERNET . Для этого дескриптора больше не будет обратных вызовов.

WINHTTP_CALLBACK_STATUS_HEADERS_AVAILABLE

Заголовок ответа получен и доступен в WinHttpQueryHeaders. Параметр lpvStatusInformation имеет значение NULL.

WINHTTP_CALLBACK_STATUS_INTERMEDIATE_RESPONSE

Получено промежуточное сообщение с кодом состояния (100 уровня) от сервера. Параметр lpvStatusInformation содержит указатель на DWORD , указывающий код состояния.

WINHTTP_CALLBACK_STATUS_NAME_RESOLVED

IP-адрес сервера успешно найден. Параметр lpvStatusInformation содержит указатель на LPWSTR , указывающий имя, которое было разрешено.

WINHTTP_CALLBACK_STATUS_READ_COMPLETE

Данные были успешно считаны с сервера. Параметр lpvStatusInformation содержит указатель на буфер, указанный в вызове WinHttpReadData. Параметр dwStatusInformationLength содержит число прочитанных байтов.

При использовании WinHttpWebSocketReceive параметр lpvStatusInformation содержит указатель на структуру WINHTTP_WEB_SOCKET_STATUS , а параметр dwStatusInformationLength указывает размер lpvStatusInformationInformation.

WINHTTP_CALLBACK_STATUS_RECEIVING_RESPONSE

Ожидание ответа сервера на запрос. Параметр lpvStatusInformation имеет значение NULL.

WINHTTP_CALLBACK_STATUS_REDIRECT

HTTP-запрос будет автоматически перенаправлять запрос. Параметр lpvStatusInformation содержит указатель на LPWSTR , указывающий на новый URL-адрес. На этом этапе приложение может считывать любые данные, возвращенные сервером с ответом перенаправления, и может запрашивать заголовки ответа. Он также может отменить операцию, закрыв дескриптор.

WINHTTP_CALLBACK_STATUS_REQUEST_ERROR

Ошибка при отправке HTTP-запроса. Параметр lpvStatusInformation содержит указатель на структуру WINHTTP_ASYNC_RESULT . Его член dwResult указывает идентификатор вызываемой функции, а dwError — возвращаемое значение.

WINHTTP_CALLBACK_STATUS_REQUEST_SENT

Запрос сведений успешно отправлен на сервер. Параметр lpvStatusInformation содержит указатель на DWORD , указывающий количество отправленных байтов.

WINHTTP_CALLBACK_STATUS_RESOLVING_NAME

Поиск IP-адреса имени сервера. Параметр lpvStatusInformation содержит указатель на разрешаемое имя сервера.

WINHTTP_CALLBACK_STATUS_RESPONSE_RECEIVED

Успешно получен ответ от сервера. Параметр lpvStatusInformation содержит указатель на DWORD , указывающий количество полученных байтов.

WINHTTP_CALLBACK_STATUS_SECURE_FAILURE

При установке безопасного (HTTPS) подключения к серверу произошла одна или несколько ошибок. Параметр lpvStatusInformation содержит указатель на DWORD , представляющий собой побитовое или сочетание значений ошибок. Дополнительные сведения см. в описании lpvStatusInformation.

WINHTTP_CALLBACK_STATUS_SENDING_REQUEST

Отправка запроса информации на сервер. Параметр lpvStatusInformation имеет значение NULL.

WINHTTP_CALLBACK_STATUS_SENDREQUEST_COMPLETE

Запрос успешно выполнен. Параметр lpvStatusInformation — это значение lpOptional, передаваемое в WinHttpSendRequest (начальный текст запроса), а параметр dwStatusInformationLength указывает количество успешно записанных начальных байтов тела (значение dwOptionalLength, переданное в WinHttpSendRequest).

WINHTTP_CALLBACK_STATUS_WRITE_COMPLETE

Данные успешно записаны на сервер. Параметр lpvStatusInformation содержит указатель на DWORD , указывающий количество записанных байтов.

При использовании WinHttpWebSocketSend параметр lpvStatusInformation содержит указатель на структуру WINHTTP_WEB_SOCKET_STATUS , а параметр dwStatusInformationLength указывает размер lpvStatusInformationInformation.

WINHTTP_CALLBACK_STATUS_GETPROXYFORURL_COMPLETE

Операция, инициированная вызовом WinHttpGetProxyForUrlEx , завершена. Данные доступны для извлечения с помощью WinHttpReadData.

WINHTTP_CALLBACK_STATUS_CLOSE_COMPLETE

Подключение было успешно закрыто с помощью вызова WinHttpWebSocketClose. Параметр lpvStatusInformation имеет значение NULL.

WINHTTP_CALLBACK_STATUS_SHUTDOWN_COMPLETE

Подключение было успешно завершено с помощью вызова WinHttpWebSocketShutdown. Параметр lpvStatusInformation имеет значение NULL.

[in] lpvStatusInformation

Указатель на буфер, указывающий сведения, относящиеся к этому вызову функции обратного вызова. Формат этих данных зависит от значения аргумента dwInternetStatus . Дополнительные сведения см. в разделе dwInternetStatus.

Если аргумент dwInternetStatus имеет WINHTTP_CALLBACK_STATUS_SECURE_FAILURE, то lpvStatusInformation указывает на DWORD, который представляет собой побитовую или комбинацию одного или нескольких из следующих значений.

Значение	Значение
WINHTTP_CALLBACK_STATUS_FLAG_CERT_REV_FAILED	Проверка отзыва сертификатов включена, но проверка отзыва не смогла проверить, был ли отозван сертификат. Сервер, используемый для проверки отзыва, может оказаться недоступным.
WINHTTP_CALLBACK_STATUS_FLAG_INVALID_CERT	SSL-сертификат недопустим.
WINHTTP_CALLBACK_STATUS_FLAG_CERT_REVOKED	SSL-сертификат был отозван.
WINHTTP_CALLBACK_STATUS_FLAG_INVALID_CA	Функция не знакома с центром сертификации, который создал сертификат сервера.
WINHTTP_CALLBACK_STATUS_FLAG_CERT_CN_INVALID	Общее имя SSL-сертификата (поле имени узла) неверно, например, если вы ввели www.microsoft.com, а общее имя в сертификате означает www.msn.com.
WINHTTP_CALLBACK_STATUS_FLAG_CERT_DATE_INVALID	Недопустимая дата получения SSL-сертификата с сервера. Срок действия сертификата истек.
WINHTTP_CALLBACK_STATUS_FLAG_SECURITY_CHANNEL_ERROR	Приложение столкнулось с внутренней ошибкой при загрузке библиотек SSL.

[in] dwStatusInformationLength

WINHTTP_CALLBACK_STATUS_REDIRECT обратные вызовы состояния предоставляют значение dwStatusInformationLength , соответствующее количеству символов LPWSTR , на который указывает lpvStatusInformation.

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

None

Remarks

Функция обратного вызова должна быть threadsafe и reentrant, так как ее можно вызвать в другом потоке для отдельного запроса и повторно ввести в том же потоке для текущего запроса. Поэтому он должен быть закодирован для безопасной обработки повторного входенения. Если параметр dwInternetStatus равен WINHTTP_CALLBACK_STATUS_HANDLE_CLOSING, обратный вызов не должен обрабатывать повторный ввод для того же запроса, так как этот обратный вызов гарантированно является последним и не выполняется при обработке других сообщений для этого запроса.

Функция обратного вызова состояния получает обновления о состоянии асинхронных операций с помощью флагов уведомлений. Уведомления, указывающие, что определенная операция завершена, называются уведомлениями о завершении или просто завершениями. В следующей таблице перечислены шесть флагов завершения и соответствующая функция, которая завершается при получении этого флага.

Флаг завершения	Функция
WINHTTP_CALLBACK_STATUS_DATA_AVAILABLE	WinHttpQueryDataAvailable
WINHTTP_CALLBACK_STATUS_HEADERS_AVAILABLE	WinHttpReceiveResponse
WINHTTP_CALLBACK_STATUS_READ_COMPLETE	WinHttpReadData
WINHTTP_CALLBACK_STATUS_SENDREQUEST_COMPLETE	WinHttpSendRequest
WINHTTP_CALLBACK_STATUS_WRITE_COMPLETE	WinHttpWriteData
WINHTTP_CALLBACK_STATUS_REQUEST_ERROR	Любой из перечисленных выше функций при возникновении ошибки.

Так как обратные вызовы выполняются во время обработки запроса, приложение должно тратить как можно меньше времени на функцию обратного вызова, чтобы избежать снижения пропускной способности данных в сети. Например, отображение диалогового окна в функции обратного вызова может быть такой длительной операцией, что сервер завершает запрос.

Функция обратного вызова может вызываться в контексте потока, отличном от потока, который инициировал запрос.

Аналогичным образом, при асинхронном вызове WinHttp отсутствует сходство потоков обратного вызова: вызов может начинаться из одного потока, но любой другой поток может принимать обратный вызов.

Примечание Дополнительные сведения о реализации в Windows XP и Windows 2000 см. в разделе Требования к времени выполнения.

Требования

Требование	Значение
Минимальная версия клиента	Windows XP, Windows 2000 Профессиональная с пакетом обновления 3 (SP3) [только классические приложения]
Минимальная версия сервера	Windows Server 2003, Windows 2000 Server с пакетом обновления 3 (SP3) [только классические приложения]
Целевая платформа	Windows
Header	winhttp.h
Распространяемые компоненты	WinHTTP 5.0 и Internet Explorer 5.01 или более поздней версии в Windows XP и Windows 2000.

См. также раздел

Версии WinHTTP

WinHttpSetStatusCallback

Поделиться через