Directory Services

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 uses default process credentials; to start a session with different credentials, call DsBindWithCred.

DWORD DsBind(
  LPCTSTR DomainController,
  LPCTSTR DnsDomainName,
  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 used in the DomainControllerName member of the DOMAIN_CONTROLLER_INFO structure returned by the DsGetDcName function. If this parameter is NULL, DsBind attempts to find and use a domain controller in the domain specified by DnsDomainName.

If this parameter is NULL and DnsDomainName is NULL, DsBind 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, DsBind 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, DsBind uses the domain name of the primary domain of the local computer.

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

Return Values

Returns an RPC error code or one of the following.

Return Code Description
NO_ERROR The function was successful.
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 accepts 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.

DomainController DnsDomainName Description
NULL NULL DsBind attempts to find 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) DsBind attempts to find a domain controller for the domain identified by DnsDomainName and fails if one cannot be found.
(value) (value) Illegal combination. DsBind will fail.

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, DsBindWithCred, DsGetDcName, DsUnBind, Domain Controller and Replication Management Functions