CredUIParseUserNameA function (wincred.h)

Article
02/09/2023

The CredUIParseUserName function extracts the domain and user account name from a fully qualified user name.

Syntax

CREDUIAPI DWORD CredUIParseUserNameA(
  [in]  PCSTR userName,
  [out] CHAR  *user,
  [in]  ULONG userBufferSize,
  [out] CHAR  *domain,
  [in]  ULONG domainBufferSize
);

Parameters

[in] userName

Pointer to a null-terminated string that contains the user name to be parsed. The name must be in UPN or down-level format, or a certificate. Typically, pszUserName is received from the CredUIPromptForCredentials or CredUICmdLinePromptForCredentials.

[out] user

Pointer to a null-terminated string that receives the user account name.

[in] userBufferSize

Maximum number of characters to write to the pszUser string including the terminating null character.

Note CREDUI_MAX_USERNAME_LENGTH does NOT include the terminating null character.

[out] domain

Pointer to a null-terminated string that receives the domain name. If pszUserName specifies a certificate, pszDomain will be NULL.

[in] domainBufferSize

Maximum number of characters to write to the pszDomain string including the terminating null character.

Note CREDUI_MAX_DOMAIN_TARGET_LENGTH does NOT include the terminating null character.

Return value

This function returns the following:

NO_ERROR
The user name is valid.
ERROR_INVALID_ACCOUNT_NAME
The user name is not valid.
ERROR_INSUFFICIENT_BUFFER
One of the buffers is too small.
ERROR_INVALID_PARAMETER
- ulUserMaxChars or ulDomainMaxChars is zero.
- pszUserName, pszUser, or pszDomain is NULL.

Remarks

This function parses the user name information returned by the CredUIPromptForCredentials and CredUICmdLinePromptForCredentials functions so that the resulting credentials can be passed to functions, such as LogonUser, that require the user name and domain as separate strings.

The following formats are supported:

<MarshalledCredentialReference>
Marshaled credential reference as defined by CredIsMarshaledCredential. Such a credential is returned in the User parameter. The Domain parameter is set to an empty string.
<DomainName>\<UserName>
<UserName> is returned in the User parameter and the <DomainName> is returned is the Domain parameter. The name is considered to have this syntax if the UserName contains a backslash (\).
<UserName>@<DNSDomainName>
The entire string is returned in the User parameter. The Domain parameter is set to an empty string. For this syntax, the last @ in the string is used because <UserName> can contain an @ but <DNSDomainName> cannot.

Note

The wincred.h header defines CredUIParseUserName as an alias which automatically selects the ANSI or Unicode version of this function based on the definition of the UNICODE preprocessor constant. Mixing usage of the encoding-neutral alias with code that not encoding-neutral can lead to mismatches that result in compilation or runtime errors. For more information, see Conventions for Function Prototypes.

Requirements

Requirement	Value
Minimum supported client	Windows XP [desktop apps only]
Minimum supported server	Windows Server 2003 [desktop apps only]
Target Platform	Windows
Header	wincred.h
Library	Credui.lib
DLL	Credui.dll