Export (0) Print
Expand All

DsGetDcName

Other versions of this page are also available for the following:
Windows Mobile Not SupportedWindows Embedded CE Supported
8/28/2008

This function returns the name of a domain controller in a specified domain. This function accepts additional domain controller selection criteria to indicate preference for a domain controller with particular characteristics.


DWORD DsGetDcName(
  LPCTSTR ComputerName,
  LPCTSTR DomainName,
  GUID* DomainGuid,
  LPCTSTR SiteName,
  ULONG Flags,
  PDOMAIN_CONTROLLER_INFO* DomainControllerInfo
);

ComputerName

Not supported in Windows Embedded CE. Must be set to NULL.

DomainName

[In] Pointer to a null-terminated string that specifies the name of the domain or the name of the application partition to query. This name can either be a DNS style name, for example, fabrikam.com, or a flat-style name, for example, Fabrikam.

Aa918344.note(en-us,MSDN.10).gifNote:
For Windows Embedded CE, if a flat-style name is passed with this parameter, only the DomainControllerName member will be returned in the DOMAIN_CONTROLLER_INFO structure upon a successful lookup. No other member will be set in the structure. The members will be set when a DNS name is queried on a Windows Embedded CE-based device, though.
DomainGuid

Not supported in Windows Embedded CE. Must be set to NULL.

SiteName

[in] Pointer to a null-terminated string that specifies the name of the site where the returned domain controller should physically exist. If this parameter is NULL, DsGetDcName attempts to return a domain controller in the site closest to the site of the computer specified by ComputerName. This parameter should be NULL by default.

Flags

Not supported in Windows Embedded CE. Must be set to NULL.

DomainControllerInfo

[out] Pointer to a PDOMAIN_CONTROLLER_INFO value that receives a pointer to a DOMAIN_CONTROLLER_INFO structure that contains data about the domain controller selected. This structure is allocated by DsGetDcName. The caller must free the structure using the NetApiBufferFree function when it is no longer required.

Aa918344.note(en-us,MSDN.10).gifNote:
In Windows Embedded CE, the DomainControllerAddress is always returned as NULL, even on successful discoveries.

If the function returns domain controller data, the return value is ERROR_SUCCESS.

If the function fails, the return value can be one of the following error codes.

Value Description

ERROR_INVALID_DOMAINNAME

The format of the specified DomainName is invalid.

ERROR_INVALID_FLAGS

The Flags parameter contains conflicting or superfluous flags.

ERROR_NOT_ENOUGH_MEMORY

A memory allocation failure occurred.

ERROR_NO_SUCH_DOMAIN

No domain controller is available for the specified domain or the domain does not exist.

DsGetDcName does not verify that the domain controller name returned is the name of an actual domain controller or global catalog. If mutual authentication is required, the caller must perform the authentication.

DsGetDcName does not require any particular access to the specified domain. By default, this function does not ensure that the returned domain controller is currently available. Instead, the caller should attempt to use the returned domain controller.

When you query a flatname, you will only get the domain controller name, not the additional information that can be obtained by querying a fully qualified domain name.

Headerdsgetdc.h
Librarynetapi32.lib
Windows Embedded CEWindows CE 5.0 and later

Community Additions

Show:
© 2014 Microsoft