Search
Module:
Directory

   Desktop Functions:

   Smart Device Functions:


Show Recent Changes
Subscribe (RSS)
Misc. Pages
Comments
FAQ
Helpful Tools
Playground
Suggested Reading
Website TODO List
Download Visual Studio Add-In

CredUIPromptForCredentials (credui)
 
.
Summary
The CredUIPromptForCredentials function creates and displays a configurable dialog box that accepts credentials information from a user. Applications that target Windows Vista or Windows Server 2008 should call CredUIPromptForWindowsCredentials instead of this function.

C# Signature:

    [DllImport("credui")]
    private static extern CredUIReturnCodes CredUIPromptForCredentials(ref CREDUI_INFO creditUR,
      string targetName,
      IntPtr reserved1,
      int iError,
      StringBuilder userName,
      int maxUserName,
      StringBuilder password,
      int maxPassword,
      [MarshalAs(UnmanagedType.Bool)] ref bool pfSave,
      CREDUI_FLAGS flags);

VB Signature:

    ''' <summary>
    ''' The CredUIPromptForCredentials function creates and displays a configurable dialog box that accepts credentials information from a user.
    ''' Applications that target Windows Vista or Windows Server 2008 should call CredUIPromptForWindowsCredentials instead of this function.
    ''' See http://msdn.microsoft.com/en-us/library/aa375177(v=VS.85).aspx
    ''' </summary>
    ''' <param name="pUiInfo">The CREDUI_INFO structure with customises the appearance of the dialog.</param>
    ''' <param name="pszTargetName">The target for the credentials, typically a server name.</param>
    ''' <param name="Reserved">RESERVER - must be NULL.</param>
    ''' <param name="dwAuthError">If prompting after an error, pass the Windows Error code so the appropriate error message is included in the dialog.</param>
    ''' <param name="pszUserName">User Name variable which will populated from the buffer.</param>
    ''' <param name="ulUserNameMaxChars">The maximum length of the User Name variable.</param>
    ''' <param name="pszPassword">Password variable which will populated from the buffer.</param>
    ''' <param name="ulPasswordMaxChars">The maximum length of the Password variable.</param>
    ''' <param name="pfSave">If set to <c>True</c> the check the "Save" checkbox on the dialog - only displayed if appropriate dwFlags passed (see remarks below).</param>
    ''' <param name="dwFlags">Flags to control the dialog functionality (see <see cref="CredUIWinFlags" />.</param>
    ''' <remarks>
    ''' If the CREDUI_FLAGS_PERSIST flag is specified, the Save check box is not displayed, but is considered to be selected.
    ''' If the CREDUI_FLAGS_DO_NOT_PERSIST flag is specified and CREDUI_FLAGS_SHOW_SAVE_CHECK_BOX is not specified, the Save check box is not displayed,
    ''' but is considered to be cleared. An application that needs to use CredUI to prompt the user for credentials, but does not need the credential
    ''' management services provided by the credential manager, can use pfSave to receive the state of the Save check box after the user closes the
    ''' dialog box. To do this, the caller must specify CREDUI_FLAGS_DO_NOT_PERSIST and CREDUI_FLAGS_SHOW_SAVE_CHECK_BOX in dwFlags. When
    ''' CREDUI_FLAGS_DO_NOT_PERSIST and CREDUI_FLAGS_SHOW_SAVE_CHECK_BOX are set, the application is responsible for examining *pfSave after the
    ''' function returns, and if *pfSave is TRUE, then the application must take the appropriate action to save the user credentials within the
    ''' resources of the application.
    ''' </remarks>
    ''' <returns>Zero on success, otherwise a non-zero error code.</returns>
    <DllImport("CREDUI.dll", CharSet:=CharSet.Unicode)> <CLSCompliant(False)> _
    Public Shared Function CredUIPromptForCredentials(ByRef pUiInfo As CREDUI_INFO, _
                            ByVal pszTargetName As String, _
                            ByVal Reserved As IntPtr, _
                            ByVal dwAuthError As UInt32, _
                            ByVal pszUserName As StringBuilder, _
                            ByVal ulUserNameMaxChars As UInt32, _
                            ByVal pszPassword As StringBuilder, _
                            ByVal ulPasswordMaxChars As UInt32, _
                            <MarshalAs(UnmanagedType.Bool)> ByRef pfSave As Boolean, _
                            ByVal dwFlags As CREDUI_FLAGS) As CredUIReturnCodes
    End Function

