Directory Services

DsBindWithCred

The DsBindWithCred function starts an RPC session with a particular domain controller and binds a handle to the directory service.

DWORD DsBindWithCred(
  LPCTSTR DomainController,
  LPCTSTR DnsDomainName,
  RPC_AUTH_IDENTITY_HANDLE AuthIdentity,
  HANDLE* phDS
);

Parameters

DomainController
[in, optional] Pointer to a null-terminated string that specifies the address of the domain controller. The address is in the same format as the DomainControllerName field of the DOMAIN_CONTROLLER_INFO structure returned by the DsGetDcName function. If this parameter is NULL, DsBindWithCred attempts to find and use a domain controller in the domain specified by DnsDomainName.

If this parameter is NULL and DnsDomainName is NULL, DsBindWithCred attempts to find and use a global catalog server in the forest of the local computer.

DnsDomainName
[in, optional] Pointer to a null-terminated string that specifies the dotted DNS name for a domain. If this parameter is NULL and DomainController is NULL, DsBindWithCred attempts to find and use a global catalog server in the forest of the local computer.

If this parameter is NULL and DomainController is not NULL, DsBindWithCred uses the domain name of the primary domain of the local computer.

AuthIdentity
[in, optional] Handle to the credentials used to start the RPC session. Use the DsMakePasswordCredentials function to create a structure suitable for AuthIdentity.

If this parameter is NULL, DsBindWithCred uses default process credentials. Passing NULL in AuthIdentity is equivalent to a call to DsBind.

phDS
[out] Address of a HANDLE value that receives the bind handle. To close this handle, call DsUnBind.

Return Values

If the function succeeds, NO_ERROR is returned.

If the function fails, an RPC error code, or one of the following, is returned.

Return Code Description
ERROR_NO_SUCH_DOMAIN No domain controller (DC) is available for the specified domain or the domain does not exist.
ERROR_INVALID_DOMAINNAME The format of the specified DnsDomainName is invalid.
ERROR_NOT_ENOUGH_MEMORY There is insufficient memory available.

Remarks

DsBindWithCred requires two optional input parameters that identify whether the caller has already found a domain controller using the DsGetDcName function or whether a domain controller should be found using default parameters. The following table describes the behavior patterns of possible combinations.

Note  The DnsDomainName is required to secure a Kerberos authentication.

DomainController DnsDomainName Description
NULL NULL DsBindWithCred attempts to bind to a global catalog and fails if one cannot be found.
(value) NULL The value for DomainController is assumed to have been obtained using the DsGetDcName function, which returns this value in the DomainControllerName field of the DOMAIN_CONTROLLER_INFO structure. The client is bound to the domain controller at this address.
NULL (value) DsBindWithCred attempts to find a domain controller for the domain identified by DnsDomainName and fails if one cannot be found.
(value) (value) This is an illegal combination. DsBindWithCred will fail.

When DsBindWithCred succeeds, DsUnbind must be called before freeing the AuthIdentity handle with DsFreePasswordCredentials.

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

DOMAIN_CONTROLLER_INFO, DsBind, DsGetDcName, DsMakePasswordCredentials, DsUnBind, DsFreePasswordCredentials, Mutual Authentication Using Kerberos, Domain Controller and Replication Management Functions