DsBindWithCred

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

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

Parameters

DomainController

[in, optional] Pointer to a null-terminated string specifying the address of the domain controller. The address is in the same format as that used in the DomainControllerAddress field of the DOMAIN_CONTROLLER_INFO structure returned by the DsGetDcName function.

DnsDomainName

[in, optional] Pointer to a null-terminated string specifying the dotted DNS name for a domain.

AuthIdentity

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

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

phDS

[out] Pointer to a bind handle to the directory service.

Return Values

When successful, this function returns NO_ERROR.

If the function fails, the return value is either an RPC error code or one of the following.

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 takes 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. Behavior of the possible combinations is outlined in the following list.

DomainController(NULL), DnsDomainName(NULL)

DsBindWithCred will attempt to bind to a global catalog and fail if one cannot be found.

DomainController(value), DnsDomainName(NULL)

The value for DomainController is assumed to have been obtained using the DsGetDcName function, which returns this value in the DomainControllerAddress field of the DOMAIN_CONTROLLER_INFO structure. The client is bound to the domain controller at this address.

DomainController(NULL), DnsDomainName(value)

DsBindWithCred will attempt to find a domain controller for the domain identified by DnsDomainName and fail if one cannot be found.

DomainController(value), DnsDomainName(value)

This is an illegal combination. The call will fail.

Requirements

  Windows NT/2000: Requires Windows 2000.
  Header: Declared in Ntdsapi.h.
  Library: Included as a resource in Ntdsapi.dll.
  Unicode: Implemented as Unicode and ANSI versions on Windows 2000.

See Also

DC and Replication Management Functions, DOMAIN_CONTROLLER_INFO, DsBind, DsGetDcName, DsMakePasswordCredentials, DsUnBind