共用方式為

CredUIPromptForWindowsCredentialsW 函式 （wincred.h）

  • 發行項

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

語法

CREDUIAPI DWORD CredUIPromptForWindowsCredentialsW(
  [in, optional]      PCREDUI_INFOW 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，則此函式會顯示以父視窗為中心的強制回應對話框。

如果 hwndParentCREDUI_INFO 結構的成員 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 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 函式會叫用認證對話方塊，並在先前的交握之前提示用戶端。 如果在 pvInAuthBuffer 參數中傳遞SSPIPFC_NO_CHECKBOX，則認證提供者不應該顯示複選框。

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

Windows 10 版本 1607：從 Windows 10 版本 1607 開始支援此值。
CREDUIWIN_PACK_32_WOW
0x10000000
 即使提供者是在 64 位系統上執行，認證提供者也應該將 ppvOutAuthBuffer 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 [僅限傳統型應用程式]
目標平臺 窗戶
標頭 wincred.h
連結庫 Credui.lib
DLL Credui.dll