Share via

Дескриптора 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 см. в разделе Сведения о 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.

Веб-сокеты в иерархии дескрипторов

Дескриптор веб-сокета наследует от дескрипторов подключения и сеанса и занимает в иерархии дескрипторов аналогичное положение дескриптора запроса. Чтобы создать дескриптор веб-сокета, должен существовать дескриптор запроса; но после создания дескриптора веб-сокета запрос может быть закрыт, и дескриптор веб-сокета продолжит функционировать.