CredMarshalCredentialA function (wincred.h)

The CredMarshalCredential function transforms a credential into a text string. Historically, many functions, such as NetUseAdd, take a domain name, user name, and password as credentials. These functions do not accept certificates as credentials. The CredMarshalCredential function converts such credentials into a form that can be passed into these APIs.

The marshaled credential should be passed as the user name string to any API that is currently passed credentials. The domain name, if applicable, passed to that API should be passed as NULL or empty. For certificate credentials, the PIN of the certificate should be passed to that API as the password.

The caller should not modify or print marshaled credentials. The returned value can be freely converted between the Unicode, ANSI, and OEM characters sets. The string is case sensitive.

Syntax

BOOL CredMarshalCredentialA(
  [in]  CRED_MARSHAL_TYPE CredType,
  [in]  PVOID             Credential,
  [out] LPSTR             *MarshaledCredential
);

Parameters

[in] CredType

Type of the credential to marshal.

[in] Credential

Credential to marshal.

This is one of the CRED_MARSHAL_TYPE values.

If CredType is CertCredential, Credential points to a CERT_CREDENTIAL_INFO structure.

If CredType is UsernameTargetCredential, Credential points to a USERNAME_TARGET_CREDENTIAL_INFO structure.

[out] MarshaledCredential

Pointer to a null-terminated string that contains the marshaled credential. The caller should free the returned buffer using CredFree.

Return value

This function returns TRUE on success and FALSE on failure. The GetLastError function can be called to get a more specific status code. The following status code can be returned:

ERROR_INVALID_PARAMETER

CredType is not valid.

Remarks

Note

The wincred.h header defines CredMarshalCredential 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 Advapi32.lib
DLL Advapi32.dll

See also

CERT_CREDENTIAL_INFO

CRED_MARSHAL_TYPE

CredFree

CredUnmarshalCredential

GetLastError

USERNAME_TARGET_CREDENTIAL_INFO