Compartir a través de

Función CredUIPromptForWindowsCredentialsA (wincred.h)

  • Artículo

La función CredUIPromptForWindowsCredentials crea y muestra un cuadro de diálogo configurable que permite a los usuarios proporcionar información de credenciales mediante cualquier proveedor de credenciales instalado en el equipo local.

Sintaxis

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
);

Parámetros

[in, optional] pUiInfo

Puntero a una estructura CREDUI_INFO que contiene información para personalizar la apariencia del cuadro de diálogo que muestra esta función.

Si el miembro hwndParent de la estructura CREDUI_INFO no es NULL, esta función muestra un cuadro de diálogo modal centrado en la ventana primaria.

Si el miembro hwndParent de la estructura CREDUI_INFO es NULL, la función muestra un cuadro de diálogo centrado en la pantalla.

Esta función omite el miembro hbmBanner de la estructura CREDUI_INFO.

[in] dwAuthError

Código de error de Windows, definido en Winerror.h, que se muestra en el cuadro de diálogo. Si las credenciales recopiladas anteriormente no eran válidas, el autor de la llamada usa este parámetro para pasar el mensaje de error de la API que recopiló las credenciales (por ejemplo, Winlogon) a esta función. El mensaje de error correspondiente tiene el formato y se muestra en el cuadro de diálogo. Establezca el valor de este parámetro en cero para mostrar ningún mensaje de error.

[in, out] pulAuthPackage

En la entrada, el valor de este parámetro se usa para especificar el paquete de autenticación para el que se serializan las credenciales del pvInAuthBuffer búfer. Si el valor de pvInAuthBuffer es NULL y la marca de CREDUIWIN_AUTHPACKAGE_ONLY se establece en el parámetro dwFlags, solo se enumerarán los proveedores de credenciales capaces de serializar credenciales para el paquete de autenticación especificado.

Para obtener el valor adecuado que se va a usar para este parámetro en la entrada, llame al función LsaLookupAuthenticationPackage y use el valor del parámetro AuthenticationPackage de esa función.

En la salida, este parámetro especifica el paquete de autenticación para el que se serializan las credenciales de la ppvOutAuthBuffer búfer.

[in, optional] pvInAuthBuffer

Puntero a un BLOB de credenciales que se usa para rellenar los campos de credenciales en el cuadro de diálogo. Establezca el valor de este parámetro en NULL para dejar vacíos los campos de credenciales.

[in] ulInAuthBufferSize

Tamaño, en bytes, del búfer de pvInAuthBuffer.

[out] ppvOutAuthBuffer

La dirección de un puntero que, en la salida, especifica la credencial BLOB. Para las credenciales Kerberos, NTLM o Negotiate, llame a la función CredUnPackAuthenticationBuffer para convertir este BLOB en representaciones de cadena de las credenciales.

Cuando haya terminado de usar el BLOB de credenciales, desactive la memoria llamando a la función de SecureZeroMemory y liberándola llamando a la función CoTaskMemFree.

[out] pulOutAuthBufferSize

Tamaño, en bytes, del búfer de ppvOutAuthBuffer.

[in, out, optional] pfSave

Puntero a un valor booleano que, en la entrada, especifica si la casilla Guardar está activada en el cuadro de diálogo que muestra esta función. En la salida, el valor de este parámetro especifica si la casilla Guardar se seleccionó cuando el usuario hace clic en el botón Enviar en el cuadro de diálogo. Establezca este parámetro en NULL para omitir la casilla Guardar .

Este parámetro se omite si la marca CREDUIWIN_CHECKBOX no está establecida en el parámetro dwFlags.

[in] dwFlags

Valor que especifica el comportamiento de esta función. Este valor puede ser una combinación deO bit a bit de uno o varios de los valores siguientes.

Valor Significado
CREDUIWIN_GENERIC
0x1
 El autor de la llamada solicita que el proveedor de credenciales devuelva el nombre de usuario y la contraseña en texto sin formato.

Este valor no se puede combinar con SECURE_PROMPT.
CREDUIWIN_CHECKBOX
0x2
 La casilla Guardar se muestra en el cuadro de diálogo.
