DsBindW function (ntdsapi.h)

Article
02/09/2023

The DsBind function binds to a domain controller.DsBind uses the default process credentials to bind to the domain controller. To specify alternate credentials, use the DsBindWithCred function.

Syntax

NTDSAPI DWORD DsBindW(
  [in, optional] LPCWSTR DomainControllerName,
  [in, optional] LPCWSTR DnsDomainName,
  [out]          HANDLE  *phDS
);

Parameters

[in, optional] DomainControllerName

Pointer to a null-terminated string that contains the name of the domain controller to bind to. This name can be the name of the domain controller or the fully qualified DNS name of the domain controller. Either name type can, optionally, be preceded by two backslash characters. All of the following examples represent correctly formatted domain controller names:

"FAB-DC-01"
"\\FAB-DC-01"
"FAB-DC-01.fabrikam.com"
"\\FAB-DC-01.fabrikam.com"

This parameter can be NULL. For more information, see Remarks.

[in, optional] DnsDomainName

Pointer to a null-terminated string that contains the fully qualified DNS name of the domain to bind to. This parameter can be NULL. For more information, see Remarks.

[out] phDS

Address of a HANDLE value that receives the binding handle. To close this handle, pass it to the DsUnBind function.

Return value

Returns ERROR_SUCCESS if successful or a Windows or RPC error code otherwise. The following are the most common error codes.

Remarks

The behavior of the DsBind function is determined by the contents of the DomainControllerName and DnsDomainName parameters. The following list describes the behavior of this function based on the contents of these parameters.

DomainControllerName	DnsDomainName	Description
NULL	NULL	DsBind will attempt to bind to a global catalog server in the forest of the local computer.
(value)	NULL	DsBind will attempt to bind to the domain controller specified by the DomainControllerName parameter.
NULL	(value)	DsBind will attempt to bind to any domain controller in the domain specified by DnsDomainName parameter.
(value )	(value)	The DomainControllerName parameter takes precedence. DsBind will attempt to bind to the domain controller specified by the DomainControllerName parameter.

Note

The ntdsapi.h header defines DsBind as an alias which automatically selects the ANSI or Unicode version of this function based on the definition of the UNICODE preprocessor constant. Mixing usage of the encoding-neutral alias with code that not encoding-neutral can lead to mismatches that result in compilation or runtime errors. For more information, see Conventions for Function Prototypes.

Requirements

Requirement	Value
Minimum supported client	Windows Vista
Minimum supported server	Windows Server 2008
Target Platform	Windows
Header	ntdsapi.h
Library	Ntdsapi.lib
DLL	Ntdsapi.dll