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"
[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 that 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 is 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 |