DsGetDcName (Windows CE 5.0)

Send Feedback

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);

Parameters

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

    Note   For Windows 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 CE-based device, though.

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

    Note   In Windows CE, the DomainControllerAddress is always returned as NULL, even on successful discoveries.

Return Values

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.

Requirements

OS Versions: Windows CE 5.0 and later.
Header: Dsgetdc.h.
Library: Netapi32.lib.

See Also

DOMAIN_CONTROLLER_INFO | NetApiBufferFree

Send Feedback on this topic to the authors

Feedback FAQs

© 2006 Microsoft Corporation. All rights reserved.