User-Defined Types:

    [Flags]
    enum CREDUI_FLAGS
    {
    INCORRECT_PASSWORD = 0x1,
    DO_NOT_PERSIST = 0x2,
    REQUEST_ADMINISTRATOR = 0x4,
    EXCLUDE_CERTIFICATES = 0x8,
    REQUIRE_CERTIFICATE = 0x10,
    SHOW_SAVE_CHECK_BOX = 0x40,
    ALWAYS_SHOW_UI = 0x80,
    REQUIRE_SMARTCARD = 0x100,
    PASSWORD_ONLY_OK = 0x200,
    VALIDATE_USERNAME = 0x400,
    COMPLETE_USERNAME = 0x800,
    PERSIST = 0x1000,
    SERVER_CREDENTIAL = 0x4000,
    EXPECT_CONFIRMATION = 0x20000,
    GENERIC_CREDENTIALS = 0x40000,
    USERNAME_TARGET_CREDENTIALS = 0x80000,
    KEEP_USERNAME = 0x100000,
    }

    public enum CredUIReturnCodes
    {
    NO_ERROR = 0,
    ERROR_CANCELLED = 1223,
    ERROR_NO_SUCH_LOGON_SESSION = 1312,
    ERROR_NOT_FOUND = 1168,
    ERROR_INVALID_ACCOUNT_NAME = 1315,
    ERROR_INSUFFICIENT_BUFFER = 122,
    ERROR_INVALID_PARAMETER = 87,
    ERROR_INVALID_FLAGS = 1004,
    }

VB Syntax:

    <Flags()> _
    Public Enum CREDUI_FLAGS
    INCORRECT_PASSWORD = &H1
    DO_NOT_PERSIST = &H2
    REQUEST_ADMINISTRATOR = &H4
    EXCLUDE_CERTIFICATES = &H8
    REQUIRE_CERTIFICATE = &H10
    SHOW_SAVE_CHECK_BOX = &H40
    ALWAYS_SHOW_UI = &H80
    REQUIRE_SMARTCARD = &H100
    PASSWORD_ONLY_OK = &H200
    VALIDATE_USERNAME = &H400
    COMPLETE_USERNAME = &H800
    PERSIST = &H1000
    SERVER_CREDENTIAL = &H4000
    EXPECT_CONFIRMATION = &H20000
    GENERIC_CREDENTIALS = &H40000
    USERNAME_TARGET_CREDENTIALS = &H80000
    KEEP_USERNAME = &H100000
    End Enum

    Public Enum CredUIReturnCodes As Integer
    NO_ERROR = 0
    ERROR_CANCELLED = 1223
    ERROR_NO_SUCH_LOGON_SESSION = 1312
    ERROR_NOT_FOUND = 1168
    ERROR_INVALID_ACCOUNT_NAME = 1315
    ERROR_INSUFFICIENT_BUFFER = 122
    ERROR_INVALID_PARAMETER = 87
    ERROR_INVALID_FLAGS = 1004
    End Enum

Also see CREDUI_INFO.

Alternative Managed API:

Do you know one? Please contribute it!

Notes:

None.

Tips & Tricks:

This only allows management of the credential provider dialog and nothing else. You also have to use the CredUnPackAuthenticationBuffer to return the userid and password obtained by CredUIPromptForWindowsCredentials to do any useful work. A common thing would be to use the credentials returned from CredUnPackAuthenticationBuffer and validate those using PrincipalContext to either validate or invalidate user logons.

Sample Code:

    /// <summary>
    /// Prompts for password.
    /// </summary>
    /// <param name="user">The user.</param>
    /// <param name="password">The password.</param>
    /// <returns>True if no errors.</returns>
    internal static bool PromptForPassword(out string user, out string password)
    {
    // Setup the flags and variables
    StringBuilder userPassword = new StringBuilder(), userID = new StringBuilder();
    CREDUI_INFO credUI = new CREDUI_INFO();
    credUI.cbSize = Marshal.SizeOf(credUI);
    bool save = false;
    CREDUI_FLAGS flags = CREDUI_FLAGS.ALWAYS_SHOW_UI | CREDUI_FLAGS.GENERIC_CREDENTIALS;

    // Prompt the user
    CredUIReturnCodes returnCode = CredUIPromptForCredentials(ref credUI, Application.ProductName, IntPtr.Zero, 0, userID, 100, userPassword, 100, ref save, flags);

    user = userID.ToString();
    password = userPassword.ToString();

    return (returnCode == CredUIReturnCodes.NO_ERROR);
    }

Documentation

Please edit this page!

Do you have...

  • helpful tips or sample code to share for using this API in managed code?
  • corrections to the existing content?
  • variations of the signature you want to share?
  • additional languages you want to include?

Select "Edit This Page" on the right hand toolbar and edit it! Or add new pages containing supporting types needed for this API (structures, delegates, and more).

 
Access PInvoke.net directly from VS:
Terms of Use
Find References
Show Printable Version
Revisions