DsBind function
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
DWORD DsBind( _In_opt_ LPCTSTR DomainControllerName, _In_opt_ LPCTSTR DnsDomainName, _Out_ HANDLE *phDS );
Parameters
- DomainControllerName [in, optional]
-
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.
- DnsDomainName [in, optional]
-
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.
- phDS [out]
-
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.
- ERROR_INVALID_PARAMETER
-
phDS is invalid.
- 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
-
Insufficient memory available.
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. |
Requirements
|
Minimum supported client |
Windows Vista |
|---|---|
|
Minimum supported server |
Windows Server 2008 |
|
Header |
|
|
Library |
|
|
DLL |
|
|
Unicode and ANSI names |
DsBindW (Unicode) and DsBindA (ANSI) |
See also
- DOMAIN_CONTROLLER_INFO
- DsBindWithCred
- DsGetDcName
- DsUnBind
- Domain Controller and Replication Management Functions