通过

CredUICmdLinePromptForCredentialsA 函数 （wincred.h）

  • 项目

CredUICmdLinePromptForCredentials 函数提示并接受在命令行（控制台）应用程序中工作的用户的凭据信息。 用户键入的名称和密码将传回呼叫应用程序进行验证。

语法

CREDUIAPI DWORD CredUICmdLinePromptForCredentialsA(
  [in]           PCSTR       pszTargetName,
  [in]           PCtxtHandle pContext,
  [in, optional] DWORD       dwAuthError,
  [in, out]      PSTR        UserName,
  [in]           ULONG       ulUserBufferSize,
  [in, out]      PSTR        pszPassword,
  [in]           ULONG       ulPasswordBufferSize,
  [in, out]      PBOOL       pfSave,
  [in]           DWORD       dwFlags
);

参数

[in] pszTargetName

指向 null终止字符串的指针，该字符串包含凭据的目标名称（通常是服务器名称）。 对于 DFS 连接，此字符串采用 ServerName\ShareName形式。 pszTargetName 参数用于标识目标信息，用于存储和检索凭据。

[in] pContext

当前保留，并且必须 NULL。

[in, optional] dwAuthError

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

[in, out] UserName

指向包含凭据用户名的 null终止字符串的指针。 如果为 pszUserName指定了非零长度字符串，则只会提示用户输入密码。 对于用户名/密码以外的凭据，可以传入凭据的封送格式。 此字符串是通过调用 CredMarshalCredential创建的。

此函数将用户提供的名称写入此缓冲区，复制最多 ulUserNameMaxChars 个字符。 此格式的字符串可以通过调用 CredUIParseUsername 函数转换为用户名/密码格式。 其封送格式的字符串可以直接传递给 安全支持提供程序（SSP）。

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

[in] ulUserBufferSize

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

指向 BOOL 的指针，该指针指定 保存 消息的初始状态，并在用户响应命令提示符后接收 保存 消息的状态。 如果 pfSave 未 NULL，CredUIPromptForCredentials 返回NO_ERROR，pfSave 返回 保存 消息的状态。 如果指定了CREDUI_FLAGS_PERSIST标志，则不会显示 保存 消息，但被视为“y”。 如果指定了CREDUI_FLAGS_DO_NOT_PERSIST标志且未指定CREDUI_FLAGS_SHOW_SAVE_CHECK_BOX，则不会显示 保存 消息，但被视为“n”。

[in] dwFlags

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

价值 意义
CREDUI_FLAGS_ALWAYS_SHOW_UI
 如果凭据可以从凭据管理器中的现有凭据返回，则显示用户界面。 仅当还指定了CREDUI_FLAGS_GENERIC_CREDENTIALS并且仅用于CREDUI_FLAGS_GENERIC_CREDENTIALS时，才允许使用此标志。
CREDUI_FLAGS_DO_NOT_PERSIST
 不显示保存消息或存储凭据。

也可以传递CREDUI_FLAGS_SHOW_SAVE_CHECK_BOX来仅显示保存消息，并在 pfSave中返回结果。
CREDUI_FLAGS_EXCLUDE_CERTIFICATES
 提示输入用户名/密码。 如果指定了 pszUserName 参数，则省略用户名。 如果凭据持久保存，请使用凭据存储传入的用户名。
CREDUI_FLAGS_EXPECT_CONFIRMATION
 指定调用方将调用 CredUIConfirmCredentials 以确定返回的凭据是否实际有效。 这可确保无效的凭据不会保存到凭据管理器。 除非指定CREDUI_FLAGS_DO_NOT_PERSIST，否则请指定此标志。
CREDUI_FLAGS_GENERIC_CREDENTIALS
 请考虑用户输入的凭据为通用凭据。
CREDUI_FLAGS_INCORRECT_PASSWORD
 以无提示方式忽略此标志。
CREDUI_FLAGS_PERSIST
 不显示保存消息，但保存凭据，就像用户回答“y”一样。
CREDUI_FLAGS_REQUEST_ADMINISTRATOR
 以无提示方式忽略此标志。
CREDUI_FLAGS_REQUIRE_CERTIFICATE
 保留供将来使用;不要传递此标志。
CREDUI_FLAGS_REQUIRE_SMARTCARD
 使用智能卡并提示输入 PIN。 如果有多个智能卡可用，请选择其中一个智能卡。 如果 pszUserName 参数传递的字符串不为空，则字符串必须与其中一张智能卡上的证书关联的 UPN 匹配。 如果字符串与证书上的整个 UPN 匹配，或者字符串与证书 UPN 中的 at sign （@） 左侧部分匹配，则 UPN 匹配。 如果有匹配项，则选择匹配的智能卡。
CREDUI_FLAGS_SERVER_CREDENTIAL
 如果身份验证失败，此标志仅在查找匹配凭据以预填充对话框时有意义。 指定此标志后，将不匹配通配符凭据。 写入凭据时，它不起作用。 CredUI 不会创建包含通配符的凭据。 任何发现都由用户显式创建或以编程方式创建，就像建立 RAS 连接时的情况一样。
CREDUI_FLAGS_SHOW_SAVE_CHECK_BOX
 显示保存消息，并在 pfSave out 参数中返回 TRUE（如果用户回答“y”“），FALSE（如果用户回答”n“）。 必须指定CREDUI_FLAGS_DO_NOT_PERSIST才能使用此标志。
CREDUI_FLAGS_USERNAME_TARGET_CREDENTIALS
 凭据是运行方式凭据。 pszTargetName 参数指定要运行的命令或程序的名称。 它仅用于提示目的。

返回值

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

价值 描述
ERROR_INVALID_FLAGS
 对于无效的任何标志组合，将返回此状态。
ERROR_INVALID_PARAMETER
 pszTargetNameNULL、空字符串或长于 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
 无法使用凭据管理器。 通常，通过调用 CredUICmdLinePromptForCredentials 并传入CREDUI_FLAGS_DO_NOT_PERSIST标志来处理此错误。
NO_ERROR
 用户选择“确定”。 pszUserName、pszPassword，pfSave 变量将返回前面记录的值。

言论

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

如果未指定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_FLAGS_PROMPT_FOR_SAVE，则 pfSave 参数不得 NULL。

CREDUI_FLAGS_REQUIRE_SMARTCARD和CREDUI_FLAGS_EXCLUDE_CERTIFICATES标志互斥。 CredUICmdLinePromptForCredentials 支持提示输入智能卡证书或基于密码的凭据。 它不支持不是智能卡证书的证书，也不支持在单个调用中提示这两个证书。

呼叫模式

  • 调用方将尝试访问目标资源，调用 credui（传递目标资源和失败状态的说明），调用 CredUIParseUserName，再次访问目标资源，然后调用 CredUIConfirmCredentials。
  • 调用方可以通过传递CREDUI_FLAGS_DO_NOT_PERSIST来提示输入凭据，而无需访问任何资源。
目标信息

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

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

凭据基于目标名称存储在凭据管理器中。 每个目标名称通常存储，而不会与凭据管理器中已存储的凭据相冲突。 按目标名称存储凭据的一个重要效果是，特定用户每个目标只能有一个凭据存储在凭据管理器中。

注意

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

要求

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

另请参阅

CredGetTargetInfo

CredMarshalCredential

CredUIConfirmCredentials

CredUIParseUserName

CredUI_INFO

WNetAddConnection