Дескриптор HINTERNET в WinHTTP
Службы HTTP Microsoft Windows (WinHTTP) используют дескриптор для отслеживания параметров и сведений, необходимых при использовании протокола HTTP. Каждый дескриптор поддерживает сведения, относящиеся к сеансу HTTP, подключению к HTTP-серверу или конкретному ресурсу. В этом разделе описываются различные типы дескрипторов, соглашения об именовании этих дескрипторов и их иерархическая структура.
Сведения об дескрипторах HINTERNET
Маркеры, созданные и используемые WinHTTP, называются дескрипторами HINTERNET. Функции WinHTTP возвращают маркеры HINTERNET, которые не взаимозаменяемы с другими дескрипторами, поэтому их нельзя использовать с такими функциями, как ReadFile или CloseHandle. Аналогичным образом другие дескрипторы нельзя использовать с функциями WinHTTP. Например, дескриптор, возвращаемый CreateFile, нельзя передать в WinHttpReadData. Эти маркеры HINTERNET невозможно закрыть, пока вызов API с помощью дескриптора выполняется. Чтобы избежать состояния гонки, приложения должны защитить дескриптор и предотвратить его закрытие до тех пор, пока вызов API выполняется.
Функции Microsoft Win32 Internet (WinInet) также используют дескриптор HINTERNET. Однако дескриптор, используемый в функциях WinInet, не может быть заменен дескриптором, используемым в функциях WinHTTP. Дополнительные сведения о WinInet см. в разделе About WinINet.
Функция winHttpCloseHandle закрывает дескриптор WinHTTP HINTERNET.
Дескриптор именования
В документации по WinHTTP описания функций в интерфейсе программирования приложения (API) и примере кода показывают создание и использование различных типов дескрипторов HINTERNET. Чтобы отслеживать доступные различные типы дескрипторов, имена этих дескрипторов согласованы. В следующей таблице показаны идентификаторы, используемые соглашением в документации.
| Тип дескриптора | Создание дескриптора функции | Идентификатор |
|---|---|---|
| Универсальный дескриптор | WinHttpOpen, WinHttpConnectили WinHttpOpenRequest | hInternet |
| Дескриптор сеанса | WinHttpOpen | hSession |
| Дескриптор подключения | WinHttpConnect | hConnect |
| Дескриптор запроса | WinHttpOpenRequest | hRequest |
| Дескриптор веб-сокета | WinHttpWebSocketCompleteUpgrade | hWebSocket |
Обработка иерархии
Дескриптор HINTERNET поддерживается в иерархии. Дескриптор, возвращаемый WinHttpOpen, является дескриптором сеанса HINTERNET. Вызов WinHttpOpen инициализирует функции WinHTTP и начинает контекст сеанса, который поддерживает сведения о пользователях и параметрах в течение всего срока действия дескриптора сеанса. WinHttpConnect указывает целевой HTTP-сервер или HTTPS и создает дескриптор подключения HINTERNET. По умолчанию дескриптор подключения наследует параметры дескриптора сеанса. Каждому ресурсу, указанному с вызовом WinHttpOpenRequest, назначается дескриптор запроса HINTERNET.
На следующей схеме показана иерархия дескрипторов HINTERNET. Каждое поле на схеме представляет функцию WinHTTP, которая возвращает дескриптор HINTERNET.
функции 
После закрытия дескриптора приложение должно быть готово к получению уведомлений обратного вызова на дескриптор до тех пор, пока не будет возвращено окончательное значение WINHTTP_CALLBACK_STATUS_HANDLE_CLOSED, чтобы указать, что дескриптор полностью закрыт (или до тех пор, пока приложение не выполняет собственную эквивалентную синхронизацию, например отслеживание и ожидание всех обратных вызовов от ожидающих асинхронных операций и обеспечение того, чтобы дальнейшие операции не пытались использовать этот дескриптор).
Дескриптор сеанса называется родительским элементом любого дескриптора соединения, который он использовал для создания; Аналогичным образом, дескриптор соединения и его родительский дескриптор сеанса называются родителями любого дескриптора запроса, который используется для создания дескриптора соединения.
При закрытии родительского дескриптора все дочерние элементы, которые имеются косвенно, даже если они не закрыты, а последующие запросы, использующие их, завершаются ошибкой ERROR_INVALID_HANDLE. Ожидающие асинхронные запросы нельзя полагаться на правильное выполнение.
На следующей схеме показаны функции, использующие дескриптор HINTERNET, созданный WinHttpOpenRequest. Затененные прямоугольники представляют функции WinHTTP, которые создают дескрипторы, а в простых полях отображаются функции, использующие эти маркеры HINTERNET. Схема также организована для отображения порядка, в котором функции WinHTTP обычно вызываются.
функции
Объяснение иерархии дескрипторов
Сначала создается дескриптор сеанса с WinHttpOpen. WinHttpConnect требует дескриптора сеанса в качестве первого параметра и возвращает дескриптор подключения для указанного сервера. Дескриптор запроса создается WinHttpOpenRequest, который использует дескриптор подключения, созданный WinHttpConnect. Если приложение выбирает добавление дополнительных заголовков в запрос или требуется для установки учетных данных для проверки подлинности, WinHttpAddRequestHeaders и WinHttpSetCredentials можно вызвать с помощью этого дескриптора запроса. Запрос отправляется WinHttpSendRequest, который использует дескриптор запроса. После отправки запроса дополнительные данные можно отправить на сервер с помощью WinHttpWriteData, или приложение может перейти непосредственно к WinHttpReceiveResponse, чтобы указать, что больше информации не отправляется на сервер. На этом этапе в зависимости от цели приложения дескриптор запроса можно использовать для вызова WinHttpQueryHeaders, WinHttpQueryAuthSchemesили получения ресурса с WinHttpQueryDataAvailable и WinHttpReadData.
Веб-сокеты в иерархии дескрипторов
Дескриптор веб-сокета наследует от дескрипторов подключения и сеансов и занимает аналогичную позицию в иерархии дескрипторов, как дескриптор запроса. Чтобы создать дескриптор веб-сокета, должен существовать дескриптор запроса; но после создания дескриптора веб-сокета запрос может быть закрыт, а дескриптор веб-сокета будет продолжать функционировать.