winHttpSetCredentials 函式 (winHTTP.h)

發行項
03/15/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	認證會傳遞至 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 來提供 Proxy 認證，而不是 WinHttpSetCredentials。只有在使用 Passport 驗證時，才會發生這種情況;在其他所有情況下，請使用 WinHttpSetCredentials，因為 WinHttpSetOption 較不安全。

注意針對 Windows XP 和 Windows 2000，請參閱 WinHttp 起始頁的執行時間需求一節。

規格需求


最低支援的用戶端	Windows XP、Windows 2000 Professional 與 SP3 [僅限傳統型應用程式]
最低支援的伺服器	Windows Server 2003、具有 SP3 的 Windows 2000 Server [僅限傳統型應用程式]
目標平台	Windows
標頭	winHTTP.h
程式庫	WinHTTP.lib
Dll	Winhttp.dll
可轉散發套件	Windows XP 和 Windows 2000 上的 WinHTTP 5.0 和 Internet Explorer 5.01 或更新版本。