Функция CredUIPromptForCredentialsA (wincred.h)
Функция CredUIPromptForCredentials создает и отображает настраиваемое диалоговое окно, которое принимает учетные данные пользователя.
Приложения, предназначенные для Windows Vista или Windows Server 2008, должны вызывать CredUIPromptForWindowsCredentials вместо этой функции по следующим причинам:
- CredUIPromptForWindowsCredentials соответствует текущему пользовательскому интерфейсу Windows.
- CredUIPromptForWindowsCredentials является более расширяемым, что позволяет интегрировать дополнительные механизмы проверки подлинности, такие как биометрические данные и смарт-карты.
- CredUIPromptForWindowsCredentials соответствует спецификации Common Criteria.
Синтаксис
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
Указатель на строку с пустым завершением, которая содержит имя целевого объекта для учетных данных, обычно это имя сервера. Для подключений распределенной файловой системы (DFS) эта строка имеет форму Имя_\сервера имя_сервера. Этот параметр используется для определения целевой информации при хранении и получении учетных данных.
[in] pContext
Этот параметр зарезервирован для использования в будущем. Он должен иметь значение NULL.
[in, optional] dwAuthError
Указывает, зачем требуется диалоговое окно учетных данных. Вызывающий объект может передать этот параметр ошибки Windows, возвращаемый другим вызовом проверки подлинности, чтобы разрешить в диалоговом окне учесть определенные ошибки. Например, если передается код состояния пароля с истекшим сроком действия, диалоговое окно может предложить пользователю изменить пароль в учетной записи.
[in, out] pszUserName
Указатель на строку, завершающуюся значением NULL, которая содержит имя пользователя для учетных данных. Если передается строка ненулевой длины, параметр UserName диалогового окна предварительно заполняется строкой. В случае учетных данных, отличных от userName/Password, можно передать маршалированные формат учетных данных. Эта строка создается путем вызова CredMarshalCredential.
Эта функция копирует предоставленное пользователем имя в этот буфер, копируя не более символов ulUserNameMaxChars . Этот формат можно преобразовать в формат userName/Password с помощью CredUIParseUsername. Маршалированные форматы можно передать непосредственно поставщику поддержки безопасности (SSP).
Если флаг CREDUI_FLAGS_DO_NOT_PERSIST не указан, значение, возвращаемое в этом параметре, будет иметь форму, которую не следует проверять, печатать или сохранять, кроме передачи в CredUIParseUsername. Последующие результаты CredUIParseUsername можно передать только в функцию проверки подлинности на стороне клиента, например WNetAddConnection или функцию SSP.
Если в этом параметре не указан ни домен, ни сервер, значение параметра pszTargetName используется в качестве домена для формирования парыимя_пользователяdomainName\. В выходных данных этот параметр получает строку, содержащую эту паруимя_\пользователя_домена.
[in] ulUserNameBufferSize
Максимальное число символов, которые можно скопировать в pszUserName , включая завершающий символ NULL.
[in, out] pszPassword
Указатель на строку, завершающуюся значением NULL, которая содержит пароль для учетных данных. Если для pszPassword указана строка ненулевой длины, параметр пароля диалогового окна будет предварительно заполнен строкой.
Эта функция копирует предоставленный пользователем пароль в этот буфер, копируя максимум символов ulPasswordMaxChars . Если флаг CREDUI_FLAGS_DO_NOT_PERSIST не указан, значение, возвращаемое в этом параметре, будет иметь форму, которую не следует проверять, печатать или сохранять, кроме как передавать его в функцию проверки подлинности на стороне клиента, например WNetAddConnection или функцию поставщика общих служб.
Завершив использование пароля, очистите его из памяти, вызвав функцию SecureZeroMemory . Дополнительные сведения о защите паролей см. в разделе Обработка паролей.
[in] ulPasswordBufferSize
Максимальное количество символов, которые можно скопировать в pszPassword , включая завершающий символ 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 для получения состояния поля Сохранить проверка после закрытия пользователем диалогового окна. Для этого вызывающий объект должен указать CREDUI_FLAGS_DO_NOT_PERSIST и CREDUI_FLAGS_SHOW_SAVE_CHECK_BOX в dwFlags. Если заданы CREDUI_FLAGS_DO_NOT_PERSIST и CREDUI_FLAGS_SHOW_SAVE_CHECK_BOX, приложение отвечает за проверку *pfSave после возврата функции. Если *pfSave имеет значение TRUE, приложение должно предпринять соответствующие действия для сохранения учетных данных пользователя в ресурсах приложения.
[in] dwFlags
Значение DWORD , указывающее специальное поведение для этой функции. Это значение может быть побитовой или комбинацией нуля или нескольких следующих значений.
| Значение | Значение |
|---|---|
|
Указывает, что пользовательский интерфейс будет отображаться, даже если учетные данные могут быть возвращены из существующих учетных данных в диспетчере учетных данных. Этот флаг разрешен только в том случае, если также указан CREDUI_FLAGS_GENERIC_CREDENTIALS. |
|
Заполните поле со списком запросом на ввод имени пользователя. |
|
Не храните учетные данные и не отображайте поля проверка. Вы можете передать CREDUI_FLAGS_SHOW_SAVE_CHECK_BOX с этим флагом, чтобы отобразить только поле Сохранить проверка, а результат возвращается в выходном параметре pfSave. |
|
Заполните поле со списком только именем пользователя или паролем. Не отображайте сертификаты или смарт-карты в поле со списком. |
|
Указывает, что вызывающий объект будет вызывать CredUIConfirmCredentials после проверки, чтобы определить, действительно ли возвращенные учетные данные действительны. Этот механизм гарантирует, что недопустимые учетные данные не будут сохранены в диспетчере учетных данных. Укажите этот флаг во всех случаях, если не указан CREDUI_FLAGS_DO_NOT_PERSIST. |
|
Учетные данные, введенные пользователем, считаются универсальными. |
|
Уведомите пользователя о недостаточных учетных данных, отображая всплывающую подсказку "Вход в систему не выполнен". |
|
Не разрешайте пользователю изменять указанное имя пользователя. |
|
Заполните поле со списком только паролем. Не разрешайте вводить имя пользователя. |
|
Не отображайте поле Сохранить проверка, но учетные данные сохраняются так, как если бы поле было отображено и выбрано. |
|
Заполните поле со списком только локальными администраторами. Windows XP Home Edition: Этот флаг отфильтрует общеизвестную учетную запись администратора. |
|
Заполните поле со списком только сертификатами и смарт-картами. Не разрешайте вводить имя пользователя. |
|
Заполните поле со списком только сертификатами или смарт-картами. Не разрешайте вводить имя пользователя. |
|
Этот флаг имеет смысл только при поиске соответствующих учетных данных для предварительного заполнения диалогового окна в случае сбоя проверки подлинности. Если этот флаг указан, учетные данные с подстановочными знаками не будут совпадать. Это не влияет на запись учетных данных. CredUI не создает учетные данные, содержащие подстановочные знаки. Все найденные были созданы явным образом пользователем или программным способом, как это происходит при подключении RAS. |
|
Если выбрано поле проверка, покажите поле Сохранить проверка и верните значение TRUE в выходном параметре pfSave, в противном случае — false. Флажок по умолчанию использует значение в pfSave . |
|
Учетные данные являются учетными данными runas. Параметр TargetName указывает имя выполняемой команды или программы. Он используется только в целях запроса. |
|
Убедитесь, что имя пользователя является допустимым. |
Возвращаемое значение
Возвращаемое значение является DWORD и может быть одним из следующих значений.
| Значение | Описание |
|---|---|
|
Пользователь выбрал отмену. Параметры pszUserName и pszPassword не изменились. |
|
Это состояние возвращается для любой из недопустимых конфигураций флагов. |
|
Либо pszTargetName имеет значение NULL, пустая строка или длиннее CREDUI_MAX_DOMAIN_LENGTH, либо pUiInfo не имеет значения NULL , а указанная структура CredUI_INFO не соответствует одному из следующих требований:
|
|
Нельзя использовать диспетчер учетных данных. Как правило, эта ошибка обрабатывается путем вызова CredUIPromptForCredentials и передачи флага CREDUI_FLAGS_DO_NOT_PERSIST. |
|
Пользователь выбрал ОК. Параметры 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.311.20.2.2) для отображения.
Windows XP: Это значение EKU не требуется для отображения сертификатов X509.
Если 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-имя дерева, к которому принадлежит компьютер
- Имя пакета, который собрал сведения
Учетные данные хранятся в диспетчере учетных данных на основе целевого имени. Каждое имя целевого объекта хранится как можно чаще, не сталкиваясь с учетными данными, которые уже хранятся в диспетчере учетных данных. Так как учетные данные хранятся по имени целевого объекта, конкретный пользователь может иметь только одну учетную запись для каждого целевого объекта, хранящегося в диспетчере учетных данных.
Примечание
Заголовок wincred.h определяет CredUIPromptForCredentials в качестве псевдонима, который автоматически выбирает версию ANSI или Юникод этой функции на основе определения константы препроцессора ЮНИКОД. Сочетание использования псевдонима, не зависящий от кодировки, с кодом, не зависящим от кодировки, может привести к несоответствиям, которые приводят к ошибкам компиляции или среды выполнения. Дополнительные сведения см. в разделе Соглашения для прототипов функций.
Требования
| Требование | Значение |
|---|---|
| Минимальная версия клиента | Windows XP [только классические приложения] |
| Минимальная версия сервера | Windows Server 2003 [только классические приложения] |
| Целевая платформа | Windows |
| Header | wincred.h |
| Библиотека | Credui.lib |
| DLL | Credui.dll |