CredUIPromptForCredentialsA 函数 (wincred.h)

  • 项目

CredUIPromptForCredentials 函数创建并显示一个可接受用户凭据信息的可配置对话框。

出于以下原因，面向 Windows Vista 或 Windows Server 2008 的应用程序应调用 CredUIPromptForWindowsCredentials 而不是此函数：

语法

CREDUIAPI DWORD CredUIPromptForCredentialsA(
  [in, optional] PCREDUI_INFOA pUiInfo,
  [in]           PCSTR         pszTargetName,
  [in]           PCtxtHandle   pContext,
  [in, optional] DWORD         dwAuthError,
  [in, out]      PSTR          pszUserName,
  [in]           ULONG         ulUserNameBufferSize,
  [in, out]      PSTR          pszPassword,
  [in]           ULONG         ulPasswordBufferSize,
  [in, out]      BOOL          *save,
  [in]           DWORD         dwFlags
);

参数

[in, optional] pUiInfo

指向 CREDUI_INFO 结构的指针，该结构包含用于自定义对话框外观的信息。

[in] pszTargetName

指向以 null 结尾的字符串的指针，该字符串包含凭据的目标名称，通常是服务器名称。 对于分布式文件系统 (DFS) 连接，此字符串的格式为 ServerName\ShareName。 此参数用于在存储和检索凭据时标识目标信息。

[in] pContext

此参数留待将来使用。 它必须为 NULL。

[in, optional] dwAuthError

指定需要凭据对话框的原因。 调用方可以传递由另一个身份验证调用返回的此 Windows 错误参数，以允许对话框适应某些错误。 例如，如果密码过期状态代码已传递，对话框可能会提示用户更改帐户的密码。

[in, out] pszUserName

指向以 null 结尾的字符串的指针，该字符串包含凭据的用户名。 如果传递了非零长度字符串，则对话框的 UserName 选项将预先填充该字符串。 对于 除 UserName/Password 以外的凭据，可以传入凭据的封送格式。 此字符串是通过调用 CredMarshalCredential 创建的。

此函数将用户提供的名称复制到此缓冲区，复制的最大 ulUserNameMaxChars 字符数。 可以使用 CredUIParseUsername 将此格式转换为 UserName/密码格式。 封送格式可以直接传递到 安全支持提供程序 (SSP) 。

如果未指定CREDUI_FLAGS_DO_NOT_PERSIST标志，则此参数中返回的值的形式不应进行检查、打印或保留，而不应将其传递给 CredUIParseUsername。 CredUIParseUsername 的后续结果只能传递给客户端身份验证函数，例如 WNetAddConnection 或 SSP 函数。

如果未指定域或服务器作为此参数的一部分，则 pszTargetName 参数的值将用作域以形成 DomainName\UserName 对。 在输出时，此参数接收包含该 DomainName\UserName 对的字符串。

[in] ulUserNameBufferSize

可复制到 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] save

指向 BOOL 的指针，该指针指定“保存检查”框的初始状态，并在用户响应对话框后接收“保存检查”框的状态。 如果此值不为 NULL，并且 CredUIPromptForCredentials 返回NO_ERROR，则当用户在对话框中选择“确定”时，pfSave 将返回“保存检查”框的状态。

如果指定了CREDUI_FLAGS_PERSIST标志，则不显示“保存检查”框，但被视为处于选中状态。

如果指定了CREDUI_FLAGS_DO_NOT_PERSIST标志并且未指定CREDUI_FLAGS_SHOW_SAVE_CHECK_BOX，则不显示“保存检查”框，但被视为已清除。

需要使用 CredUI 提示用户输入凭据，但不需要凭据管理器提供的凭据管理服务的应用程序可以使用 pfSave 在用户关闭对话框后接收“保存检查”框的状态。 为此，调用方必须在 dwFlags 中指定CREDUI_FLAGS_DO_NOT_PERSIST和CREDUI_FLAGS_SHOW_SAVE_CHECK_BOX。 设置CREDUI_FLAGS_DO_NOT_PERSIST和CREDUI_FLAGS_SHOW_SAVE_CHECK_BOX时，应用程序负责在函数返回后检查 *pfSave ;如果 *pfSave 为 TRUE，则应用程序必须采取适当的操作，将用户凭据保存在应用程序的资源中。

[in] dwFlags

指定此函数的特殊行为的 DWORD 值。 此值可以是以下零个或多个值的按位或 组合。

值 含义
CREDUI_FLAGS_ALWAYS_SHOW_UI
0x00080
 指定即使可以从凭据管理器中的现有凭据返回凭据，也会显示用户界面。 仅当还指定了CREDUI_FLAGS_GENERIC_CREDENTIALS时，才允许使用此标志。
CREDUI_FLAGS_COMPLETE_USERNAME
0x00800
 使用用户名提示填充组合框。
CREDUI_FLAGS_DO_NOT_PERSIST
0x00002
 不要存储凭据或显示检查框。 可以传递带有此标志的CREDUI_FLAGS_SHOW_SAVE_CHECK_BOX，以便仅显示“保存检查”框，结果将在 pfSave 输出参数中返回。
CREDUI_FLAGS_EXCLUDE_CERTIFICATES
0x00008
 仅使用用户名/密码填充组合框。 不要在组合框中显示证书或智能卡。
CREDUI_FLAGS_EXPECT_CONFIRMATION
0x20000
 指定调用方在检查以确定返回的凭据是否实际有效后调用 CredUIConfirmCredentials 。 此机制可确保无效的凭据不会保存到凭据管理器。 在所有情况下指定此标志，除非指定了CREDUI_FLAGS_DO_NOT_PERSIST。
