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

Статья
08/27/2023

Функция WinHttpSetCredentials передает на сервер необходимые учетные данные авторизации.

Синтаксис

WINHTTPAPI BOOL WinHttpSetCredentials(
  [in] HINTERNET hRequest,
  [in] DWORD     AuthTargets,
  [in] DWORD     AuthScheme,
  [in] LPCWSTR   pwszUserName,
  [in] LPCWSTR   pwszPassword,
  [in] LPVOID    pAuthParams
);

Параметры

[in] hRequest

Допустимый дескриптор HINTERNET, возвращаемый WinHttpOpenRequest.

[in] AuthTargets

Целое число без знака, указывающее флаг, содержащий целевой объект проверки подлинности. Может быть одним из значений в следующей таблице.

Значение	Значение
WINHTTP_AUTH_TARGET_SERVER	Учетные данные передаются на сервер.
WINHTTP_AUTH_TARGET_PROXY	Учетные данные передаются прокси-серверу.

[in] AuthScheme

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

Значение	Значение
WINHTTP_AUTH_SCHEME_BASIC	Используйте обычную проверку подлинности.
WINHTTP_AUTH_SCHEME_NTLM	Используйте проверку подлинности NTLM.
WINHTTP_AUTH_SCHEME_PASSPORT	Используйте проверку подлинности по паспорту.
WINHTTP_AUTH_SCHEME_DIGEST	Используйте дайджест-проверку подлинности.
WINHTTP_AUTH_SCHEME_NEGOTIATE	Выбор между проверкой подлинности NTLM и Kerberos.

[in] pwszUserName

Указатель на строку, содержащую допустимое имя пользователя.

[in] pwszPassword

Указатель на строку, содержащую допустимый пароль. Пароль может быть пустым.

[in] pAuthParams

Этот параметр зарезервирован и должен иметь значение NULL.

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

Возвращает значение TRUE в случае успешного выполнения или FALSE в противном случае. Для получения дополнительных сведений об ошибке вызовите Метод GetLastError. В следующей таблице указаны возвращенные коды ошибок.

Код ошибки	Описание
ERROR_WINHTTP_INCORRECT_HANDLE_STATE	Не удается выполнить запрошенную операцию, так как предоставленный дескриптор находится в неправильном состоянии.
ERROR_WINHTTP_INCORRECT_HANDLE_TYPE	Для этой операции указан неправильный тип дескриптора.
ERROR_WINHTTP_INTERNAL_ERROR	Произошла внутренняя ошибка.
ERROR_NOT_ENOUGH_MEMORY	Недостаточно памяти для завершения запрошенной операции (код ошибки Windows).

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

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

Пример кода, иллюстрирующий использование WinHttpSetCredentials, см. в разделе Проверка подлинности в WinHTTP.

Примечание При использовании проверки подлинности Passport и ответа на код состояния 407 приложение WinHTTP должно использовать WinHttpSetOption для предоставления учетных данных прокси-сервера, а не WinHttpSetCredentials. Это верно только при использовании проверки подлинности Passport; во всех остальных случаях используйте WinHttpSetCredentials, так как WinHttpSetOption менее защищен.

Примечание Для 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.