共用方式為


CredUICmdLinePromptForCredentialsA 函式 (wincred.h)

CredUICmdLinePromptForCredentials 函式會提示使用者在命令行 (控制台) 應用程式中輸入並接受認證資訊。 使用者輸入的名稱和密碼會傳回給呼叫端應用程式以進行驗證。

語法

CREDUIAPI DWORD CredUICmdLinePromptForCredentialsA(
  [in]           PCSTR       pszTargetName,
  [in]           PCtxtHandle pContext,
  [in, optional] DWORD       dwAuthError,
  [in, out]      PSTR        UserName,
  [in]           ULONG       ulUserBufferSize,
  [in, out]      PSTR        pszPassword,
  [in]           ULONG       ulPasswordBufferSize,
  [in, out]      PBOOL       pfSave,
  [in]           DWORD       dwFlags
);

參數

[in] pszTargetName

Null 終止字串的指標,其中包含認證的目標名稱,通常是伺服器名稱。 對於 DFS 連線,此字串的格式為 ServerName\ShareNamepszTargetName 參數可用來識別目標資訊,並用來儲存和擷取認證。

[in] pContext

目前保留且必須是 NULL

[in, optional] dwAuthError

指定為何需要提示輸入認證。 呼叫端可以傳遞由另一個驗證呼叫傳回的這個 Windows 錯誤參數,以允許對話方塊容納特定錯誤。 例如,如果傳遞密碼過期狀態代碼,對話框會提示使用者變更帳戶上的密碼。

[in, out] UserName

包含認證用戶名稱之 Null 終止字串的指標。 如果為 pszUserName 指定非零長度字串,則只會提示使用者輸入密碼。 在使用者名稱/密碼以外的認證的情況下,可以傳入認證的封送處理格式。 此字串是由呼叫 CredMarshalCredential 所建立。

此函式會將使用者提供的名稱寫入此緩衝區,複製最多 ulUserNameMaxChars 字元。 此格式的字串可以藉由呼叫 CredUIParseUsername 函式,轉換成使用者名稱/密碼格式。 其封送處理格式的字串可以直接傳遞至 安全性支援提供者 , (SSP) 。

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

[in] ulUserBufferSize

可以複製到 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] pfSave

BOOL 的指標,指定儲存訊息的初始狀態,並在用戶回應命令提示字元之後接收儲存訊息的狀態。 如果 pfSave 不是 NULL而且 CredUIPromptForCredentials 會傳回NO_ERROR,pfSave 會傳回儲存訊息的狀態。 如果指定CREDUI_FLAGS_PERSIST旗標,則不會顯示 儲存訊息, 但會被視為 “y”。 如果指定CREDUI_FLAGS_DO_NOT_PERSIST旗標且未指定CREDUI_FLAGS_SHOW_SAVE_CHECK_BOX,則不會顯示 儲存訊息, 但會被視為 “n”。

[in] dwFlags

指定此函式特殊行為的 DWORD 值。 這個值可以是零個或多個下列值的位 OR 組合。

意義
CREDUI_FLAGS_ALWAYS_SHOW_UI
如果認證可以從認證管理員中的現有認證傳回,則顯示使用者介面。 只有在同時指定CREDUI_FLAGS_GENERIC_CREDENTIALS且只與CREDUI_FLAGS_GENERIC_CREDENTIALS搭配使用時,才允許此旗標。
CREDUI_FLAGS_DO_NOT_PERSIST
請勿顯示儲存訊息或儲存認證。

CREDUI_FLAGS_SHOW_SAVE_CHECK_BOX也可以傳遞來僅顯示儲存訊息,並在 pfSave 中傳回結果。

