Função CredUIPromptForWindowsCredentialsA (wincred.h)

A função CredUIPromptForWindowsCredentials cria e exibe uma caixa de diálogo configurável que permite que os usuários forneçam informações de credencial usando qualquer provedor de credenciais instalado no computador local.

Sintaxe

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

Um ponteiro para uma estrutura CREDUI_INFO que contém informações para personalizar a aparência da caixa de diálogo exibida por essa função.

Se o membro hwndParent da estrutura CREDUI_INFO não for NULL, essa função exibirá uma caixa de diálogo modal centralizada na janela pai.

Se o membro hwndParent da estrutura CREDUI_INFO for NULL, a função exibirá uma caixa de diálogo centralizada na tela.

Essa função ignora o membro hbmBanner da estrutura CREDUI_INFO .

[in] dwAuthError

Um código de erro do Windows, definido em Winerror.h, que é exibido na caixa de diálogo. Se as credenciais coletadas anteriormente não forem válidas, o chamador usará esse parâmetro para passar a mensagem de erro da API que coletou as credenciais (por exemplo, Winlogon) para essa função. A mensagem de erro correspondente é formatada e exibida na caixa de diálogo. Defina o valor desse parâmetro como zero para não exibir nenhuma mensagem de erro.

[in, out] pulAuthPackage

Na entrada, o valor desse parâmetro é usado para especificar o pacote de autenticação para o qual as credenciais no buffer pvInAuthBuffer são serializadas. Se o valor de pvInAuthBuffer for NULL e o sinalizador CREDUIWIN_AUTHPACKAGE_ONLY for definido no parâmetro dwFlags , somente os provedores de credenciais capazes de serializar credenciais para o pacote de autenticação especificado deverão ser enumerados.

Para obter o valor apropriado a ser usado para esse parâmetro na entrada, chame a função LsaLookupAuthenticationPackage e use o valor do parâmetro AuthenticationPackage dessa função.

Na saída, esse parâmetro especifica o pacote de autenticação para o qual as credenciais no buffer ppvOutAuthBuffer são serializadas.

[in, optional] pvInAuthBuffer

Um ponteiro para um BLOB de credencial usado para preencher os campos de credencial na caixa de diálogo. Defina o valor desse parâmetro como NULL para deixar os campos de credencial vazios.

[in] ulInAuthBufferSize

O tamanho, em bytes, do buffer pvInAuthBuffer .

[out] ppvOutAuthBuffer

O endereço de um ponteiro que, na saída, especifica o BLOB de credencial. Para credenciais Kerberos, NTLM ou Negotiate, chame a função CredUnPackAuthenticationBuffer para converter esse BLOB em representações de cadeia de caracteres das credenciais.

Quando terminar de usar o BLOB de credenciais, limpe-o da memória chamando a função SecureZeroMemory e libere-a chamando a função CoTaskMemFree .

[out] pulOutAuthBufferSize

O tamanho, em bytes, do buffer ppvOutAuthBuffer .

[in, out, optional] pfSave

Um ponteiro para um valor booliano que, na entrada, especifica se a caixa Salvar marcar está selecionada na caixa de diálogo exibida por essa função. Na saída, o valor desse parâmetro especifica se a caixa Salvar marcar foi selecionada quando o usuário clica no botão Enviar na caixa de diálogo. Defina esse parâmetro como NULL para ignorar a caixa Salvar marcar.

Esse parâmetro será ignorado se o sinalizador CREDUIWIN_CHECKBOX não estiver definido no parâmetro dwFlags .

[in] dwFlags

Um valor que especifica o comportamento dessa função. Esse valor pode ser uma combinação or bit a bit de um ou mais dos valores a seguir.

Valor Significado
CREDUIWIN_GENERIC
0x1
O chamador está solicitando que o provedor de credenciais retorne o nome de usuário e a senha em texto sem formatação.

Esse valor não pode ser combinado com SECURE_PROMPT.