CREDUIWIN_AUTHPACKAGE_ONLY
0x10
 Solo se deben enumerar los proveedores de credenciales que admiten el paquete de autenticación especificado por el parámetro pulAuthPackage.

Este valor no se puede combinar con CREDUIWIN_IN_CRED_ONLY.
CREDUIWIN_IN_CRED_ONLY
0x20
 Solo se deben enumerar las credenciales especificadas por el parámetro pvInAuthBuffer para el paquete de autenticación especificado por el parámetro pulAuthPackage.

Si se establece esta marca y el parámetro pvInAuthBuffer es NULL, se produce un error en la función.

Este valor no se puede combinar con CREDUIWIN_AUTHPACKAGE_ONLY.
CREDUIWIN_ENUMERATE_ADMINS
0x100
 Los proveedores de credenciales deben enumerar solo los administradores. Este valor está pensado solo para fines de control de cuentas de usuario (UAC). Se recomienda que los autores de llamadas externos no establezcan esta marca.
CREDUIWIN_ENUMERATE_CURRENT_USER
0x200
 Solo se deben enumerar las credenciales entrantes del paquete de autenticación especificado por el parámetro pulAuthPackage.
CREDUIWIN_SECURE_PROMPT
0x1000
 El cuadro de diálogo de credenciales debe mostrarse en el escritorio seguro. Este valor no se puede combinar con CREDUIWIN_GENERIC.

Windows Vista: Este valor se admite a partir de Windows Vista con SP1.
CREDUIWIN_PREPROMPTING
0x2000
 El cuadro de diálogo de credenciales se invoca mediante la función SspiPromptForCredentials y se solicita al cliente antes de un protocolo de enlace anterior. Si SSPIPFC_NO_CHECKBOX se pasa en el parámetro pvInAuthBuffer, el proveedor de credenciales no debe mostrar la casilla.

Windows Vista: Este valor se admite a partir de Windows Vista con SP1.
0x40000
 El proveedor de credenciales no empaquetará el nombre de la entidad de AAD. Esto solo se aplica a dispositivos unidos a Azure AD.

Windows 10, versión 1607: Este valor es compatible a partir de Windows 10, versión 1607.
CREDUIWIN_PACK_32_WOW
0x10000000
 El proveedor de credenciales debe alinear el BLOB de credenciales al que apunta el parámetro ppvOutAuthBuffer a un límite de 32 bits, incluso si el proveedor se ejecuta en un sistema de 64 bits.
0x80000000
 Las credenciales de Windows Hello se empaquetarán en un búfer de autenticación de tarjeta inteligente. Esto solo se aplica a los proveedores de credenciales face, fingerprint y PIN.

Windows 10, versión 1809: Este valor es compatible a partir de Windows 10, versión 1809.

Valor devuelto

Si la función se ejecuta correctamente, la función devuelve ERROR_SUCCESS. Si el usuario cancela la función, devuelve ERROR_CANCELLED. Cualquier otro valor devuelto indica que la función no se pudo cargar.

Observaciones

Esta función no guarda las credenciales.

Las aplicaciones que usan SSPI para autenticar a los usuarios no deben llamar a esta función. En su lugar, llame a SspiPromptForCredentials.

Nota

El encabezado wincred.h define CredUIPromptForWindowsCredentials como alias que selecciona automáticamente la versión ANSI o Unicode de esta función en función de la definición de la constante de preprocesador UNICODE. La combinación del uso del alias neutral de codificación con código que no es neutral de codificación puede dar lugar a errores de coincidencia que dan lugar a errores de compilación o tiempo de ejecución. Para obtener más información, vea Conventions for Function Prototypes.

Requisitos

Requisito Valor
cliente mínimo admitido Windows Vista [solo aplicaciones de escritorio]
servidor mínimo admitido Windows Server 2008 [solo aplicaciones de escritorio]
de la plataforma de destino de Windows
encabezado de wincred.h
biblioteca de Credui.lib
DLL de Credui.dll