Export (0) Print
Expand All

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.

Return codeDescription
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 table describes the behavior of this function based on the contents of these parameters.

DomainControllerNameDnsDomainNameDescription
NULLNULLDsBind will attempt to bind to a global catalog server in the forest of the local computer.
(value)NULLDsBind 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 2000 Professional [desktop apps only]

Minimum supported server

Windows 2000 Server [desktop apps only]

Redistributable

Active Directory Client Extension on Windows NT 4.0 and Windows Me/98/95

Header

Ntdsapi.h

Library

Ntdsapi.lib

DLL

Ntdsapi.dll

Unicode and ANSI names

DsBindW (Unicode) and DsBindA (ANSI)

See also

DOMAIN_CONTROLLER_INFO
DsBindWithCred
DsGetDcName
DsUnBind
Domain Controller and Replication Management Functions

 

 

Show:
© 2014 Microsoft