CREDUIWIN_CHECKBOX
0x2
A caixa Salvar marcar é exibida na caixa de diálogo.
CREDUIWIN_AUTHPACKAGE_ONLY
0x10
Somente os provedores de credenciais que dão suporte ao pacote de autenticação especificado pelo parâmetro pulAuthPackage devem ser enumerados.

Esse valor não pode ser combinado com CREDUIWIN_IN_CRED_ONLY.

CREDUIWIN_IN_CRED_ONLY
0x20
Somente as credenciais especificadas pelo parâmetro pvInAuthBuffer para o pacote de autenticação especificado pelo parâmetro pulAuthPackage devem ser enumeradas.

Se esse sinalizador estiver definido e o parâmetro pvInAuthBuffer for NULL, a função falhará.

Esse valor não pode ser combinado com CREDUIWIN_AUTHPACKAGE_ONLY.

CREDUIWIN_ENUMERATE_ADMINS
0x100
Os provedores de credenciais devem enumerar somente administradores. Esse valor destina-se apenas para fins de Controle de Conta de Usuário (UAC). Recomendamos que os chamadores externos não definam esse sinalizador.
CREDUIWIN_ENUMERATE_CURRENT_USER
0x200
Somente as credenciais de entrada para o pacote de autenticação especificado pelo parâmetro pulAuthPackage devem ser enumeradas.
CREDUIWIN_SECURE_PROMPT
0x1000
A caixa de diálogo de credencial deve ser exibida na área de trabalho segura. Esse valor não pode ser combinado com CREDUIWIN_GENERIC.

Windows Vista: Esse valor tem suporte a partir do Windows Vista com SP1.

CREDUIWIN_PREPROMPTING
0x2000
A caixa de diálogo de credencial é invocada pela função SspiPromptForCredentials e o cliente é solicitado antes de um handshake anterior. Se SSPIPFC_NO_CHECKBOX for passado no parâmetro pvInAuthBuffer, o provedor de credenciais não deverá exibir a caixa marcar.

Windows Vista: Esse valor tem suporte a partir do Windows Vista com SP1.

0x40000
O provedor de credenciais não empacotará o nome da autoridade do AAD. Isso só é aplicado a Azure AD dispositivos ingressados.

Windows 10, versão 1607: esse valor tem suporte a partir do Windows 10, versão 1607.

CREDUIWIN_PACK_32_WOW
0x10000000
O provedor de credenciais deve alinhar o BLOB de credencial apontado pelo parâmetro ppvOutAuthBuffer a um limite de 32 bits, mesmo que o provedor esteja em execução em um sistema de 64 bits.
0x80000000
Windows Hello credenciais serão empacotadas em um buffer de autenticação de cartão inteligente. Isso só se aplica aos provedores de credenciais de rosto, impressão digital e PIN.

Windows 10, versão 1809: há suporte para esse valor começando com Windows 10, versão 1809.

Retornar valor

Se a função for bem-sucedida, a função retornará ERROR_SUCCESS. Se a função for cancelada pelo usuário, ela retornará ERROR_CANCELLED. Qualquer outro valor retornado indica que a função não foi carregada.

Comentários

Essa função não salva credenciais.

Aplicativos que usam SSPI para autenticar usuários não devem chamar essa função. Em vez disso, chame SspiPromptForCredentials.

Observação

O cabeçalho wincred.h define CredUIPromptForWindowsCredentials como um alias que seleciona automaticamente a versão ANSI ou Unicode dessa função com base na definição da constante de pré-processador UNICODE. Misturar o uso do alias neutro de codificação com código que não seja neutro em codificação pode levar a incompatibilidades que resultam em erros de compilação ou de runtime. Para obter mais informações, consulte Convenções para protótipos de função.

Requisitos

Requisito Valor
Cliente mínimo com suporte Windows Vista [somente aplicativos da área de trabalho]
Servidor mínimo com suporte Windows Server 2008 [somente aplicativos da área de trabalho]
Plataforma de Destino Windows
Cabeçalho wincred.h
Biblioteca Credui.lib
DLL Credui.dll