CredUIPromptForCredentialsA 函式 (wincred.h)

  • 發行項

CredUIPromptForCredentials 函式會建立並顯示可設定的對話框，以接受使用者的認證資訊。

以 Windows Vista 或 Windows Server 2008 為目標的應用程式應該呼叫 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/密碼格式。 封送處理的格式可以直接傳遞至 安全性支援提供者 ， (SSP) 。

如果未指定CREDUI_FLAGS_DO_NOT_PERSIST旗標，則此參數中傳回的值是不應該檢查、列印或保存的格式，而不是將它傳遞至 CredUIParseUsername。 CredUIParseUsername 的後續結果只能傳遞至用戶端驗證函式，例如 WNetAddConnection 或 SSP 函式。

如果未將網域或伺服器指定為此參數的一部分， pszTargetName 參數的值會當做網域來形成 DomainName\UserName 配對。 在輸出時，此參數會接收包含 該 DomainName\UserName 配對的字串。

[in] ulUserNameBufferSize

可以複製到 pszUserName 的最大字元數，包括終止的 Null 字元。

注意 CREDUI_MAX_USERNAME_LENGTH不包含終止 Null 字元。
 

[in, out] pszPassword

包含認證密碼之 Null 終止字串的指標。 如果為 pszPassword 指定非零長度字串，對話框的密碼選項將會預先填入字串。

此函式會將使用者提供的密碼複製到此緩衝區，複製最多 ulPasswordMaxChars 字元。 如果未指定CREDUI_FLAGS_DO_NOT_PERSIST旗標，則此參數中傳回的值是不應該檢查、列印或保存的窗體，而不是將它傳遞至客戶端驗證函式，例如 WNetAddConnection 或 SSP 函式。

當您完成使用密碼時，請呼叫 SecureZeroMemory 函式 ，從記憶體清除密碼。 如需保護密碼的詳細資訊，請參閱 處理密碼。

[in] ulPasswordBufferSize

可以複製到 pszPassword 的最大字元數，包括終止的 Null 字元。

注意 CREDUI_MAX_PASSWORD_LENGTH不包含終止 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_ALWAYS_SHOW_UI
0x00080
 指定即使認證可以從認證管理員中的現有認證傳回，也會顯示使用者介面。 只有在同時指定CREDUI_FLAGS_GENERIC_CREDENTIALS時，才允許此旗標。
CREDUI_FLAGS_COMPLETE_USERNAME
0x00800
 在下拉式方塊中填入用戶名稱的提示。
CREDUI_FLAGS_DO_NOT_PERSIST
0x00002
 請勿儲存認證或顯示複選框。 您可以使用此旗標傳遞CREDUI_FLAGS_SHOW_SAVE_CHECK_BOX，只顯示 [ 儲存 ] 複選框，而且結果會在 pfSave 輸出參數中傳回。
CREDUI_FLAGS_EXCLUDE_CERTIFICATES
0x00008
 僅以使用者名稱/密碼填入下拉式方塊。 不要在下拉式方塊中顯示憑證或智慧卡。
CREDUI_FLAGS_EXPECT_CONFIRMATION
0x20000
 指定呼叫端會在檢查之後呼叫 CredUIConfirmCredentials ，以判斷傳回的認證是否實際有效。 此機制可確保無效的認證不會儲存至認證管理員。 除非指定CREDUI_FLAGS_DO_NOT_PERSIST，否則在所有情況下都指定此旗標。
CREDUI_FLAGS_GENERIC_CREDENTIALS
0x40000
 請考慮使用者輸入的認證為一般認證。
CREDUI_FLAGS_INCORRECT_PASSWORD
0x00001
 藉由顯示「登入失敗」批註提示，通知用戶認證不足。
CREDUI_FLAGS_KEEP_USERNAME
0x100000
 不允許使用者變更提供的用戶名稱。
CREDUI_FLAGS_PASSWORD_ONLY_OK
0x00200
 僅以密碼填入下拉式方塊。 不允許輸入用戶名稱。
CREDUI_FLAGS_PERSIST
0x01000
 請勿顯示 [ 儲存] 複選框，但認證會儲存為已顯示並選取方塊。
