通过

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，则此函数将显示以父窗口为中心的模式对话框。

如果 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

一个值，指定此函数的行为。 此值可以是以下一个或多个值的按位或 组合。

价值 意义
CREDUIWIN_GENERIC
0x1
 调用方请求凭据提供程序以纯文本形式返回用户名和密码。

此值不能与 SECURE_PROMPT结合使用。
CREDUIWIN_CHECKBOX
0x2
 对话框中将显示 “保存”复选框。
CREDUIWIN_AUTHPACKAGE_ONLY
0x10
 仅应枚举支持 pulAuthPackage 参数指定的身份验证包的凭据提供程序。

此值不能与 CREDUIWIN_IN_CRED_ONLY结合使用。
CREDUIWIN_IN_CRED_ONLY
0x20
 应枚举由 pulAuthPackage 参数指定的身份验证包的 pvInAuthBuffer 参数指定的凭据。

如果设置了此标志，并且 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
 凭据提供程序应将 ppvOutAuthBuffer 指向的凭据 BLOB 与 32 位边界保持一致，即使提供程序在 64 位系统上运行也是如此。
0x80000000
 Windows Hello 凭据将打包在智能卡身份验证缓冲区中。 这仅适用于人脸、指纹和 PIN 凭据提供程序。

Windows 10 版本 1809：从 Windows 10 版本 1809 开始支持此值。

返回值

如果函数成功，该函数将返回 ERROR_SUCCESS。 如果用户取消函数，则返回 ERROR_CANCELLED。 任何其他返回值都表示函数无法加载。

言论

此函数不保存凭据。

使用 SSPI 对用户进行身份验证的应用程序不应调用此函数。 请改为调用 SspiPromptForCredentials。

注意

wincred.h 标头将 CredUIPromptForWindowsCredentials 定义为一个别名，该别名根据 UNICODE 预处理器常量的定义自动选择此函数的 ANSI 或 Unicode 版本。 将中性编码别名与不中性编码的代码混合使用可能会导致编译或运行时错误不匹配。 有关详细信息，请参阅函数原型的 约定。

要求

要求 价值
最低支持的客户端 Windows Vista [仅限桌面应用]
支持的最低服务器 Windows Server 2008 [仅限桌面应用]
目标平台 窗户
标头 wincred.h
库 Credui.lib
DLL Credui.dll