DsBind

The DsBind function starts a remote procedure call (RPC) session with a particular domain controller and binds a handle to the directory service. DsBind will use default process credentials; to start a session with different credentials, call DsBindWithCred instead.

DWORD DsBind(
  TCHAR *DomainController,
  TCHAR *DnsDomainName,
  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.

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

DSBind 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)

DsBind will attempt to find 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 DomainController field of the DOMAIN_CONTROLLER_INFO structure. The client is bound to the domain controller at this address.

DomainController(NULL), DnsDomainName(value)

DsBind 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 is failed.

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, DsBindWithCred, DsGetDcName, DsUnBind