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

  • Статья

Функция WinHttpCloseHandle закрывает один дескриптор HINTERNET (см. раздел Дескрипторы HINTERNET в WinHTTP).

Синтаксис

WINHTTPAPI BOOL WinHttpCloseHandle(
  [in] HINTERNET hInternet
);

Параметры

[in] hInternet

Допустимый дескриптор HINTERNET (см . раздел Маркеры HINTERNET в WinHTTP), который необходимо закрыть.

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

Значение TRUE , если дескриптор успешно закрыт, в противном случае — ЗНАЧЕНИЕ FALSE. Дополнительные сведения об ошибке можно получить, вызвав GetLastError. Среди возвращаемых кодов ошибок:

Коды ошибок Описание
ERROR_WINHTTP_SHUTDOWN
 Поддержка функции WinHTTP завершается или выгружается.
ERROR_WINHTTP_INTERNAL_ERROR
 Произошла внутренняя ошибка.
ERROR_NOT_ENOUGH_MEMORY
 Недостаточно памяти для выполнения запрошенной операции. (Код ошибки Windows)

Комментарии

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

Если для закрываемого дескриптора зарегистрирован обратный вызов состояния и дескриптор был создан со значением контекста, отличном от NULL , выполняется обратный вызов WINHTTP_CALLBACK_STATUS_HANDLE_CLOSING . Это последний обратный вызов, выполненный из дескриптора и указывающий, что дескриптор уничтожается.

Приложение может завершить выполняемый асинхронный запрос, закрыв дескриптор запроса HINTERNET с помощью WinHttpCloseHandle. Помните следующее.

  • После того как приложение вызывает WinHttpCloseHandle для дескриптора WinHTTP, оно не может вызывать другие функции API WinHTTP, используя этот дескриптор из любого потока.
  • Даже после возврата вызова WinHttpCloseHandle приложение должно быть готово к получению обратных вызовов для закрытого дескриптора, так как WinHTTP может асинхронно удалять дескриптор. Если асинхронный запрос не удалось успешно выполнить, обратный вызов получает уведомление WINHTTP_CALLBACK_STATUS_REQUEST_ERROR.
  • Если приложение связывает структуру данных контекста или объект с дескриптором, оно должно поддерживать такую привязку до тех пор, пока функция обратного вызова не получит уведомление WINHTTP_CALLBACK_STATUS_HANDLE_CLOSING . Это последнее уведомление обратного вызова, отправленное WinHTTP перед удалением объекта дескриптора из памяти. Чтобы получить уведомление WINHTTP_CALLBACK_STATUS_HANDLE_CLOSING обратного вызова, приложение должно включить флаг WINHTTP_CALLBACK_FLAG_HANDLES в вызове WinHttpSetStatusCallback .
  • Перед вызовом WinHttpCloseHandle приложение может вызвать WinHttpSetStatusCallback , чтобы указать, что обратные вызовы больше не должны выполняться:

    WinHttpSetStatusCallback( hRequest, NULL, 0, 0 );

    Может показаться, что структура контекстных данных может быть освобождена немедленно, а не ждать уведомления WINHTTP_CALLBACK_STATUS_HANDLE_CLOSING , но это не так: WinHTTP не синхронизирует WinHttpSetStatusCallback с обратными вызовами, исходящими из рабочих потоков. В результате обратный вызов может уже выполняться из другого потока, и приложение может получать уведомление о обратном вызове даже после того, как указатель функции обратного вызова был удален со значением NULL и удалена структура контекстных данных дескриптора. Из-за этого потенциального состояния гонки будьте консервативны в освобождении структуры контекста до получения уведомления WINHTTP_CALLBACK_STATUS_HANDLE_CLOSING .

Приложение никогда не должно вызывать WinHttpCloseHandle для синхронного запроса. Это может создать состояние гонки. Дополнительные сведения см. в разделе Handles HINTERNET в WinHTTP .
Примечание Для Windows XP и Windows 2000 см. раздел Требования к времени выполнения начальной страницы WinHttp.
 

Требования

Требование Значение
Минимальная версия клиента 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.

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

Сведения о службах MICROSOFT Windows HTTP (WinHTTP)

Версии WinHTTP

WinHttpConnect

WinHttpOpen

WinHttpOpenRequest