pinvoke.net: Edit: credui.CredUIPromptForWindowsCredentials

@msdn=http://search.microsoft.com/search/results.aspx?qu=$$$
@pinvoke=http://pinvoke.net/$$$.htm

Summary: 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.

!!!!C# Signature:
    [DllImport("credui.dll", CharSet = CharSet.Unicode)]
    private static extern uint CredUIPromptForWindowsCredentials(ref CREDUI_INFO notUsedHere,
          int authError,
          ref uint authPackage,
          IntPtr InAuthBuffer,
          uint InAuthBufferSize,
          out IntPtr refOutAuthBuffer,
          out uint refOutAuthBufferSize,
          ref bool fSave,
          PromptForWindowsCredentialsFlags flags);

!!!!VB Signature:

''' <summary>
    ''' 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.
    ''' NOTE: Windows Vista or Server 2008 or later ONLY. For older Windows versions use CredUIPromptForCredentials().
    ''' See http://msdn.microsoft.com/en-us/library/aa375178(v=VS.85).aspx
    ''' </summary>
    ''' <param name="pUiInfo">The CREDUI_INFO structure with customises the appearance of the dialog.</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="pulAuthPackage">Determine the authentication package to use. Pass zero to use default. Returns with identifier for package used.</param>
    ''' <param name="pvInAuthBuffer">An authentication buffer with which to default prompted values (see <see cref="CredPackAuthenticationBuffer" />).</param>
    ''' <param name="ulInAuthBufferSize">Size of the input authentication buffer.</param>
    ''' <param name="ppvOutAuthBuffer">An authentication buffer which will be populated with entered credentials (see <see cref="CredUnPackAuthenticationBuffer" />).</param>
    ''' <param name="pulOutAuthBufferSize">Size of the output authentication buffer.</param>
    ''' <param name="pfSave">If set to <c>True</c> the check the "Save" checkbox on the dialog - only displayed if CREDUIWIN_CHECKBOX is passed in dwFlags.</param>
    ''' <param name="dwFlags">Flags to control the dialog functionality (see <see cref="CredUIWinFlags" />.</param>
    ''' <returns>A <see cref="CredUIReturnCodes" /> value.</returns>
    <System.Runtime.InteropServices.DllImport("credui.dll", EntryPoint:="CredUIPromptForWindowsCredentials", CharSet:=CharSet.Unicode)> <CLSCompliant(False)> _
    Public Shared Function CredUIPromptForWindowsCredentials(ByRef pUiInfo As CREDUI_INFO, _
                                                            ByVal dwAuthError As UInt32, _
                                                            ByRef pulAuthPackage As UInt32, _
                                                            ByVal pvInAuthBuffer As IntPtr, _
                                                            ByVal ulInAuthBufferSize As UInt32, _
                                                            ByRef ppvOutAuthBuffer As IntPtr, _
                                                            ByRef pulOutAuthBufferSize As UInt32, _
                                                            <MarshalAs(UnmanagedType.Bool)> ByRef pfSave As Boolean, _
                                                            ByVal dwFlags As CredUIWinFlags) As CredUIReturnCodes
    End Function

!!!!User-Defined Types:

C# Syntax:

[StructLayout(LayoutKind.Sequential, CharSet = CharSet.Unicode)]
    private struct CREDUI_INFO
    {
          public int cbSize;
          public IntPtr hwndParent;
          public string pszMessageText;
          public string pszCaptionText;
          public IntPtr hbmBanner;
    }

[Flags]
    private enum PromptForWindowsCredentialsFlags
    {
          /// <summary>
          /// The caller is requesting that the credential provider return the user name and password in plain text.
          /// This value cannot be combined with SECURE_PROMPT.
          /// </summary>
          CREDUIWIN_GENERIC = 0x1,
          /// <summary>
          /// The Save check box is displayed in the dialog box.
          /// </summary>
          CREDUIWIN_CHECKBOX = 0x2,
          /// <summary>
          /// Only credential providers that support the authentication package specified by the authPackage parameter should be enumerated.
          /// This value cannot be combined with CREDUIWIN_IN_CRED_ONLY.
          /// </summary>
          CREDUIWIN_AUTHPACKAGE_ONLY = 0x10,
          /// <summary>
          /// Only the credentials specified by the InAuthBuffer parameter for the authentication package specified by the authPackage parameter should be enumerated.
          /// If this flag is set, and the InAuthBuffer parameter is NULL, the function fails.
          /// This value cannot be combined with CREDUIWIN_AUTHPACKAGE_ONLY.
          /// </summary>
          CREDUIWIN_IN_CRED_ONLY = 0x20,
          /// <summary>
          /// Credential providers should enumerate only administrators. This value is intended for User Account Control (UAC) purposes only. We recommend that external callers not set this flag.
          /// </summary>
          CREDUIWIN_ENUMERATE_ADMINS = 0x100,
          /// <summary>
          /// Only the incoming credentials for the authentication package specified by the authPackage parameter should be enumerated.
          /// </summary>
          CREDUIWIN_ENUMERATE_CURRENT_USER = 0x200,
          /// <summary>
          /// The credential dialog box should be displayed on the secure desktop. This value cannot be combined with CREDUIWIN_GENERIC.
          /// Windows Vista: This value is not supported until Windows Vista with SP1.
          /// </summary>
          CREDUIWIN_SECURE_PROMPT = 0x1000,
          /// <summary>
          /// The credential provider should align the credential BLOB pointed to by the refOutAuthBuffer parameter to a 32-bit boundary, even if the provider is running on a 64-bit system.
          /// </summary>
          CREDUIWIN_PACK_32_WOW = 0x10000000,
    }

VB Syntax:

<Flags()> _
    Public Enum CredUIWinFlags As Integer
        CredUIWin_Generic = &H1
        CredUIWin_Checkbox = &H2
        CredUIWin_AuthPackage_Only = &H10
        CredUIWin_InCred_Only = &H20
        CredUIWin_Enumerate_Admins = &H100
        CredUIWin_Enumerate_CurrentUser = &H200
        CredUIWin_Secure_Prompt = &H1000
        CredUIWin_Pack_32_Wow = &H10000000
    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

!!!!Alternative Managed API:
Do you know one?  Please contribute it!

!!!!Notes:
None.

!!!!Tips & Tricks:
Please add some!

!!!!Sample Code:
C# Sample:

bool save = false;
    int errorcode = 0;
    uint dialogReturn;
    uint authPackage = 0;
    IntPtr outCredBuffer;
    uint outCredSize;

CREDUI_INFO credui = new CREDUI_INFO();
    credui.cbSize = Marshal.SizeOf(credui);
    credui.pszCaptionText = "Connect to your application";
    credui.pszMessageText = "Enter your credentials!";
    credui.hwndParent = this.Handle;

while (true) //Show the dialog again and again, until Cancel is clicked or the entered credentials are correct.
    {
          //Show the dialog
          dialogReturn = CredUIPromptForWindowsCredentials(ref credui,
          errorcode,
          ref authPackage,
          (IntPtr)0,  //You can force that a specific username is shown in the dialog. Create it with 'CredPackAuthenticationBuffer()'. Then, the buffer goes here...
          0,              //...and the size goes here. You also have to add CREDUIWIN_IN_CRED_ONLY to the flags (last argument).
          out outCredBuffer,
          out outCredSize,
          ref save,
          0); //Use the PromptForWindowsCredentialsFlags-Enum here. You can use multiple flags if you seperate them with | .
 
          if (dialogReturn != 0) break; //Break, if Cancel was clicked or an error occurred
 
 
          /*Unpack your credentials  (outCredBuffer, outCredSize) with 'CredUnPackAuthenticationBuffer()'
            For example, it returns a bool 'credentialsEnteredCorrect':*/
          bool credentialsEnteredCorrect = false;
 
 
          if (credentialsEnteredCorrect) break; //Break the while-loop, if the entered credentials are correct.
          else errorcode = 1326; //Else display an error message inside the dialog next time (The errorcodes are defined in 'winerror.h')
          //1326 = 'Logon failure: unknown user name or bad password.' 
    }

Documentation: CredUIPromptForWindowsCredentials@msdn on MSDN