Функция WinHttpSetStatusCallback (winhttp.h)

Статья
03/15/2023

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

Синтаксис

WINHTTPAPI WINHTTP_STATUS_CALLBACK WinHttpSetStatusCallback(
  [in] HINTERNET               hInternet,
  [in] WINHTTP_STATUS_CALLBACK lpfnInternetCallback,
  [in] DWORD                   dwNotificationFlags,
  [in] DWORD_PTR               dwReserved
);

Параметры

[in] hInternet

Дескриптор HINTERNET , для которого должен быть задан обратный вызов.

[in] lpfnInternetCallback

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

[in] dwNotificationFlags

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

Ниже приведены возможные значения.

Значение	Значение
WINHTTP_CALLBACK_FLAG_ALL_COMPLETIONS	Активируется при любом уведомлении о завершении. Этот флаг указывает, что используются все уведомления, необходимые для операций чтения или записи. Список завершений см. в WINHTTP_STATUS_CALLBACK .
WINHTTP_CALLBACK_FLAG_ALL_NOTIFICATIONS	Активируется при любом уведомлении об изменении состояния, включая завершения. Список уведомлений см. в WINHTTP_STATUS_CALLBACK .
WINHTTP_CALLBACK_FLAG_RESOLVE_NAME	Активируется после начала и завершения разрешения имен.
WINHTTP_CALLBACK_FLAG_CONNECT_TO_SERVER	Активируется после начала и завершения подключения к серверу.
WINHTTP_CALLBACK_FLAG_DETECTING_PROXY	Активируется при обнаружении прокси-сервера.
WINHTTP_CALLBACK_FLAG_DATA_AVAILABLE	Активируется при выполнении запроса данных.
WINHTTP_CALLBACK_FLAG_HEADERS_AVAILABLE	Активируется, когда заголовки ответа доступны для получения.
WINHTTP_CALLBACK_FLAG_READ_COMPLETE	Активируется после завершения операции чтения данных.
WINHTTP_CALLBACK_FLAG_REQUEST_ERROR	Активируется при возникновении асинхронной ошибки.
WINHTTP_CALLBACK_FLAG_SEND_REQUEST	Активируется после начала и завершения отправки заголовка запроса с помощью WinHttpSendRequest.
WINHTTP_CALLBACK_FLAG_SENDREQUEST_COMPLETE	Активируется при отправке заголовка запроса с помощью WinHttpSendRequest.
WINHTTP_CALLBACK_FLAG_WRITE_COMPLETE	Активируется после завершения операции после передачи данных.
WINHTTP_CALLBACK_FLAG_RECEIVE_RESPONSE	Активируется после начала и завершения получения ресурса с HTTP-сервера.
WINHTTP_CALLBACK_FLAG_CLOSE_CONNECTION	Активируется при начале и завершении закрытия HTTP-подключения.
WINHTTP_CALLBACK_FLAG_HANDLES	Активируется при создании или закрытии дескриптора HINTERNET .
WINHTTP_CALLBACK_FLAG_REDIRECT	Активируется при перенаправлении запроса.
WINHTTP_CALLBACK_FLAG_INTERMEDIATE_RESPONSE	Активируется при получении промежуточного (уровня 100) сообщения кода состояния от сервера.
WINHTTP_CALLBACK_FLAG_SECURE_FAILURE	Активируется при сбое безопасного подключения.

[in] dwReserved

Этот параметр зарезервирован и должен иметь значение NULL.

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

В случае успешного выполнения возвращает указатель на ранее определенную функцию обратного вызова состояния или значение NULL , если ранее не была определена функция обратного вызова состояния. Возвращает WINHTTP_INVALID_STATUS_CALLBACK , если не удалось установить функцию обратного вызова. Чтобы получить дополнительные сведения об ошибке, вызовите Метод GetLastError. Среди возвращаемых кодов ошибок приведены следующие.

Код ошибки	Описание
ERROR_WINHTTP_INCORRECT_HANDLE_TYPE	Для этой операции указан неправильный тип дескриптора.
ERROR_WINHTTP_INTERNAL_ERROR	Произошла внутренняя ошибка.
ERROR_NOT_ENOUGH_MEMORY	Недостаточно памяти для выполнения запрошенной операции. (Код ошибки Windows)

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

Даже если WinHTTP используется в асинхронном режиме (то есть при установке WINHTTP_FLAG_ASYNC в WinHttpOpen), эта функция работает синхронно. Возвращаемое значение указывает на успех или сбой. Дополнительные сведения об ошибке можно получить, вызвав GetLastError.

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

Функция обратного вызова может быть задана для любого дескриптора и наследуется производными дескрипторами. Функцию обратного вызова можно изменить с помощью WinHttpSetStatusCallback при условии, что нет ожидающих запросов, которые должны использовать предыдущее значение обратного вызова. Однако изменение функции обратного вызова для дескриптора не приводит к изменению обратных вызовов на производных дескрипторах, таких как возвращенные WinHttpConnect. Необходимо изменить функцию обратного вызова на каждом уровне.

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

После инициации функции WinHttpSetStatusCallback к функции обратного вызова можно получить доступ из WinHTTP для мониторинга ресурсоемких сетевых операций.

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

В следующем фрагменте кода показан рекомендуемый метод для задания функции обратного вызова значения NULL.

WinHttpSetStatusCallback( hOpen,
                          NULL,
                          WINHTTP_CALLBACK_FLAG_ALL_NOTIFICATIONS,
                          NULL );

Однако обратите внимание, что WinHTTP не синхронизирует WinHttpSetStatusCallback с рабочими потоками. Если обратный вызов, исходящий из другого потока, выполняется, когда приложение вызывает WinHttpSetStatusCallback, приложение по-прежнему получает уведомление о обратном вызове даже после того, как WinHttpSetStatusCallback успешно задает функцию обратного вызова значение NULL и возвращает.

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

Примеры

В следующем примере показано, как установить функцию обратного вызова для асинхронных функций WinHTTP. В примере предполагается, что функция WINHTTP_STATUS_CALLBACK с именем "AsyncCallback( )" была ранее реализована:

    // Use WinHttpOpen to obtain an HINTERNET handle.
    HINTERNET hSession = WinHttpOpen(L"A WinHTTP Example Program/1.0", 
                                    WINHTTP_ACCESS_TYPE_DEFAULT_PROXY,
                                    WINHTTP_NO_PROXY_NAME, 
                                    WINHTTP_NO_PROXY_BYPASS, 0);
    if (hSession)
    {
        // Install the status callback function.
        WINHTTP_STATUS_CALLBACK isCallback = WinHttpSetStatusCallback( hSession,
                                               (WINHTTP_STATUS_CALLBACK)AsyncCallback,
                                               WINHTTP_CALLBACK_FLAG_ALL_NOTIFICATIONS, 
                                               NULL);
                                               
        // Place additional code here.
    
        // When finished, release the HINTERNET handle.
        WinHttpCloseHandle(hSession);
    }
    else
    {
        printf("Error %u in WinHttpOpen.\n", GetLastError());
    }

Требования

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