CREDUI_FLAGS_GENERIC_CREDENTIALS
0x40000
 将用户输入的凭据视为通用凭据。
CREDUI_FLAGS_INCORRECT_PASSWORD
0x00001
 通过显示“登录失败”气球提示，通知用户凭据不足。
CREDUI_FLAGS_KEEP_USERNAME
0x100000
 不允许用户更改提供的用户名。
CREDUI_FLAGS_PASSWORD_ONLY_OK
0x00200
 仅使用密码填充组合框。 不允许输入用户名。
CREDUI_FLAGS_PERSIST
0x01000
 不显示“保存检查”框，但凭据的保存就像显示和选中框一样。
CREDUI_FLAGS_REQUEST_ADMINISTRATOR
0x00004
 仅使用本地管理员填充组合框。Windows XP 家庭版： 此标志将筛选出已知的管理员帐户。
CREDUI_FLAGS_REQUIRE_CERTIFICATE
0x00010
 仅使用证书和智能卡填充组合框。 不允许输入用户名。
CREDUI_FLAGS_REQUIRE_SMARTCARD
0x00100
 仅使用证书或智能卡填充组合框。 不允许输入用户名。
CREDUI_FLAGS_SERVER_CREDENTIAL
0x04000
 如果身份验证失败，此标志仅在找到匹配凭据以预填充对话框时才有意义。 指定此标志时，通配符凭据将不匹配。 写入凭据时，它不起作用。 CredUI 不会创建包含通配符的凭据。 找到的任何内容要么由用户显式创建，要么以编程方式创建，就像建立 RAS 连接时一样。
CREDUI_FLAGS_SHOW_SAVE_CHECK_BOX
0x00040
 如果选择了“检查”框，则显示“保存检查”框并在 pfSave 输出参数中返回 TRUE，否则返回 FALSE。 默认情况下，复选框使用 pfSave 中的值。
CREDUI_FLAGS_USERNAME_TARGET_CREDENTIALS
0x80000
 凭据是“运行方式”凭据。 TargetName 参数指定运行的命令或程序的名称。 它仅用于提示目的。
CREDUI_FLAGS_VALIDATE_USERNAME
0x00400
 检查用户名是否有效。

返回值

返回值为 DWORD ，可以是以下值之一。

值 说明
ERROR_CANCELLED
 用户选择了 “取消”。 pszUserName 和 pszPassword 参数未更改。
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
 不能使用凭据管理器。 通常，通过调用 CredUIPromptForCredentials 并传入 CREDUI_FLAGS_DO_NOT_PERSIST 标志来处理此错误。
NO_ERROR
 用户选择 “确定”。 pszUserName、pszPassword 和 pfSave 参数将返回前面所述的值。

注解

CredUIPromptForCredentials 函数创建并显示应用程序模式对话框。 显示对话框后，直到用户或应用程序关闭该对话框，应用程序中的其他窗口都不能变为活动状态。

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的标志是互斥的。 如果两者均未指定，则凭据为域凭据。

X509 证书的 增强型密钥用法 (EKU) 值 szOID_KP_SMARTCARD_LOGON ( 1.3.6.1.4.1.1.311.20.2.2) 。

Windowsxp： 显示 X509 证书不需要此 EKU 值。

如果未指定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 (传递目标资源的说明和故障状态) ，调用 CredUIParseUserName，再次访问目标资源，然后调用 CredUIConfirmCredentials。
  • 调用方可以通过传递CREDUI_FLAGS_DO_NOT_PERSIST来提示输入凭据，而无需访问任何资源。
  • 对于泛型凭据，没有身份验证包。 因此，应用程序需要访问凭据才能进行身份验证。 提示输入凭据，未在第一次身份验证之前传递CREDUI_FLAGS_ALWAYS_SHOW_UI。 仅当凭据管理器中没有凭据时，才会显示用户界面。 在来自应用程序内的所有后续消息中，将传递CREDUI_FLAGS_ALWAYS_SHOW_UI，因为凭据管理器中的凭据显然对该资源无效。
目标信息

目标信息是有关要访问的资源位置的信息。 有关资源的所有潜在目标名称的列表，请调用 CredGetTargetInfo。 使用其中一个包对命名目标进行身份验证时，CredGetTargetInfo 返回由 Negotiate、NTLM 或 Kerberos 身份验证包缓存的信息。 CredGetTargetInfo 为目标返回以下部分或全部名称：

  • 计算机的 NetBIOS 服务器名称
  • 计算机的 DNS 服务器名称
  • 计算机所属域的 NetBIOS 域名
  • 计算机所属域的 DNS 域名
  • 计算机所属树的 DNS 树名称
  • 收集信息的包的名称
如果信息不适用于目标计算机，则此信息中的任何部分都可能缺失。 例如，作为工作组成员的计算机没有 NetBIOS 域名。

凭据基于目标名称存储在凭据管理器中。 每个目标名称都尽可能存储，而不会与凭据管理器中已存储的凭据发生冲突。 由于凭据按目标名称存储，因此特定用户只能有一个凭据存储在凭据管理器中的每个目标。

注意

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

要求

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

另请参阅

CredGetTargetInfo

CredMarshalCredential

CredUIConfirmCredentials

CredUIParseUserName

CredUIPromptForWindowsCredentials

CredUI_INFO

WNetAddConnection