CREDUI_FLAGS_EXCLUDE_CERTIFICATES
提示輸入使用者名稱/密碼。 如果指定 pszUserName 參數,則會省略用戶名稱。 如果保存認證,請使用認證來儲存傳入的用戶名稱。
CREDUI_FLAGS_EXPECT_CONFIRMATION
指定呼叫端會呼叫 CredUIConfirmCredentials ,以判斷傳回的認證是否實際有效。 這可確保無效的認證不會儲存至認證管理員。 除非指定CREDUI_FLAGS_DO_NOT_PERSIST,否則請指定此旗標。
CREDUI_FLAGS_GENERIC_CREDENTIALS
請考慮使用者輸入的認證一般認證。
CREDUI_FLAGS_INCORRECT_PASSWORD
以無訊息方式忽略此旗標。
CREDUI_FLAGS_PERSIST
請勿顯示儲存訊息,但儲存認證,就像使用者回答 “y”。
CREDUI_FLAGS_REQUEST_ADMINISTRATOR
以無訊息方式忽略此旗標。
CREDUI_FLAGS_REQUIRE_CERTIFICATE
保留供日後使用;請勿傳遞此旗標。
CREDUI_FLAGS_REQUIRE_SMARTCARD
使用智慧卡並提示 PIN。 如果有多個智慧卡可用,請選取其中一張智慧卡。 如果 pszUserName 參數傳遞不是空的字串,字串必須符合其中一張智慧卡上與憑證相關聯的 UPN。 如果字串符合憑證上整個 UPN,或字串符合憑證 UPN 的左邊部分 (@) ,則 UPN 會相符。 如果有相符專案,則會選取相符的智慧卡。
CREDUI_FLAGS_SERVER_CREDENTIAL
此旗標只有在尋找相符的認證以預先填入對話框時才有意義,驗證應該會失敗。 指定此旗標時,不會比對通配符認證。 寫入認證時沒有任何作用。 CredUI 不會建立包含通配符的認證。 用戶明確建立或以程序設計方式建立任何找到的專案,如建立 RAS 連線時所發生。
CREDUI_FLAGS_SHOW_SAVE_CHECK_BOX
如果使用者回答 「y」,則會在 pfSave out 參數中顯示儲存訊息並傳回 TRUE,如果使用者回答 “n”,則為 FALSE。 必須指定CREDUI_FLAGS_DO_NOT_PERSIST才能使用此旗標。
CREDUI_FLAGS_USERNAME_TARGET_CREDENTIALS
認證是執行身分認證。 pszTargetName 參數會指定正在執行的命令或程序名稱。 它僅用於提示用途。

傳回值

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

Description
ERROR_INVALID_FLAGS
此狀態會針對任何無效的旗標組合傳回。
ERROR_INVALID_PARAMETER
pszTargetNameNULL、空字串或超過 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
無法使用認證管理員。 一般而言,呼叫 CredUICmdLinePromptForCredentials 並傳入 CREDUI_FLAGS_DO_NOT_PERSIST 旗標來處理此錯誤。
NO_ERROR
用戶選擇 [確定]。 pszUserNamepszPasswordpfSave 變數會傳回稍早記載的值。

備註

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旗標互斥。 如果未指定認證,認證就是網域認證。

如果未指定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_FLAGS_PROMPT_FOR_SAVE,pfSave 參數不得為 NULL

CREDUI_FLAGS_REQUIRE_SMARTCARD和CREDUI_FLAGS_EXCLUDE_CERTIFICATES旗標互斥。 CredUICmdLinePromptForCredentials 支援提示智慧卡憑證或密碼型認證。 它不支援不是智慧卡憑證的憑證,也不支援在單一呼叫時提示兩者。

呼叫模式

  • 呼叫端會嘗試存取目標資源、呼叫 credui (傳遞目標資源的描述和失敗狀態) 、呼叫 CredUIParseUserName、再次存取目標資源,然後呼叫 CredUIConfirmCredentials
  • 呼叫端可以藉由傳遞CREDUI_FLAGS_DO_NOT_PERSIST來提示輸入認證,而不需要存取任何資源。
目標資訊

目標資訊是要存取之資源位置的相關信息。 如需資源所有潛在目標名稱的清單,請呼叫 CredGetTargetInfoCredGetTargetInfo 會傳回當其中一個套件用來向具名目標進行驗證時,Negotiate、NTLM 或 Kerberos 驗證套件所快取的資訊。 CredGetTargetInfo 會傳回目標的一些或所有名稱:

  • 計算機的 NetBIOS 伺服器名稱
  • 計算機的 DNS 伺服器名稱
  • 計算機所屬網域的 NetBIOS 功能變數名稱
  • 計算機所屬網域的 DNS 功能變數名稱
  • 計算機所屬樹狀結構的 DNS 樹狀結構名稱
  • 收集資訊的封裝名稱
如果資訊不適用於目標計算機,則可能會遺漏此資訊的任何部分。 例如,屬於工作組成員的計算機沒有 NetBIOS 功能變數名稱。 屬於 Windows 網域成員的電腦沒有 DNS 功能變數名稱或 DNS 樹狀結構名稱。

認證會根據目標名稱儲存在認證管理員中。 每個目標名稱通常會盡可能儲存,而不會與認證管理員中已儲存的認證發生衝突。 依目標名稱儲存認證的重要效果是,特定使用者在每個儲存在認證管理員中的目標只能有一個認證。

注意

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

規格需求

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

另請參閱

CredGetTargetInfo

CredMarshalCredential

CredUIConfirmCredentials

CredUIParseUserName

CredUI_INFO

WNetAddConnection