CredUIPromptForWindowsCredentialsA function (wincred.h)

The CredUIPromptForWindowsCredentials function creates and displays a configurable dialog box that allows users to supply credential information by using any credential provider installed on the local computer.

Syntax

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

Parameters

[in, optional] pUiInfo

A pointer to a CREDUI_INFO structure that contains information for customizing the appearance of the dialog box that this function displays.

If the hwndParent member of the CREDUI_INFO structure is not NULL, this function displays a modal dialog box centered on the parent window.

If the hwndParent member of the CREDUI_INFO structure is NULL, the function displays a dialog box centered on the screen.

This function ignores the hbmBanner member of the CREDUI_INFO structure.

[in] dwAuthError

A Windows error code, defined in Winerror.h, that is displayed in the dialog box. If credentials previously collected were not valid, the caller uses this parameter to pass the error message from the API that collected the credentials (for example, Winlogon) to this function. The corresponding error message is formatted and displayed in the dialog box. Set the value of this parameter to zero to display no error message.

[in, out] pulAuthPackage

On input, the value of this parameter is used to specify the authentication package for which the credentials in the pvInAuthBuffer buffer are serialized. If the value of pvInAuthBuffer is NULL and the CREDUIWIN_AUTHPACKAGE_ONLY flag is set in the dwFlags parameter, only credential providers capable of serializing credentials for the specified authentication package are to be enumerated.

To get the appropriate value to use for this parameter on input, call the LsaLookupAuthenticationPackage function and use the value of the AuthenticationPackage parameter of that function.

On output, this parameter specifies the authentication package for which the credentials in the ppvOutAuthBuffer buffer are serialized.

[in, optional] pvInAuthBuffer

A pointer to a credential BLOB that is used to populate the credential fields in the dialog box. Set the value of this parameter to NULL to leave the credential fields empty.

[in] ulInAuthBufferSize

The size, in bytes, of the pvInAuthBuffer buffer.

[out] ppvOutAuthBuffer

The address of a pointer that, on output, specifies the credential BLOB. For Kerberos, NTLM, or Negotiate credentials, call the CredUnPackAuthenticationBuffer function to convert this BLOB to string representations of the credentials.

When you have finished using the credential BLOB, clear it from memory by calling the SecureZeroMemory function, and free it by calling the CoTaskMemFree function.

[out] pulOutAuthBufferSize

The size, in bytes, of the ppvOutAuthBuffer buffer.

[in, out, optional] pfSave

A pointer to a Boolean value that, on input, specifies whether the Save check box is selected in the dialog box that this function displays. On output, the value of this parameter specifies whether the Save check box was selected when the user clicks the Submit button in the dialog box. Set this parameter to NULL to ignore the Save check box.

This parameter is ignored if the CREDUIWIN_CHECKBOX flag is not set in the dwFlags parameter.

[in] dwFlags

A value that specifies behavior for this function. This value can be a bitwise-OR combination of one or more of the following values.

Return value

If the function succeeds, the function returns ERROR_SUCCESS. If the function is canceled by the user, it returns ERROR_CANCELLED. Any other return value indicates that the function failed to load.

Remarks

This function does not save credentials.

Applications that use SSPI to authenticate users should not call this function. Instead, call SspiPromptForCredentials.

Requirements