CREDUI_FLAGS_REQUEST_ADMINISTRATOR
0x00004
 僅以本機系統管理員填入下拉式方塊。Windows XP Home Edition： 此旗標會篩選掉已知的系統管理員帳戶。
CREDUI_FLAGS_REQUIRE_CERTIFICATE
0x00010
 僅以憑證和智慧卡填入下拉式方塊。 不允許輸入用戶名稱。
CREDUI_FLAGS_REQUIRE_SMARTCARD
0x00100
 僅以憑證或智慧卡填入下拉式方塊。 不允許輸入用戶名稱。
CREDUI_FLAGS_SERVER_CREDENTIAL
0x04000
 只有在尋找相符的認證以預先填入對話框時，此旗標才有意義，驗證應該會失敗。 指定此旗標時，通配符認證將不會相符。 撰寫認證時，它沒有任何作用。 CredUI 不會建立包含通配符的認證。 用戶明確建立或以程序設計方式建立任何找到的專案，就像建立 RAS 連線時一樣。
CREDUI_FLAGS_SHOW_SAVE_CHECK_BOX
0x00040
 如果選取此複選框，請顯示 [儲存] 複選框，並在 pfSave 輸出參數中傳回 TRUE，否則傳回 FALSE。 複選框預設會使用 pfSave 中的值。
CREDUI_FLAGS_USERNAME_TARGET_CREDENTIALS
0x80000
 認證是“runas” 認證。 TargetName 參數會指定要執行之命令或程序的名稱。 它僅用於提示用途。
CREDUI_FLAGS_VALIDATE_USERNAME
0x00400
 檢查用戶名稱是否有效。

傳回值

傳回值是 DWORD ，可以是下列其中一個值。

值 Description
ERROR_CANCELLED
 用戶選擇 [取消]。 pszUserName 和 pszPassword 參數尚未變更。
ERROR_INVALID_FLAGS
 這個狀態會針對任何無效的旗標組態傳回。
ERROR_INVALID_PARAMETER
 pszTargetName 為 NULL、空字串或超過 CREDUI_MAX_DOMAIN_LENGTH，或 pUiInfo 不是 NULL，而且指向的CredUI_INFO結構不符合下列其中一項需求：
  • cbSize 成員必須是一個。
  • 如果 hbmBanner 成員不是 NULL，它必須是類型OBJ_BITMAP。
  • 如果 pszMessageText 成員不是 NULL，它不得大於CREDUI_MAX_MESSAGE_LENGTH。
  • 如果 pszCaptionText 成員不是 NULL，它不得大於 CREDUI_MAX_CAPTION_LENGTH。
ERROR_NO_SUCH_LOGON_SESSION
 無法使用認證管理員。 一般而言，呼叫 CredUIPromptForCredentials 並傳入 CREDUI_FLAGS_DO_NOT_PERSIST 旗標來處理此錯誤。
NO_ERROR
 用戶選擇 [確定]。 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 樹狀結構名稱
  • 收集資訊的封裝名稱
如果資訊不適用於目標計算機，則可能會遺漏此資訊的任何部分。 例如，屬於工作組成員的計算機沒有 NetBIOS 功能變數名稱。

認證會根據目標名稱儲存在認證管理員中。 每個目標名稱通常會盡可能儲存，而不會與認證管理員中已儲存的認證發生衝突。 因為認證是以目標名稱儲存，所以特定使用者只能在認證管理員中儲存每個目標一個認證。

注意

wincred.h 標頭會根據 UNICODE 預處理器常數的定義，將 CredUIPromptForCredentials 定義為自動選取此函式的 ANSI 或 Unicode 版本。 混合使用編碼中性別名與非編碼中性的程序代碼，可能會導致編譯或運行時間錯誤不符。 如需詳細資訊，請參閱 函式原型的慣例。

規格需求

需求 值
最低支援的用戶端 Windows XP [僅限傳統型應用程式]
最低支援的伺服器 Windows Server 2003 [僅限桌面應用程式]
目標平台 Windows
標頭 wincred.h
程式庫 Credui.lib
Dll Credui.dll

另請參閱

CredGetTargetInfo

CredMarshalCredential

CredUIConfirmCredentials

CredUIParseUserName

CredUIPromptForWindowsCredentials

CredUI_INFO

WNetAddConnection