Перенос приложений WinINet в WinHTTP

Службы Microsoft Windows HTTP (WinHTTP) предназначены для серверных приложений среднего уровня и серверных приложений, которым требуется доступ к стеку клиентов HTTP. Microsoft Windows Internet (WinINet) предоставляет стек клиента HTTP для клиентских приложений, а также доступ к протоколам FTP, SOCKSv4 и Gopher. Этот обзор поможет определить, будет ли полезным перенос приложений WinINet в WinHTTP. Здесь также описываются конкретные требования к преобразованию.

• Что следует учитывать перед переносом приложения WinINet
• Эквиваленты WinHTTP функциям WinINet
• Различная обработка асинхронных запросов
• Различия в уведомлениях обратного вызова WinHTTP
• Различия в проверке подлинности
• Различия в безопасных транзакциях HTTP

Что следует учитывать перед переносом приложения WinINet

Рассмотрите возможность переноса приложения WinINet в WinHTTP, если ваше приложение будет пользоваться следующими преимуществами:

• Стек клиента HTTP, безопасный на сервере.
• Минимальное использование стека.
• Масштабируемость серверного приложения.
• Меньше зависимостей от API, связанных с платформой.
• Поддержка олицетворения потока.
• Удобный для службы стек HTTP.
• Доступ к объекту WinHttpRequest с доступом к скриптам.

Не рекомендуется переносить приложение WinINet в WinHTTP, если оно должно поддерживать одно или несколько из следующих компонентов:

• Протокол FTP или Gopher из стека HTTP.
• Поддержка протокола SOCKSv4 для взаимодействия с прокси-серверами SOCKS.
• Автоматические коммутируемые службы.

Если вы решили перенести приложение в WinHTTP, в следующих разделах описан процесс преобразования.

Для примера приложения для WinINet и WinHTTP сравните пример AsyncDemo для WinINet с примером AsyncDemo для WinHTTP.

Эквиваленты WinHTTP функциям WinINet

В следующей таблице перечислены функции WinINet, связанные со стеком клиентов HTTP, а также эквиваленты WinHTTP.

Если приложению требуются функции WinINet, которых нет в списке, не переносите приложение в WinHTTP.

Различная обработка асинхронных запросов

Имейте в виду, что в WinINet и WinHTTP некоторые функции могут выполнять асинхронные запросы как синхронно, так и асинхронно. Приложение должно обрабатывать обе ситуации. Существуют значительные различия в том, как WinINet и WinHTTP обрабатывают эти потенциально асинхронные функции.

Wininet

• Синхронное завершение. Если потенциально асинхронный вызов функции WinINet завершается синхронно, параметры OUT функции возвращают результаты операции. При возникновении ошибки получите код ошибки, вызвав Метод GetLastError после вызова функции WinINet.

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

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

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

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

WinHTTP

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

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

Хотя большинство ошибок также можно обрабатывать полностью в функции обратного вызова, приложения WinHTTP по-прежнему должны быть подготовлены к возврату функции FALSE из-за ERROR_INVALID_PARAMETER или другой аналогичной ошибки, полученной путем вызова GetLastError.

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

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

Различия в уведомлениях обратного вызова WinHTTP

Функция обратного вызова состояния получает обновления о состоянии операций с помощью флагов уведомлений. В WinHTTP уведомления выбираются с помощью параметра dwNotificationFlags функции WinHttpSetStatusCallback . Используйте флаг WINHTTP_CALLBACK_FLAG_ALL_NOTIFICATIONS , чтобы получать уведомления обо всех обновлениях состояния.

Уведомления, указывающие, что определенная операция завершена, называются уведомлениями о завершении или просто завершениями. В WinINet каждый раз, когда функция обратного вызова получает завершение, параметр lpvStatusInformation содержит INTERNET_ASYNC_RESULT структуру. В WinHTTP эта структура доступна не для всех завершений. Важно просмотреть справочную страницу для WINHTTP_STATUS_CALLBACK, на которой содержатся сведения об уведомлениях и типе данных, которые можно ожидать для каждого из них.

В WinHTTP одно завершение WINHTTP_CALLBACK_STATUS_REQUEST_ERROR указывает на сбой операции. Все остальные завершения указывают на успешное выполнение операции.

