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\ShareName。 pszTargetName 參數可用來識別目標資訊，並用來儲存和擷取認證。

[in] pContext

目前保留且必須是 NULL。

[in, optional] dwAuthError

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

[in, out] UserName

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

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

如果未指定CREDUI_FLAGS_DO_NOT_PERSIST旗標，則此參數中傳回的值是不應該檢查、列印或保存的格式，而不是將它傳遞至 CredUIParseUsername。 CredUIParseUsername 的後續結果只能傳遞至客戶端驗證 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
 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
 無法使用認證管理員。 一般而言，呼叫 CredUICmdLinePromptForCredentials 並傳入 CREDUI_FLAGS_DO_NOT_PERSIST 旗標來處理此錯誤。
NO_ERROR
 用戶選擇 [確定]。 pszUserName、pszPassword 和 pfSave 變數會傳回稍早記載的值。

備註

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來提示輸入認證，而不需要存取任何資源。
目標資訊

目標資訊是要存取之資源位置的相關信息。 如需資源所有潛在目標名稱的清單，請呼叫 CredGetTargetInfo。 CredGetTargetInfo 會傳回當其中一個套件用來向具名目標進行驗證時，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