Функция WinHttpCloseHandle (winhttp.h)
Функция WinHttpCloseHandle закрывает один дескриптор HINTERNET (см. раздел Дескрипторы HINTERNET в WinHTTP).
Синтаксис
WINHTTPAPI BOOL WinHttpCloseHandle(
[in] HINTERNET hInternet
);
Параметры
[in] hInternet
Допустимый дескриптор HINTERNET (см . раздел Маркеры HINTERNET в WinHTTP), который необходимо закрыть.
Возвращаемое значение
Значение TRUE , если дескриптор успешно закрыт, в противном случае — ЗНАЧЕНИЕ FALSE. Дополнительные сведения об ошибке можно получить, вызвав GetLastError. Среди возвращаемых кодов ошибок:
| Коды ошибок | Описание |
|---|---|
|
Поддержка функции WinHTTP завершается или выгружается. |
|
Произошла внутренняя ошибка. |
|
Недостаточно памяти для выполнения запрошенной операции. (Код ошибки 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 .
Требования
| Требование | Значение |
|---|---|
| Минимальная версия клиента | 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. |