CredUIPromptForCredentialsA 函式 （wincred.h）
CredUIPromptForCredentials 函式會建立並顯示可設定的對話方塊，以接受來自使用者的認證資訊。
以 Windows Vista 或 Windows Server 2008 為目標的應用程式應呼叫 CredUIPromptForWindowsCredentials，而不是此函式，原因如下：
- CredUIPromptForWindowsCredentials 與目前的 Windows 使用者介面一致。
- CredUIPromptForWindowsCredentials 更容易延伸，允許整合其他驗證機制，例如生物特徵辨識和智慧卡。
- CredUIPromptForWindowsCredentials 符合通用準則規格。
語法
CREDUIAPI DWORD CredUIPromptForCredentialsA(
[in, optional] PCREDUI_INFOA pUiInfo,
[in] PCSTR pszTargetName,
[in] PCtxtHandle pContext,
[in, optional] DWORD dwAuthError,
[in, out] PSTR pszUserName,
[in] ULONG ulUserNameBufferSize,
[in, out] PSTR pszPassword,
[in] ULONG ulPasswordBufferSize,
[in, out] BOOL *save,
[in] DWORD dwFlags
);
參數
[in, optional] pUiInfo
CREDUI_INFO 結構的指標，其中包含自定義對話框外觀的資訊。
[in] pszTargetName
Null 終止字串的指標，其中包含認證的目標名稱，通常是伺服器名稱。 針對分散式文件系統 （DFS） 連線，此字串的格式為 serverName\ShareName。 此參數可用來識別儲存和擷取認證時的目標資訊。
[in] pContext
此參數保留供日後使用。 它必須是 NULL
[in, optional] dwAuthError
指定需要認證對話框的原因。 呼叫端可以傳遞由另一個驗證呼叫傳回的這個 Windows 錯誤參數，以允許對話方塊容納某些錯誤。 例如，如果傳遞密碼過期狀態代碼，對話框可能會提示使用者變更帳戶的密碼。
[in, out] pszUserName
Null 終止字串的指標，其中包含認證的用戶名稱。 如果傳遞非零長度字串，對話框的 UserName 選項會預先填入字串。 在 UserName/Password以外的認證案例中，可以傳入認證封送處理格式。 此字串的建立方式是呼叫 CredMarshalCredential。
此函式會將使用者提供的名稱複製到此緩衝區，複製最多 ulUserNameMaxChars 個字元。 您可以使用 CredUIParseUsername，將此格式轉換成 UserName/Password 格式。 封送處理格式可以直接傳遞至 安全性支援提供者 （SSP）。
如果未指定CREDUI_FLAGS_DO_NOT_PERSIST旗標，則此參數中傳回的值是不應該檢查、列印或保存的表單，而不是將它傳遞給 CredUIParseUsername。 CredUIParseUsername 的後續結果只能傳遞至客戶端驗證函式，例如 WNetAddConnection 或 SSP 函式。
如果未將網域或伺服器指定為此參數的一部分，pszTargetName 參數的值會當做網域來形成 DomainName\UserName 組。 在輸出時，此參數會收到字串，其中包含 DomainName\UserName 組。
[in] ulUserNameBufferSize
可以複製到 pszUserName 的最大字元數， 包括終止的 Null 字元。
[in, out] pszPassword
包含認證密碼之 Null 終止字串的指標。 如果為 pszPassword指定非零長度字串，對話框的密碼選項將會預先填入字元串。
此函式會將使用者提供的密碼複製到此緩衝區，複製最多 ulPasswordMaxChars 個字元。 如果未指定CREDUI_FLAGS_DO_NOT_PERSIST旗標，則此參數中傳回的值是不應該檢查、列印或保存的窗體，而不是將它傳遞至客戶端驗證函式，例如 WNetAddConnection 或 SSP 函式。
當您完成使用密碼時，請呼叫 SecureZeroMemory 函式，從記憶體清除密碼。 如需保護密碼的詳細資訊，請參閱 處理密碼。
[in] ulPasswordBufferSize
可以複製到 pszPassword 的最大字元數， 包括終止的 Null 字元。
[in, out] save
BOOL 的指標，指定 [儲存] 複選框的初始狀態，並在使用者回應對話框后收到 [儲存] 複選框的狀態。 如果未
如果指定CREDUI_FLAGS_PERSIST旗標，則不會顯示 [儲存] 複選框，但會被視為選取。
如果未指定CREDUI_FLAGS_DO_NOT_PERSIST旗標且未指定CREDUI_FLAGS_SHOW_SAVE_CHECK_BOX，則不會顯示 [儲存] 複選框，但會被視為已清除。
需要使用 CredUI 提示使用者輸入認證，但不需要認證管理員所提供的認證管理服務的應用程式，可以使用 pfSave，在使用者關閉對話框之後，接收 [Save] 複選框的狀態。 若要這樣做，呼叫端必須在 dwFlags中指定CREDUI_FLAGS_DO_NOT_PERSIST和CREDUI_FLAGS_SHOW_SAVE_CHECK_BOX。 設定CREDUI_FLAGS_DO_NOT_PERSIST和CREDUI_FLAGS_SHOW_SAVE_CHECK_BOX時，應用程式會負責檢查函式傳回之後的 *pfSave，如果 *pfSaveTRUE，則應用程式必須採取適當的動作，將使用者認證儲存在應用程式的資源內。
[in] dwFlags
DWORD 值，指定此函式的特殊行為。 這個值可以是位OR 下列值的零或多個組合。
| 價值 | 意義 |
|---|---|
|
指定即使可以從認證管理員中的現有認證傳回認證，也會顯示使用者介面。 只有在同時指定CREDUI_FLAGS_GENERIC_CREDENTIALS時，才允許此旗標。 |
|
在下拉式方塊中填入用戶名稱的提示。 |
|
請勿儲存認證或顯示複選框。 您可以使用這個旗標傳遞CREDUI_FLAGS_SHOW_SAVE_CHECK_BOX以顯示 [儲存] 複選框，而且結果會傳回 pfSave 輸出參數。 |
|
僅以使用者名稱/密碼填入下拉式方塊。 不要在下拉式方塊中顯示憑證或智慧卡。 |
|
指定呼叫者會在檢查以判斷傳回的認證是否實際有效之後，呼叫 CredUIConfirmCredentials。 此機制可確保無效的認證不會儲存至認證管理員。 除非指定CREDUI_FLAGS_DO_NOT_PERSIST，否則在所有情況下都指定此旗標。 |
|
請考慮使用者輸入的認證為一般認證。 |
|
顯示「登入失敗」氣球提示，通知用戶認證不足。 |
|
不允許使用者變更提供的用戶名稱。 |
|
僅以密碼填入下拉式方塊。 不允許輸入用戶名稱。 |
|
請勿顯示 [儲存] 複選框 |
|
僅使用本機系統管理員填入下拉式方塊。Windows XP Home Edition：此旗標會篩選掉已知的系統管理員帳戶。 |
|
僅以憑證和智慧卡填入下拉式方塊。 不允許輸入用戶名稱。 |
|
僅以憑證或智慧卡填入下拉式方塊。 不允許輸入用戶名稱。 |
|
如果驗證失敗，此旗標只有在尋找相符的認證以預先填入對話框時才有意義。 指定此旗標時，將不會比對通配符認證。 寫入認證時沒有任何作用。 CredUI 不會建立包含通配符的認證。 用戶明確建立或以程序設計方式建立任何找到的專案，就像建立 RAS 連線時一樣。 |
|
如果選取複選框，請顯示 |
|
認證是「runas」認證。 TargetName 參數會指定正在執行的命令或程式名稱。 它僅供提示之用。 |
|
檢查用戶名稱是否有效。 |
傳回值
傳回值是 DWORD，可以是下列其中一個值。
| 價值 | 描述 |
|---|---|
|
使用者選擇 [取消] |
|
這個狀態會針對任何無效的旗標組態傳回。 |
|
|
|
無法使用認證管理員。 通常，呼叫 CredUIPromptForCredentials 並傳入 CREDUI_FLAGS_DO_NOT_PERSIST 旗標，來處理此錯誤。 |
|
使用者選擇 [確定] 。 pszUserName、pszPassword，以及 pfSave 參數會傳回先前記載的值。 |
言論
CredUIPromptForCredentials 函式會建立並顯示應用程式強制回應對話方塊。 顯示對話框之後，直到使用者或應用程式關閉對話框為止，應用程式內沒有其他視窗可以變成作用中狀態。
旗標CREDUI_FLAGS_REQUIRE_SMARTCARD、CREDUI_FLAGS_REQUIRE_CERTIFICATE和CREDUI_FLAGS_EXCLUDE_CERTIFICATE互斥。
如果指定了CREDUI_FLAGS_DO_NOT_PERSIST，則必須指定 pszTargetName
旗標CREDUI_FLAG_USERNAME_TARGET_CREDENTIALS和CREDUI_FLAGS_GENERIC_CREDENTIALS互斥。 如果兩者都未指定，認證就是網域認證。
X509 憑證必須具有 增強密鑰使用 （EKU） 值 szOID_KP_SMARTCARD_LOGON （1.3.6.1.4.1.311.20.2.2）才能顯示。
Windows XP：此 EKU 值不需要顯示 X509 憑證。
如果未指定CREDUI_FLAGS_GENERIC_CREDENTIALS或指定CREDUI_FLAGS_COMPLETE_USERNAME，則會檢查具類型的名稱
如果指定了CREDUI_FLAGS_GENERIC_CREDENTIALS，而且也指定了CREDUI_FLAGS_VALIDATE_USERNAME，則會檢查具類型的名稱。 如果具類型的名稱無效，系統會提示使用者輸入有效的名稱。
如果指定了CREDUI_FLAGS_GENERIC_CREDENTIALS，而且未指定CREDUI_FLAGS_COMPLETE_USERNAME或CREDUI_FLAGS_VALIDATE_USERNAME，則不會以任何方式檢查具類型的名稱。
如果未設定CREDUI_FLAGS_PERSIST或CREDUI_FLAGS_DO_NOT_PERSIST，則會顯示 [儲存] 複選框
呼叫模式
- 呼叫端會嘗試存取目標資源、呼叫 credui（傳遞目標資源的描述和失敗狀態）、呼叫 CredUIParseUserName、再次存取目標資源，然後呼叫 CredUIConfirmCredentials。
- 呼叫端可以透過傳遞CREDUI_FLAGS_DO_NOT_PERSIST來提示認證，而不需要存取任何資源。
- 針對泛型認證，沒有驗證套件。 因此，應用程式必須存取認證來執行驗證。 提示輸入認證，而不是在第一次驗證之前傳遞CREDUI_FLAGS_ALWAYS_SHOW_UI。 只有在認證管理員中沒有認證時，才會顯示使用者介面。 在應用程式內的所有後續訊息上，將會傳遞CREDUI_FLAGS_ALWAYS_SHOW_UI，因為認證管理員中的認證顯然對該資源無效。
目標資訊是所要存取之資源位置的相關信息。 如需資源所有潛在目標名稱的清單，請呼叫 CredGetTargetInfo。 CredGetTargetInfo 傳回交涉、NTLM 或 Kerberos 驗證套件在其中一個封裝用來向具名目標進行驗證時所快取的資訊。 CredGetTargetInfo 會針對目標傳回下列部分或所有名稱：
- 計算機的 NetBIOS 伺服器名稱
- 計算機的 DNS 伺服器名稱
- 計算機所屬網域的 NetBIOS 功能變數名稱
- 計算機所屬網域的 DNS 功能變數名稱
- 計算機所屬樹狀結構的 DNS 樹狀目錄名稱
- 收集資訊的套件名稱
認證會根據目標名稱儲存在認證管理員中。 每個目標名稱通常會盡可能儲存，而不會與認證管理員中已儲存的認證發生衝突。 由於認證是以目標名稱儲存，因此特定使用者只能在認證管理員中儲存每個目標一個認證。
注意
wincred.h 標頭會根據 UNICODE 預處理器常數的定義，將 CredUIPromptForCredentials 定義為自動選取此函式的 ANSI 或 Unicode 版本。 混合使用編碼中性別名與非編碼中性的程序代碼，可能會導致編譯或運行時間錯誤不符。 如需詳細資訊，請參閱函式原型的
要求
| 要求 | 價值 |
|---|---|
| 最低支援的用戶端 | Windows XP [僅限傳統型應用程式] |
| 支援的最低伺服器 | Windows Server 2003 [僅限傳統型應用程式] |
| 目標平臺 | 窗戶 |
| 標頭 | wincred.h |
| 連結庫 | Credui.lib |
| DLL | Credui.dll |