Функция CredUIPromptForWindowsCredentialsW (wincred.h)

Статья
11/20/2024

Функция 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, содержащую сведения о настройке внешнего вида диалогового окна, отображаемого этой функцией.

Если элемент hwndParent структуры CREDUI_INFO не NULL, эта функция отображает модальное диалоговое окно в центре родительского окна.

Если элемент hwndParent структуры CREDUI_INFONULL, функция отображает диалоговое окно в центре экрана.

Эта функция игнорирует элемент hbmBanner структуры CREDUI_INFO.

[in] dwAuthError

Код ошибки Windows, определенный в Winerror.h, который отображается в диалоговом окне. Если учетные данные, собранные ранее, недопустимы, вызывающий параметр использует этот параметр для передачи сообщения об ошибке из 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-объект в строковые представления учетных данных.

Завершив использование БОЛЬШОго двоичного объекта учетных данных, очистите его от памяти, вызвав функцию SecureZeroMemory и освободив ее, вызвав функцию CoTaskMemFree.

[out] pulOutAuthBufferSize

Размер в байтах буфера ppvOutAuthBuffer.

[in, out, optional] pfSave

Указатель на логическое значение, указывающее, установлен ли флажок Сохранить в диалоговом окне, отображаемом этой функцией. В выходных данных значение этого параметра указывает, был ли установлен флажок "Сохранить", когда пользователь нажимает кнопку "Отправить" в диалоговом окне. Установите для этого параметра значение NULL, чтобы игнорировать флажок "Сохранить ".

Этот параметр игнорируется, если флаг CREDUIWIN_CHECKBOX не задан в параметре dwFlags.

[in] dwFlags

Значение, указывающее поведение этой функции. Это значение может быть битовойИЛИ сочетание одного или нескольких из следующих значений.

Ценность	Значение
CREDUIWIN_GENERIC 0x1	Вызывающий объект запрашивает, чтобы поставщик учетных данных возвращал имя пользователя и пароль в виде обычного текста. Это значение нельзя объединить с SECURE_PROMPT.
CREDUIWIN_CHECKBOX 0x2	Флажок "Сохранить" отображается в диалоговом окне.
CREDUIWIN_AUTHPACKAGE_ONLY 0x10	Необходимо перечислить только поставщики учетных данных, поддерживающие пакет проверки подлинности, указанный параметром pulAuthPackage. Это значение нельзя объединить с CREDUIWIN_IN_CRED_ONLY.
CREDUIWIN_IN_CRED_ONLY 0x20	Необходимо перечислить только учетные данные, указанные параметром pvInAuthBuffer для пакета проверки подлинности, указанного параметром pulAuthPackage. Если этот флаг задан, а параметр 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 с пакетом обновления 1 (SP1).
CREDUIWIN_PREPROMPTING 0x2000	Диалоговое окно учетных данных вызывается функцией SspiPromptForCredentials, и клиенту будет предложено перед подтверждением. Если SSPIPFC_NO_CHECKBOX передается в параметре pvInAuthBuffer, то поставщик учетных данных не должен отображать флажок. Windows Vista: Это значение поддерживается начиная с Windows Vista с пакетом обновления 1 (SP1).
0x40000	Поставщик учетных данных не упаковывает имя центра AAD. Это применяется только к устройствам, присоединенным к Azure AD. Windows 10 версии 1607: Это значение поддерживается начиная с Windows 10 версии 1607.
CREDUIWIN_PACK_32_WOW 0x10000000	Поставщик учетных данных должен выровнять учетные данные BLOB, на которые указывает параметр ppvOutAuthBuffer на 32-разрядную границу, даже если поставщик работает в 64-разрядной системе.
0x80000000	Учетные данные Windows Hello будут упакованы в буфер проверки подлинности смарт-карт. Это относится только к поставщикам учетных данных для лиц, отпечатков пальцев и ПИН-кода. Windows 10 версии 1809: это значение поддерживается начиная с Windows 10 версии 1809.

Возвращаемое значение

Если функция выполнена успешно, функция возвращает ERROR_SUCCESS. Если функция отменена пользователем, она возвращает ERROR_CANCELLED. Любое другое возвращаемое значение указывает, что функция не удалось загрузить.

Замечания

Эта функция не сохраняет учетные данные.

Приложения, использующие SSPI для проверки подлинности пользователей, не должны вызывать эту функцию. Вместо этого вызовите SspiPromptForCredentials.

Заметка

Заголовок wincred.h определяет CredUIPromptForWindowsCredentials в качестве псевдонима, который автоматически выбирает версию ANSI или Юникод этой функции на основе определения константы препроцессора ЮНИКОДа. Сочетание использования псевдонима, нейтрального для кодирования, с кодом, не зависящим от кодирования, может привести к несоответствиям, которые приводят к ошибкам компиляции или среды выполнения. Дополнительные сведения см. в соглашениях о прототипах функций.

Требования

Требование	Ценность
минимальные поддерживаемые клиентские	Windows Vista [только классические приложения]
минимальный поддерживаемый сервер	Windows Server 2008 [только классические приложения]
целевая платформа	Виндоус
заголовка	wincred.h
библиотеки	Credui.lib
DLL	Credui.dll

Поделиться через