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，并在 dwFlags 参数中设置了CREDUIWIN_AUTHPACKAGE_ONLY标志，则仅枚举能够序列化指定身份验证包凭据的凭据提供程序。

若要获取在输入时用于此参数的相应值，请调用 LsaLookupAuthenticationPackage 函数，并使用该函数的 AuthenticationPackage 参数的值。

输出时，此参数指定将 ppvOutAuthBuffer 缓冲区中的凭据序列化为的身份验证包。

[in, optional] pvInAuthBuffer

指向凭据 BLOB 的指针，该 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
 应仅枚举由 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 [仅限桌面应用]
目标平台 Windows
标头 wincred.h
Library Credui.lib
DLL Credui.dll