Directory Services

DsMakePasswordCredentials

The DsMakePasswordCredentials function constructs a credential structure suitable for input to the DsBindWithCred function.

DWORD DsMakePasswordCredentials(
  LPCTSTR User,
  LPCTSTR Domain,
  LPCTSTR Password,
  RPC_AUTH_IDENTITY_HANDLE* pAuthIdentity
);

Parameters

User
[in] Pointer to a null-terminated string that contains the user name to use for the credentials.
Domain
[in] Pointer to a null-terminated string that contains the domain that the user is a member of.
Password
[in] Pointer to a null-terminated string that contains the password to use for the credentials.
pAuthIdentity
[out] Pointer to an RPC_AUTH_IDENTITY_HANDLE that receives the credential handle. This handle is used in a subsequent call to DsBindWithCred. Free this handle with the DsFreePasswordCredentials function when it is no longer required.

Return Values

Returns a Win32 error code, including the following.
Return Code Description
ERROR_SUCCESS The function was successful.
ERROR_INVALID_PARAMETER One or more parameters are invalid.
ERROR_NOT_ENOUGH_MEMORY A memory allocation failure occurred.
STATUS_INVALID_PARAMETER pAuthIdentity is invalid.

Remarks

A null, default credential may be created if none of the input parameters are present. Otherwise, User must be present. The Domain parameter may be null when User is fully qualified, such as a user in UPN format; for example, "someone@fabrikam.com".

When the handle returned in pAuthIdentitity is passed to DsBindWithCred, DsUnbind must be called before freeing the handle with DsFreePasswordCredentials. The normal sequence of events is:

  1. Call DsMakePasswordCredentials to obtain the credential handle.
  2. Call DsBindWithCred, passing the credential handle.
  3. Call DsUnbind when the RPC connection is no longer required.
  4. Call DsFreePasswordCredentials to free the credential handle.

Requirements

Client: Included in Windows XP and Windows 2000 Professional.
Server: Included in Windows Server 2003 and Windows 2000 Server.
Redistributable: Requires Active Directory Client Extension on Windows NT 4.0 SP6a and Windows 95/98/Me.
Unicode: Implemented as Unicode and ANSI versions on Windows NT/2000/XP.
Header: Declared in Ntdsapi.h.
Library: Use Ntdsapi.lib.

See Also

DsBindWithCred, DsFreePasswordCredentials, DsUnbind, RPC_AUTH_IDENTITY_HANDLE, Domain Controller and Replication Management Functions