DsBindA function (ntdsapi.h)

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 DsBindA(
  [in, optional] LPCSTR DomainControllerName,
  [in, optional] LPCSTR 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

See also

DOMAIN_CONTROLLER_INFO

Domain Controller and Replication Management Functions

DsBindWithCred

DsGetDcName

DsUnBind