DsGetDcName (Windows CE 5.0)
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