Как WinINet, так и WinHTTP используют определяемое пользователем контекстное значение для передачи сведений из потока main функции обратного вызова состояния, которая может выполняться в рабочем потоке. В WinINet значение контекста, используемое функцией обратного вызова состояния, задается путем вызова одной из нескольких функций. В WinHTTP значение контекста задается только с помощью WinHttpSendRequest или WinHttpSetOption. Из-за этого в WinHTTP может появиться уведомление до установки значения контекста. Если функция обратного вызова получает уведомление до установки значения контекста, приложение должно быть подготовлено к получению null в параметре dwContext функции обратного вызова.

Различия в проверке подлинности

В WinINet учетные данные пользователя задаются путем вызова функции InternetSetOption с помощью кода, аналогичного приведенному в следующем примере кода.

// Use the WinINet InternetSetOption function to set the 
// user credentials to the user name contained in strUsername 
// and the password to the contents of strPassword.
       
InternetSetOption( hRequest, INTERNET_OPTION_PROXY_USERNAME, 
                   strUsername, strlen(strUsername) + 1 );

InternetSetOption( hRequest, INTERNET_OPTION_PROXY_PASSWORD, 
                   strPassword, strlen(strPassword) + 1 );

Для обеспечения совместимости учетные данные пользователя также можно задать в WinHTTP с помощью функции WinHttpSetOption , но это не рекомендуется, так как это может представлять уязвимость системы безопасности.

Вместо этого, когда приложение получает код состояния 401 в WinHTTP, рекомендуется сначала определить схему проверки подлинности с помощью WinHttpQueryAuthSchemes , а затем задать учетные данные с помощью WinHttpSetCredentials. В следующем примере кода показано, как это сделать.

DWORD dwSupportedSchemes;
DWORD dwPrefered;
DWORD dwTarget;

// Obtain the supported and first schemes.
WinHttpQueryAuthSchemes( hRequest, &dwSupportedSchemes, &dwPrefered, &dwTarget );

// Set the credentials before resending the request.
WinHttpSetCredentials( hRequest, dwTarget, dwPrefered, strUsername, strPassword, NULL );

Так как в WinHTTP нет эквивалента InternetErrorDlg , приложения, получающие учетные данные через пользовательский интерфейс, должны предоставлять собственный интерфейс.

В отличие от WinINet, WinHTTP не кэширует пароли. Для каждого запроса должны быть предоставлены допустимые учетные данные пользователя.

WinHTTP не поддерживает схему распределенной проверки подлинности паролей (DPA), поддерживаемую WinINet. Однако WinHTTP поддерживает Microsoft Passport 1.4. Дополнительные сведения об использовании проверки подлинности Passport в WinHTTP см. в статье Проверка подлинности passport в WinHTTP.

WinHTTP не использует параметры интернет-Обозреватель для определения политики автоматического входа. Вместо этого политика автоматического входа задается с помощью WinHttpSetOption. Дополнительные сведения о проверке подлинности в WinHTTP, включая политику автоматического входа, см. в разделе Проверка подлинности в WinHTTP.

Различия в безопасных транзакциях HTTP

В WinINet инициируйте безопасный сеанс с помощью HttpOpenRequest или InternetConnect, но в WinHTTP необходимо вызвать WinHttpOpenRequest с помощью флага WINHTTP_FLAG_SECURE .

В безопасной транзакции HTTP сертификаты сервера можно использовать для проверки подлинности сервера для клиента. В WinINet, если сертификат сервера содержит ошибки, HttpSendRequest завершается ошибкой и предоставляет сведения об ошибках сертификата.

В WinHttp ошибки сертификата сервера обрабатываются в соответствии с версией следующим образом:

• Начиная с WinHttp 5.1, если сертификат сервера завершается сбоем или содержит ошибки, вызов WinHttpSendRequest сообщает о WINHTTP_CALLBACK_STATUS_SECURE_FAILURE в функции обратного вызова. Если ошибка, созданная WinHttpSendRequest , игнорируется, последующие вызовы WinHttpReceiveResponse завершаются ошибкой ERROR_WINHTTP_OPERATION_CANCELLED.
• В WinHTTP 5.0 ошибки в сертификатах сервера по умолчанию не приводят к сбою запроса. Вместо этого об ошибках сообщается в функции обратного вызова с уведомлением WINHTTP_CALLBACK_STATUS_SECURE_FAILURE .

На некоторых более ранних платформах WinINet поддерживал протоколы Технологии частной коммуникации (PCT) и (или) Fortezza, хотя и не в Windows XP.

WinHTTP не поддерживает протоколы PCT и Fortezza на любой платформе и использует протокол SSL 2.0, SSL 3.0 или TLS 1.0.