CredUICredUIPromptForCredentials Method

[DllImportAttribute("CredUI.dll", CharSet = CharSet.Auto, BestFitMapping = false, 
	ThrowOnUnmappableChar = true)]
public static Win32ErrorCode CredUIPromptForCredentials(
	ref CredUiInfo refUiInfo,
	string targetName,
	[OptionalAttribute] IntPtr reserved,
	Win32ErrorCode authError,
	StringBuilder userName,
	int userNameSize,
	StringBuilder password,
	int passwordSize,
	ref bool refSave,
	CredentialsDialogOptions flags
)

<DllImportAttribute("CredUI.dll", CharSet := CharSet.Auto, BestFitMapping := false, 
	ThrowOnUnmappableChar := true>]
Public Shared Function CredUIPromptForCredentials ( 
	ByRef refUiInfo As CredUiInfo,
	targetName As String,
	<OptionalAttribute> reserved As IntPtr,
	authError As Win32ErrorCode,
	userName As StringBuilder,
	userNameSize As Integer,
	password As StringBuilder,
	passwordSize As Integer,
	ByRef refSave As Boolean,
	flags As CredentialsDialogOptions
) As Win32ErrorCode

Dim refUiInfo As CredUiInfo
Dim targetName As String
Dim reserved As IntPtr
Dim authError As Win32ErrorCode
Dim userName As StringBuilder
Dim userNameSize As Integer
Dim password As StringBuilder
Dim passwordSize As Integer
Dim refSave As Boolean
Dim flags As CredentialsDialogOptions

Dim returnValue As Win32ErrorCode

returnValue = CredUI.CredUIPromptForCredentials(refUiInfo, 
	targetName, reserved, authError, 
	userName, userNameSize, password, 
	passwordSize, refSave, flags)

public:
[DllImportAttribute(L"CredUI.dll", CharSet = CharSet::Auto, BestFitMapping = false, 
	ThrowOnUnmappableChar = true)]
static Win32ErrorCode CredUIPromptForCredentials(
	CredUiInfo% refUiInfo, 
	String^ targetName, 
	[OptionalAttribute] IntPtr reserved, 
	Win32ErrorCode authError, 
	StringBuilder^ userName, 
	int userNameSize, 
	StringBuilder^ password, 
	int passwordSize, 
	bool% refSave, 
	CredentialsDialogOptions flags
)

[<DllImportAttribute("CredUI.dll", CharSet = CharSet.Auto, BestFitMapping = false, 
	ThrowOnUnmappableChar = true)>]
static member CredUIPromptForCredentials : 
        refUiInfo : CredUiInfo byref * 
        targetName : string * 
        [<OptionalAttribute>] reserved : IntPtr * 
        authError : Win32ErrorCode * 
        userName : StringBuilder * 
        userNameSize : int * 
        password : StringBuilder * 
        passwordSize : int * 
        refSave : bool byref * 
        flags : CredentialsDialogOptions -> Win32ErrorCode 

No code example is currently available or this language may not be supported.

Parameters

refUiInfo  CredUiInfo

A CredUiInfo structure that contains information for customizing the appearance of the dialog box.

If the Parent member is not Zero, this function displays a modal dialog box centered on the parent window.

If the Parent member is Zero, the function displays a dialog box centered on the screen.

targetName  String

A pointer to a null-terminated string that contains the name of the target for the credentials, typically a server name.

For Distributed File System (DFS) connections, this string is of the form ServerName/ShareName.

This parameter is used to identify target information when storing and retrieving credentials.

reserved  IntPtr  (Optional)

This parameter is reserved for future use. It must be Zero.

authError  Win32ErrorCode

Specifies why the credential dialog box is needed.

A caller can pass this Windows error parameter, returned by another authentication call, to allow the dialog box to accommodate certain errors.

For example, if the password expired status code is passed, the dialog box could prompt the user to change the password on the account.

userName  StringBuilder

A pointer to a null-terminated string that contains the user name for the credentials.

If a nonzero-length string is passed, the UserName option of the dialog box is prefilled with the string.

In the case of credentials other than UserName/Password, a marshaled format of the credential can be passed in. This string is created by calling CredMarshalCredential function.

This function copies the user-supplied name to this buffer, copying a maximum of userNameSize characters. This format can be converted to UserName/Password format by using CredUIParseUserName(String, StringBuilder, Int32, StringBuilder, Int32).

A marshaled format can be passed directly to a security support provider (SSP).

If the DoNotPersist flag is not specified, the value returned in this parameter is of a form that should not be inspected, printed, or persisted other than passing it to CredUIParseUserName(String, StringBuilder, Int32, StringBuilder, Int32).

The subsequent results of CredUIParseUserName(String, StringBuilder, Int32, StringBuilder, Int32) can be passed only to a client-side authentication function such as WNetAddConnection or an SSP function.

If no domain or server is specified as part of this parameter, the value of the targetName parameter is used as the domain to form a DomainName/UserName pair.

On output, this parameter receives a string that contains that DomainName/UserName pair.

userNameSize  Int32

The maximum number of characters that can be copied to userName including the terminating null character.

password  StringBuilder

A pointer to a null-terminated string that contains the password for the credentials.

If a nonzero-length string is specified for password, the password option of the dialog box will be prefilled with the string.

This function copies the user-supplied password to this buffer, copying a maximum of passwordSize characters.

If the DoNotPersist flag is not specified, the value returned in this parameter is of a form that should not be inspected, printed, or persisted other than passing it to a client-side authentication function such as WNetAddConnection or an SSP function.

When you have finished using the password, clear the password from memory by calling the SecureZeroMemory function.

passwordSize  Int32

The maximum number of characters that can be copied to password including the terminating null character.

refSave  Boolean

A value that specifies the initial state of the Save check box and receives the state of the Save check box after the user has responded to the dialog box.

If this value is not NULL and CredUIPromptForCredentials(CredUiInfo, String, IntPtr, Win32ErrorCode, StringBuilder, Int32, StringBuilder, Int32, Boolean, CredentialsDialogOptions) returns ERROR_SUCCESS, then refSave returns the state of the Save check box when the user chose OK in the dialog box.

If the Persist flag is specified, the Save check box is not displayed, but is considered to be selected.

If the DoNotPersist flag is specified and ShowSaveCheckBox 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 refSave to receive the state of the Save check box after the user closes the dialog box. To do this, the caller must specify DoNotPersist and ShowSaveCheckBox in flags.

When DoNotPersist and ShowSaveCheckBox are set, the application is responsible for examining *pfSave after the function returns, and if refSave is , then the application must take the appropriate action to save the user credentials within the resources of the application.

flags  CredentialsDialogOptions

A value that specifies special behavior for this function.

Return Value

Reference