Compartilhar via

Função CredUIPromptForWindowsCredentialsA (wincred.h)

  • Artigo

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 hwndParent membro da estrutura CREDUI_INFO não estiver NULL, essa função exibirá uma caixa de diálogo modal centralizada na janela pai.

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

Essa função ignora o hbmBanner membro 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 para 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 credencial, desmarque-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 de seleção Salvar está marcada na caixa de diálogo exibida por essa função. Na saída, o valor desse parâmetro especifica se a caixa de seleção Salvar foi selecionada quando o usuário clica no botão enviar na caixa de diálogo. Defina esse parâmetro para NULL para ignorar a caixa de seleção salvar .

Esse parâmetro será ignorado se o sinalizador de 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 orOR 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 de seleção Salvar é exibida na caixa de diálogo.
CREDUIWIN_AUTHPACKAGE_ONLY
0x10
 Somente 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 os administradores. Esse valor destina-se apenas a fins de UAC (Controle de Conta de Usuário). 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 de seleção.

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 dispositivos ingressados no Azure AD.

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 credenciais 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
 As credenciais do Windows Hello serão empacotadas em um buffer de autenticação de cartão inteligente. Isso só se aplica aos provedores de credenciais de detecção facial, impressão digital e PIN.

Windows 10, versão 1809: Esse valor tem suporte a partir do Windows 10, versão 1809.

Valor de retorno

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 falhou ao carregar.

Observações

Essa função não salva credenciais.

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

Nota

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 do pré-processador UNICODE. A combinação do uso do alias neutro de codificação com código que não é neutro em codificação pode levar a incompatibilidades que resultam em erros de compilação ou de runtime. Para obter mais informações, consulte Conventions for Function Prototypes.

Requisitos

Requisito Valor
de cliente com suporte mínimo Windows Vista [somente aplicativos da área de trabalho]
servidor com suporte mínimo Windows Server 2008 [somente aplicativos da área de trabalho]
da Plataforma de Destino Windows
cabeçalho wincred.h
biblioteca Credui.lib
de DLL Credui.dll