CredUIPromptForCredentialsW 函式 (wincred.h)
CredUIPromptForCredentials 函式會建立並顯示可設定的對話框，以接受使用者的認證資訊。
以 Windows Vista 或 Windows Server 2008 為目標的應用程式應該呼叫 CredUIPromptForWindowsCredentials ，而不是此函式，原因如下：
- CredUIPromptForWindowsCredentials 與目前的 Windows 使用者介面一致。
- CredUIPromptForWindowsCredentials 更容易延伸，允許整合其他驗證機制，例如生物特徵辨識和智慧卡。
- CredUIPromptForWindowsCredentials 符合 Common Criteria 規格。
語法
CREDUIAPI DWORD CredUIPromptForCredentialsW(
[in, optional] PCREDUI_INFOW pUiInfo,
[in] PCWSTR pszTargetName,
[in] PCtxtHandle pContext,
[in, optional] DWORD dwAuthError,
[in, out] PWSTR pszUserName,
[in] ULONG ulUserNameBufferSize,
[in, out] PWSTR 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/密碼格式。 封送處理的格式可以直接傳遞至 安全性支援提供者 ， (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 的指標，指定 [儲存] 複選框的初始狀態，並在使用者響應對話框之後收到 [儲存] 複選框的狀態。 如果此值不是 NULL，而且 CredUIPromptForCredentials 會傳回NO_ERROR，則當使用者在對話框中選擇 [確定] 時，pfSave 會傳回 [儲存] 複選框的狀態。
如果指定了CREDUI_FLAGS_PERSIST旗標，則不會顯示 [ 儲存 ] 複選框，但會被視為已選取。
如果指定CREDUI_FLAGS_DO_NOT_PERSIST旗標，且未指定CREDUI_FLAGS_SHOW_SAVE_CHECK_BOX，則不會顯示 [ 儲存 ] 複選框，但會視為已清除。
需要使用 CredUI 提示使用者輸入認證，但不需要認證管理員所提供的認證管理服務的應用程式，可以使用 pfSave 在使用者關閉對話框之後接收 [ 儲存 ] 複選框的狀態。 若要這樣做，呼叫端必須在 dwFlags 中指定CREDUI_FLAGS_DO_NOT_PERSIST和CREDUI_FLAGS_SHOW_SAVE_CHECK_BOX。 設定CREDUI_FLAGS_DO_NOT_PERSIST和CREDUI_FLAGS_SHOW_SAVE_CHECK_BOX時，應用程式會負責檢查函式傳回後的 *pfSave ，如果 *pfSave 為 TRUE，則應用程式必須採取適當的動作，在應用程式的資源內儲存用戶認證。
[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 連線時所發生。 |
|
如果選取此複選框，請在 pfSave 輸出參數中顯示 [儲存] 複選框並傳回 TRUE，否則傳回 FALSE。 複選框預設會使用 pfSave 中的值。 |
|
認證是“runas” 認證。 TargetName 參數會指定正在執行的命令或程序名稱。 它僅用於提示用途。 |
|
檢查用戶名稱是否有效。 |
傳回值
傳回值是 DWORD ，可以是下列其中一個值。
| 值 | Description |
|---|---|
|
用戶選擇 [取消]。 pszUserName 和 pszPassword 參數尚未變更。 |
|
此狀態會針對任何無效的旗標組態傳回。 |
|
pszTargetName 為 NULL、空字串或超過 CREDUI_MAX_DOMAIN_LENGTH，或 pUiInfo 不是 NULL，而且指向的CredUI_INFO結構不符合下列其中一個需求：
|
|
無法使用認證管理員。 一般而言，呼叫 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 或 uiInfo-pszMessageText> 和 uiInfo-pszCaption>。
旗標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) 顯示。
Windowsxp： 此 EKU 值不需要顯示 X509 憑證。
如果未指定CREDUI_FLAGS_GENERIC_CREDENTIALS或指定CREDUI_FLAGS_COMPLETE_USERNAME，則會 檢查具類型的名稱。 語法檢查會套用與 CredUIParseUserName 所套用的相同規則。 如果具型別名稱無效，系統會提示使用者輸入有效的名稱。 如果遺漏具型別名稱的網域部分，則會根據目標名稱提供一個。
如果指定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 會在其中一個套件用來向具名目標進行驗證時，傳回 Negotiate、NTLM 或 Kerberos 驗證套件快取的資訊。 CredGetTargetInfo 會傳回目標的一些或所有下列名稱：
- 計算機的 NetBIOS 伺服器名稱
- 計算機的 DNS 伺服器名稱
- 計算機所屬網域的 NetBIOS 功能變數名稱
- 計算機所屬網域的 DNS 功能變數名稱
- 計算機所屬樹狀結構的 DNS 樹狀結構名稱
- 收集資訊的套件名稱
認證會根據目標名稱儲存在認證管理員中。 每個目標名稱通常會儲存在一般情況下，而不會與已經儲存在認證管理員中的認證發生衝突。 因為認證是以目標名稱儲存，所以特定使用者只能有每個儲存在認證管理員中的認證。
規格需求
| 需求 | 值 |
|---|---|
| 最低支援的用戶端 | Windows XP [僅限傳統型應用程式] |
| 最低支援的伺服器 | Windows Server 2003 [僅限傳統型應用程式] |
| 目標平台 | Windows |
| 標頭 | wincred.h |
| 程式庫 | Credui.lib |
| Dll | Credui.dll |