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

WinHttpOpenRequest 返回的有效 HINTERNET 句柄。

[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	使用 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 (即在 WinHttpOpen) 中设置了WINHTTP_FLAG_ASYNC时，此函数也会同步运行。返回值指示成功或失败。要获得更多的错误信息，请调用 GetLastError。

WinHttpSetCredentials 设置的凭据仅用于单个请求;WinHTTP 不会缓存这些凭据以用于后续请求。因此，必须编写应用程序，以便它们能够响应多个挑战。如果重新使用经过身份验证的连接，则无法对后续请求提出质询，但代码应能够随时响应质询。

有关说明 WinHttpSetCredentials 用法的示例代码，请参阅 WinHTTP 中的身份验证。

注意使用 Passport 身份验证和响应 407 状态代码时，WinHTTP 应用程序必须使用 WinHttpSetOption 来提供代理凭据，而不是 WinHttpSetCredentials。仅当使用 Passport 身份验证时，才如此;在所有其他情况下，请使用 WinHttpSetCredentials，因为 WinHttpSetOption 不太安全。

注意对于 Windows XP 和 Windows 2000，请参阅 WinHttp 起始页的运行时要求部分。

要求


最低受支持的客户端	Windows XP、Windows 2000 Professional 和 SP3 [仅限桌面应用]
最低受支持的服务器	Windows Server 2003、Windows 2000 Server SP3 [仅限桌面应用]
目标平台	Windows
标头	winhttp.h
Library	Winhttp.lib
DLL	Winhttp.dll
可再发行组件	Windows XP 和 Windows 2000 上的 WinHTTP 5.0 和 Internet Explorer 5.01 或更高版本。