Share via

DsGetDcName (Compact 2013)

  • Article

3/26/2014

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.

Syntax

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

Parameters

  • ComputerName
    Not supported in Windows Embedded Compact. 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.

    Note

    For Windows Embedded Compact, 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 Compact-based device, though.

  • DomainGuid
    Not supported in Windows Embedded Compact. 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 Compact. 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.

    Note

    In Windows Embedded Compact, the DomainControllerAddress is always returned as NULL, even on successful discoveries.

Return Value

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.

Remarks

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.

Requirements

Header

dsgetdc.h

Library

netapi32.lib

See Also

Reference

Domain Discovery Functions
DOMAIN_CONTROLLER_INFO
NetApiBufferFree