CredUIPromptForWindowsCredentialsA 函式 (wincred.h)

  • 發行項

CredUIPromptForWindowsCredentials 函式會建立並顯示可設定的對話方塊，讓用戶能夠使用安裝在本機電腦上的任何認證提供者來提供認證資訊。

語法

CREDUIAPI DWORD CredUIPromptForWindowsCredentialsA(
  [in, optional]      PCREDUI_INFOA pUiInfo,
  [in]                DWORD         dwAuthError,
  [in, out]           ULONG         *pulAuthPackage,
  [in, optional]      LPCVOID       pvInAuthBuffer,
  [in]                ULONG         ulInAuthBufferSize,
  [out]               LPVOID        *ppvOutAuthBuffer,
  [out]               ULONG         *pulOutAuthBufferSize,
  [in, out, optional] BOOL          *pfSave,
  [in]                DWORD         dwFlags
);

參數

[in, optional] pUiInfo

CREDUI_INFO 結構的指標，其中包含自定義此函式所顯示之對話框外觀的資訊。

如果CREDUI_INFO結構的 hwndParent 成員不是 NULL，則此函式會顯示以父視窗為中心的模式對話方塊。

如果CREDUI_INFO結構的 hwndParent 成員為 NULL，此函式會在畫面上顯示置中對話方塊。

此函式會忽略 CREDUI_INFO 結構的 hbmBanner 成員。

[in] dwAuthError

在 Winerror.h 中定義的 Windows 錯誤碼，顯示在對話框中。 如果先前收集的認證無效，則呼叫端會使用此參數，將收集認證之 API 的錯誤訊息傳遞至此函式 (，例如 Winlogon) 。 對應的錯誤訊息會格式化並顯示在對話框中。 將此參數的值設定為零，以顯示沒有錯誤訊息。

[in, out] pulAuthPackage

在輸入時，此參數的值是用來指定 pvInAuthBuffer 緩衝區中認證串行化的驗證套件。 如果 pvInAuthBuffer 的值是 NULL ，而且 CREDUIWIN_AUTHPACKAGE_ONLY 旗標是在 dwFlags 參數中設定，則只會列舉能夠串行化指定驗證套件之認證的認證提供者。

若要取得在輸入上用於此參數的適當值，請呼叫 LsaLookupAuthenticationPackage 函式，並使用該函式的 AuthenticationPackage 參數值。

在輸出時，此參數會指定 ppvOutAuthBuffer 緩衝區中認證串行化的驗證套件。

[in, optional] pvInAuthBuffer

用來填入對話框中認證欄位之認證 BLOB 的指標。 將此參數的值設定為 NULL ，讓認證欄位保持空白。

[in] ulInAuthBufferSize

pvInAuthBuffer 緩衝區的大小，以位元組為單位。

[out] ppvOutAuthBuffer

輸出上指定認證 BLOB 的指標位址。 針對 Kerberos、NTLM 或 Negotiate 認證，請呼叫 CredUnPackAuthenticationBuffer 函式，將此 BLOB 轉換為認證的字串表示。

當您完成使用認證 BLOB 時，請藉由呼叫 SecureZeroMemory 函式 從記憶體中清除它，並藉由呼叫 CoTaskMemFree 函式來釋放它。

[out] pulOutAuthBufferSize

ppvOutAuthBuffer 緩衝區的大小，以位元組為單位。

[in, out, optional] pfSave

在輸入時，布爾值的指標會指定是否在此函式顯示的對話框中選取 [ 儲存 ] 複選框。 在輸出時，此參數的值會指定當使用者按兩下對話框中的 [提交] 按鈕時，是否選取 [儲存] 複選框。 將此參數設定為 NULL ，以忽略 [ 儲存 ] 複選框。

如果未在 dwFlags 參數中設定CREDUIWIN_CHECKBOX旗標，則會忽略此參數。

[in] dwFlags

值，指定這個函式的行為。 這個值可以是下列一或多個值的位 OR 組合。

值 意義
CREDUIWIN_GENERIC
0x1
 呼叫端要求認證提供者以純文本傳回使用者名稱和密碼。

此值無法與 SECURE_PROMPT結合。
CREDUIWIN_CHECKBOX
0x2
 [ 儲存] 複選框會顯示在對話框中。
CREDUIWIN_AUTHPACKAGE_ONLY
0x10
 只應該列舉支援 pulAuthPackage 參數所指定之驗證套件的認證提供者。

此值無法與 CREDUIWIN_IN_CRED_ONLY結合。
CREDUIWIN_IN_CRED_ONLY
0x20
 只有 pvInAuthBuffer 參數所指定的認證，才應該列舉 pulAuthPackage 參數所指定的驗證套件。

如果已設定此旗標，且 pvInAuthBuffer 參數為 NULL，則函式會失敗。

此值無法與 CREDUIWIN_AUTHPACKAGE_ONLY結合。
CREDUIWIN_ENUMERATE_ADMINS
0x100
 認證提供者應該只列舉系統管理員。 此值僅適用於用戶帳戶控制 (UAC) 用途。 我們建議外部呼叫端未設定此旗標。
CREDUIWIN_ENUMERATE_CURRENT_USER
0x200
 應該只列舉 pulAuthPackage 參數所指定之驗證套件的傳入認證。
CREDUIWIN_SECURE_PROMPT
0x1000
 認證對話框應該會顯示在安全桌面上。 此值無法與 CREDUIWIN_GENERIC結合。

Windows Vista： 從 Windows Vista SP1 開始，支援此值。
CREDUIWIN_PREPROMPTING
0x2000
 SspiPromptForCredentials 函式會叫用認證對話方塊，並在先前交握之前提示用戶端。 如果SSPIPFC_NO_CHECKBOX是在 pvInAuthBuffer 參數中傳遞，則認證提供者不應該顯示複選框。

Windows Vista： 從 Windows Vista SP1 開始，支援此值。
0x40000
 認證提供者不會封裝 AAD 授權單位名稱。 這隻適用於已加入 Azure AD 的裝置。

Windows 10 版本 1607：從 1607 版 Windows 10 開始支援此值。
CREDUIWIN_PACK_32_WOW
0x10000000
 即使提供者在 64 位系統上執行，認證提供者也應該將 ppvOutAuthBuffer 參數指向的認證 BLOB 對齊 32 位界限。
0x80000000
 Windows Hello 認證會封裝在智慧卡驗證緩衝區中。 這僅適用於臉部、指紋和 PIN 認證提供者。

Windows 10 版本 1809：從 Windows 10 版本 1809 開始支援此值。

傳回值

如果函式成功，函式會傳回 ERROR_SUCCESS。 如果使用者取消函式，則會傳回 ERROR_CANCELLED。 任何其他傳回值都表示函式無法載入。

備註

此函式不會儲存認證。

使用 SSPI 來驗證使用者的應用程式不應該呼叫此函式。 請改為呼叫 SspiPromptForCredentials。

注意

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

規格需求

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