Share via

3.5.4.3.1 DsrGetDcNameEx2 (Opnum 34)

  • Article

The DsrGetDcNameEx2 method SHOULD<148> return information about a domain controller (DC) in the specified domain and site. If the AccountName parameter is not NULL, and a DC matching the requested capabilities (as defined in the Flags parameter) responds during this method call, then that DC will have verified that the DC account database contains an account for the AccountName specified. The server that receives this call is not required to be a DC. 

 NET_API_STATUS DsrGetDcNameEx2(
   [in, unique, string] LOGONSRV_HANDLE ComputerName,
   [in, unique, string] wchar_t* AccountName,
   [in] ULONG AllowableAccountControlBits,
   [in, unique, string] wchar_t* DomainName,
   [in, unique] GUID* DomainGuid,
   [in, unique, string] wchar_t* SiteName,
   [in] ULONG Flags,
   [out] PDOMAIN_CONTROLLER_INFOW* DomainControllerInfo
 );

ComputerName: The custom binding handle defined in section 3.5.4.1.

AccountName: A null-terminated Unicode string that contains the name of the account that MUST exist and be enabled on the DC.

AllowableAccountControlBits: A set of bit flags that list properties of the AccountName account. A flag is TRUE (or set) if its value is equal to 1. If the flag is set, then the account MUST have that property; otherwise, the property is ignored. The value is constructed from zero or more bit flags from the following table.


0


1


2


3


4


5


6


7


8


9

1
0


1


2


3


4


5


6


7


8


9

2
0


1


2


3


4


5


6


7


8


9

3
0


1

0

0

0

0

0

0

F

0

0

0

0

0

0

0

0

0

0

0

E

D

C

0

B

A

0

0

0

0

0

0

0

0

Where the bits are defined as:

Value

Description

A

Account for users whose primary account is in another domain. This account provides user access to the domain, but not to any domain that trusts the domain.

B

Normal domain user account.

C

Interdomain trust account.

D

Computer account for a domain member.

E

Computer account for a backup domain controller (BDC).

F

Computer account for a read-only domain controller (RODC).<149>

All other bits MUST be set to zero and MUST be ignored on receipt.

DomainName: A null-terminated Unicode string that contains the domain name. If the string is NULL or empty (that is, the first character in the string is the null-terminator character), then the primary domain name is assumed.

DomainGuid: A pointer to a GUID structure that specifies the GUID of the domain queried. If DomainGuid is not NULL and the domain specified by DomainName cannot be found, the DC locator attempts to locate a DC in the domain that has the GUID specified by DomainGuid. This allows renamed domains to be found by their GUID.

SiteName: A null-terminated string that contains the name of the site in which the DC MUST be located.

Flags: A set of bit flags that provide additional data that is used to process the request. A flag is TRUE (or set) if its value is equal to 1. The value is constructed from zero or more bit flags from the following table.


0


1


2


3


4


5


6


7


8


9

1
0


1


2


3


4


5


6


7


8


9

2
0


1


2


3


4


5


6


7


8


9

3
0


1

S

R

0

0

0

0

0

0

W

V

U

T

Q

P

O

N

M

L

K

J

I

H

G

F

E

D

C

B

0

0

0

A

Where the bits are defined as:

Value

Description

A

The server ignores any cached DC data.

B

The server returns a DC that supports directory service functions.

C

The server first attempts to find a DC that supports directory service functions.

D

The server returns a DC that is a global catalog server for the forest.

E

The server returns a DC that is the PDC for the domain.

F

The server uses cached DC data if available, even if the cached data is expired.

G

The server returns a DC that has an IP (either IPv4 or IPv6) address.

H

The server returns a DC that is currently running the Kerberos Key Distribution Center service.

I

The server returns a DC that is currently running W32Time.

J

The server returns a DC that is writable.

K

The server first attempts to find a DC that is a reliable time server. If a reliable time server is unavailable, the server returns a DC that is currently running W32Time.

L

The server returns a different DC in the domain if one exists.

M

The server returns an LDAP server. The server MAY return a DC.

N

Specifies that the DomainName parameter is a NetBIOS name.

O

Specifies that the DomainName parameter is a DNS name.

P

The server attempts to find a DC in the next closest site if a DC in the closest site is not available. If a DC in the next closest site is also not available, the server returns any available DC.<150>

Q

The server returns a DC that has a DC functional level of DS_BEHAVIOR_WIN2008 or greater, as specified in [MS-ADTS] section 6.1.4.2.

R

Specifies that the names returned in the DomainControllerName and DomainName fields of DomainControllerInfo are DNS names.

S

Specifies that the names returned in the DomainControllerName and DomainName fields of DomainControllerInfo are NetBIOS names.

T

The server returns a DC that is currently running the Active Directory Web Service.

U

The server returns a DC that has a DC functional level of DS_BEHAVIOR_WIN2012 or greater, as specified in [MS-ADTS] section 6.1.4.2.

V

The server returns a DC that has a DC functional level of DS_BEHAVIOR_WIN2012R2 or greater, as specified in [MS-ADTS] section 6.1.4.2.

W

The server returns a DC that has a DC functional level of DS_BEHAVIOR_WIN2016 or greater, as specified in [MS-ADTS] section 6.1.4.2.

All other bits MUST be set to zero. The server MUST return ERROR_INVALID_FLAGS if any of the unspecified bits are not zero.

DomainControllerInfo: A pointer to a DOMAIN_CONTROLLER_INFOW structure (section 2.2.1.2.1) containing data about the DC.

Return Values: The method returns 0x00000000 on success; otherwise, it returns a nonzero error code.

On receiving this call, the server MUST perform the following Flags parameter validations:

  • Flags D, E, and H MUST NOT be combined with each other.

  • Flag N MUST NOT be combined with the O flag.

  • Flag R MUST NOT be combined with the S flag.

  • Flags B, Q, U, V, and W MUST NOT be combined with each other.

  • Flag K MUST NOT be combined with any of the flags: B, C, D, E, or H.

  • Flag P MUST NOT be set when the SiteName parameter is provided.

The server MUST return ERROR_INVALID_FLAGS for any of the previously mentioned conflicting combinations.

Additionally, the server MUST perform the following parameter validations:

  • If the flag D is set and DomainName parameter is neither NULL nor empty, the DomainName is a valid NetBIOS name format or a FQDN format, and the DomainName is not the FQDN or NetBIOS name of a trusted forest, then the server MUST return ERROR_NO_SUCH_DOMAIN. To determine the list of trusted forests, and their FQDN) and NetBIOS names, the server MUST use the TrustedDomains ADM. The domains from this collection that have the C bit set in the Flags field represent the trusted forests.

  • If the flag N is set and DomainName parameter is neither NULL nor empty and the DomainName is NOT a valid NetBIOS name format, then the server MUST return ERROR_INVALID_DOMAINNAME.

  • If the flag O is set and DomainName parameter is neither NULL nor empty and the DomainName is NOT in a valid FQDN format and AllowDnsSuffixSearch is FALSE, then the server MUST return ERROR_INVALID_DOMAINNAME.

  • If neither the N flag nor the O flag are specified and DomainName parameter is neither NULL nor empty, then the server MUST return ERROR_INVALID_DOMAINNAME if the DomainName is neither a valid NetBIOS name format nor a valid FQDN format.

If the A bit in Flags is not set, then the server attempts to use the LocatedDCsCache and FailedDiscoveryCache if it has them, even if the F bit in Flags is not set. The process for this is as follows:

  • If there is no entry for the requested domain in LocatedDCsCache, then check if it exists in FailedDiscoveryCache. If an entry is found in FailedDiscoveryCache, then find the delta between the current time and the last failure time for that cache entry. If this delta is less than FailedDiscoveryCachePeriod, the server returns an error.

  • If there is an entry for the requested domain in LocatedDCsCache, but its capabilities do not include the requested capabilities, then invalidate the cached entry and attempt to locate a DC as follows.

  • If the delta between the current time and the creation time for the entry in LocatedDCsCache is greater than the CacheEntryValidityPeriod and the F bit in the Flags is not set, then invalidate the cached entry and attempt to locate a DC as follows.

  • If the difference between the current time and the refresh time for the entry in LocatedDCsCache is greater than CacheEntryPingValidityPeriod, then the server MUST send a ping message to the DC prior to returning the value. The ping mechanism to be used, whether LDAP Ping ([MS-ADTS] section 6.3.3) or Mailslot Ping ([MS-ADTS] section 6.3.5), is determined based on the N and O bit settings in the Flags, as follows. If a ping of the DC fails, then it MUST invalidate the cache entry and attempt to locate a DC as follows. Otherwise update the refresh time and return the cached result.

The server MUST attempt to locate a domain controller for the domain specified by the client. The server SHOULD<151> implement alternate means of locating a DC: for example, a static list in a file, or the two methods detailed in  [MS-ADTS] section 6.3.6.

If the ComputerName parameter is not NULL, it is compared against the server's computer name. If the server is not a DC (section 3.1.4.8) and the ComputerName parameter does not match the server's computer name, the server MUST return STATUS_INVALID_COMPUTER_NAME. If the ComputerName parameter matches the server's computer name, the ComputerName parameter is NULL, or the server is a DC, then processing proceeds.

The server uses the DC location protocol ([MS-ADTS] section 6.3.6) to locate a DC (the located DC is known as the responding DC). There are two methods of locating a DC that the DC location protocol supports. One of the methods involves the DNS-based discovery mechanism (defined in the following) and then the LDAP ping message, and the other method involves the mailslot ping message.

If the N bit is set in the Flags parameter, the mailslot message MUST be sent.

If the O bit is set in the Flags parameter, DNS-based discovery MUST be performed, and the LDAP message MUST be sent.

  • If the DomainName parameter is an FQDN with a single label and AllowDnsSuffixSearch is TRUE and AllowSingleLabelDNSDomain is FALSE, then a DNS-based discovery is attempted. The DNS SRV queries specified below are performed by using FQDNs formed by appending in turn each of the server's DNS suffixes to DomainName.

If neither the N bit nor the O bit are specified, then:

  • If the DomainName parameter is an FQDN with more than one label (as specified in [RFC1035]), or if the AllowSingleLabelDNSDomain field is TRUE and the DomainName parameter is an FQDN with a single label, then a DNS-based discovery is attempted and an LDAP message sent.

  • If the DomainName parameter is a syntactically valid NetBIOS name (as specified in [MS-NBTE]), then the mailslot message MUST be sent.

If the DNS-based discovery is performed, the server identifies the candidate DCs by performing DNS SRV queries as follows:

  1. Based on the value of the B, D, E, H, and M bits in the Flags parameter, the appropriate query is selected from those listed in [MS-ADTS] section 6.3.6. Other bits specified in the Flags parameter do not contribute to the selection of this query but are used to validate against the capabilities published in the ping response. The table below shows the specific query that is used for the different valid combinations of these bits:

    Bits specified

    Non site-specific query

    Site-specific query

    B=0/1, D=0, E=1, H=0, M=0/1

    _ldap._tcp.pdc._msdcs.<domainname>

    N/A

    B=0/1, D=0, E=0, H=1, M=0/1

    _kerberos._tcp.dc._msdcs.<domainname>

    _kerberos._tcp.<sitename>._sites.dc._msdcs.<domainname>

    B=0/1, D=1, E=0, H=0, M=1

    _gc._tcp.<forestname>

    _gc._tcp.<sitename>._sites.<forestname>

    B=0/1, D=0, E=0, H=0, M=1

    _ldap._tcp.<domainname>

    _ldap._tcp.<sitename>._sites.<domainname>

    B=0/1, D=1, E=0, H=0, M=0

    _gc._tcp.dc._msdcs.<forestname>

    _gc._tcp.<sitename>._sites.dc._msdcs.<forestname>

    B=0/1, D=0, E=0, H=0, M=0

    _ldap._tcp.dc._msdcs.<domainname>

    _ldap._tcp.<sitename>._sites.dc._msdcs.<domainname>

  2. If the SiteName parameter is not NULL, the server MUST attempt a site-specific query. For example, if the request is to locate a Key Distribution Center (KDC), the following query is used: _kerberos._tcp.<SiteName>._sites.dc._msdcs.<DomainName>.

  3. If the SiteName parameter is NULL, the server MUST attempt to first use a site-specific query for the SiteName (ADM element) site where applicable. For example, if the request is to locate a KDC, the following query is used: _kerberos._tcp.<SiteName>._sites.dc._msdcs.<DomainName>. If the site-specific query does not result in any candidate domain controllers, or if the candidate domain controllers are not reachable via LDAP ping (defined in the following), and if the P bit in the Flags parameter is set, and if NextClosestSiteName (ADM element) is not NULL, then the server MUST attempt to locate a DC in the next closest site by performing a site-specific query for NextClosestSiteName. If a DC in the next closest site is not available, or if the P bit in the Flags parameter was not set, or if NextClosestSiteName was NULL, the server MUST return any available DC, using a non-site-specific query to determine the candidate domain controllers. Using the same KDC example as before, the following non-site-specific query is used: _kerberos._tcp.dc._msdcs.<DomainName>.

In either mechanism (defined in [MS-ADTS] section 6.3.6), multiple candidate DCs can be discovered. The candidate DCs are pinged to determine availability and ability to satisfy the specified requirements.

The LDAP/mailslot ping messages are constructed as follows:

When using the LDAP ping method ([MS-ADTS] section 6.3.3), the server MUST set the parameters of the LDAP message as follows:

  • The DnsDomain field of the message is set to the DomainName parameter of the DsrGetDcNameEx2 call. If DomainName is NULL, the DnsDomain field of the message is set to DnsDomainName (section 3.5.1). If the DomainName parameter is an FQDN with a single label and AllowDnsSuffixSearch is TRUE and AllowSingleLabelDNSDomain is FALSE, the DnsDomain field of the message is set to the FQDN formed by appending in turn each of the server's DNS suffixes to DomainName.

  • The Host field of the message is set to the ComputerName that is sending the message.

  • The User field of the message is not set.

  • The AAC field of the message is not set.

  • The DomainSid field of the message is not set.

  • If the DomainGuid parameter of the DsrGetDcNameEx2 is not NULL, the DomainGuid field of the message is set to the DomainGuid parameter, else the DomainGuid field of the message is not set.

When using the mailslot ping method ([MS-ADTS] section 6.3.5), the server MUST set the parameters of the mailslot message as follows:

  • The UnicodeComputerName field of the message is set to the ComputerName that is sending the message.

  • The UnicodeUserName field of the message is not set.

  • The AllowableAccountControlBits field of the message is not set.

  • The DomainSidSize field of the message is set to 0x00000000.

  • The DomainSid field of the message is not set.

  • The DomainGuid field of the message is not set.

If the AccountName parameter is specified, the server MUST perform the following additional processing that is defined in [MS-ADTS]:

  • The LDAP and mailslot query message fields are set as specified in [MS-ADTS] sections 6.3.3 and 6.3.5, except for the following:

    • LDAP ping message:

      • The User field of the message is set to the value of the AccountName parameter.

      • The AAC field of the message is mapped from the AllowableAccountControlBits parameter, according to the table in [MS-SAMR] section 3.1.5.14.2, where the "ProtocolUserAccountControl" column defines the AAC field while the "DatabaseUserAccountControl" column defines the AllowableAccountControlBits.

    • Mailslot message:

      • The UnicodeUserName field of the message is set to the value of the AccountName parameter.

      • The AllowableAccountControlBits field of the message is mapped from the AllowableAccountControlBits parameter, according to the table in [MS-SAMR] section 3.1.5.14.2, where the "ProtocolUserAccountControl" column defines the AAC field while the "DatabaseUserAccountControl" column defines the AllowableAccountControlBits.

LDAP/Mailslot ping responses from the candidate DCs are processed (in the order in which they are received) along with the flags to determine if the server queried meets all of the requirements, until a server that meets the requirements is found or an implementation-specific timeout is reached.

If the B bit in the Flags is set, the server SHOULD<152> return a DC that supports directory service functions. To determine if a domain controller meets this requirement, the server MUST check the value of the NETLOGON_SAM_LOGON_RESPONSE.NtVersion field in the message and ensure that NETLOGON_NT_VERSION_5 or greater is specified. If a server that meets this requirement cannot be located, the server MUST return ERROR_NO_SUCH_DOMAIN.

If the C bit in the Flags is set, the service MUST first attempt to find a DC that supports directory service functions.<153> To determine if a domain controller meets this requirement, the server MUST check the value of the NETLOGON_SAM_LOGON_RESPONSE.NtVersion field in the message and ensure that NETLOGON_NT_VERSION_5 or greater is specified. If a DC that supports the directory service functions is not available, the server MUST return the name of a non–directory service DC.

If the D bit in the Flags is set, the server MUST return a DC that is a global catalog server for the forest of domains. To determine if a domain controller is a global catalog server, the server MUST check the value of the FG bit in the Flags field of the message as defined in [MS-ADTS] section 6.3.1.2.

If the E bit in the Flags is set, the server MUST return a DC that is the PDC for the domain. To determine if a domain controller is a primary domain controller the server MUST check the value of the FP bit in the Flags field of the message as defined in [MS-ADTS] section 6.3.1.2. If a server that meets this requirement cannot be located, the server MUST return ERROR_NO_SUCH_DOMAIN.

If the G bit in the Flags is set, the server MUST return a DC that has an IP (either IPv4 or IPv6) address. The IP address is verified by examining the DcIpAddress field of the NETLOGON_SAM_LOGON_RESPONSE message ([MS-ADTS] section 6.3.1.8) or the DcSockAddr field of the NETLOGON_SAM_LOGON_RESPONSE_EX message ([MS-ADTS] section 6.3.1.9). If a server that meets this requirement cannot be located, the server MUST return ERROR_NO_SUCH_DOMAIN.

If the H bit in the Flags is set, the server MUST return a DC that is currently running the Kerberos Key Distribution Center service. To determine if a domain controller is currently running the Kerberos Key Distribution Center service, the server MUST check the value of the FK bit in the Flags field of the message as defined in [MS-ADTS] section 6.3.1.2. If a server that meets this requirement cannot be located, the server MUST return ERROR_NO_SUCH_DOMAIN.

If the I bit in the Flags is set, then the server MUST return a DC that is currently running W32Time. To determine if a domain controller is currently running an [MS-SNTP] implementation, the server MUST check the value of the FT bit in the Flags field of the message as defined in [MS-ADTS] section 6.3.1.2. If a server that meets this requirement cannot be located, the server MUST return ERROR_NO_SUCH_DOMAIN.

If the J bit in the Flags is set, the server MUST return a DC that is writable.<154> To determine if a domain controller is writable, the server MUST check the value of the FW bit in the Flags field of the message as defined in [MS-ADTS] section 6.3.1.2. If a server that meets this requirement cannot be located, the server MUST return ERROR_NO_SUCH_DOMAIN.

If the K bit in the Flags is set, the server returns a DC that is a reliable time server. If a reliable time server is unavailable, the server returns a DC that is a time server. To determine whether a domain controller is a reliable time server, the server MUST check the value of the FGT bit in the Flags field of the message as defined in [MS-ADTS] section 6.3.1.2. To determine whether a domain controller is a time server, the server MUST check the value of the FT bit in the Flags field of the message as defined in [MS-ADTS] section 6.3.1.2. If a domain controller that meets either of these requirements cannot be located, the server MUST return ERROR_NO_SUCH_DOMAIN.

If the L bit in the Flags is set, the server MUST return a DC in the domain other than the server if one exists. This flag is ignored if the recipient if not running as a DC.

If the M bit in the Flags is set, the server MUST return an LDAP server. To determine if a domain controller is an LDAP server, the server MUST check the value of the FL bit in the Flags field of the message as defined in [MS-ADTS] section 6.3.1.2. The server MAY return a DC. No other services are required to be present on the server returned. The server MAY return a server that has a writable config container or a writable schema container. If the D bit in the Flags is set, the server returned MUST be an LDAP server and a global catalog server and might be a DC. No other services are implied to be present at the server. If this flag is specified, the B, C, E, H, I, J, and T bits in the Flags are ignored along with their respective processing requirements.

If the Q bit in Flags is set, the server MUST return a DC that has a functional level of DS_BEHAVIOR_WIN2008 or greater. To determine the functional level of a DC, the server MUST locate the DC's nTDSDSA object in the directory and verify the msDS-Behavior-Version attribute as specified in [MS-ADTS] section 6.1.4.2.

If the T bit in the Flags is set, the server SHOULD<155> return a DC that is currently running the Active Directory Web Service. To determine if a domain controller is currently running the Active Directory Web Service, the server MUST check the value of the FWS bit in the Flags field of the message as defined in [MS-ADTS] section 6.3.1.2. If a server that meets this requirement cannot be located, the server MUST return ERROR_NO_SUCH_DOMAIN.

If the U bit in Flags is set, the server MUST return a DC that has a functional level of DS_BEHAVIOR_WIN2012 or greater. To determine the functional level of a DC, the server MUST locate the DC's nTDSDSA object in the directory and verify the msDS-Behavior-Version attribute as specified in [MS-ADTS] section 6.1.4.2.

If the V bit in Flags is set, the server MUST return a DC that has a functional level of DS_BEHAVIOR_WIN2012R2 or greater. To determine the functional level of a DC, the server MUST locate the DC's nTDSDSA object in the directory and verify the msDS-Behavior-Version attribute as specified in [MS-ADTS] section 6.1.4.2.

If the W bit in Flags is set, then the server MUST return a DC that has a functional level of DS_BEHAVIOR_WIN2016 or greater. To determine the functional level of a DC, the server MUST locate the DC's nTDSDSA object in the directory and verify the msDS-Behavior-Version attribute as specified in [MS-ADTS] section 6.1.4.2.

NETLOGON_SAM_LOGON_RESPONSE_EX ([MS-ADTS] section 6.3.1.9) and NETLOGON_SAM_LOGON_RESPONSE ([MS-ADTS] section 6.3.1.8) messages are received from a DC in response to the LDAP and the mailslot messages, respectively. Using these response messages, the DsrGetDcNameEx2 populates the returned DOMAIN_CONTROLLER_INFOW structure (section 2.2.1.2.1) as follows:

  • The DnsHostName, DnsDomainName, NetbiosComputerName, and NetbiosDomainName fields are compressed and MUST be decompressed as specified in [MS-ADTS] section 6.3.7.

  • If the R flag is set in the Flags parameter:

    • The DomainControllerInfo.DomainControllerName field MUST be set to the value of the DnsHostName message field. If the DnsHostName field is not set in the message, the error ERROR_NO_SUCH_DOMAIN MUST be returned.

    • The DomainControllerInfo.DomainName field MUST be set to the value of the DnsDomainName message field. If the DnsDomainName field is not set in the message, the error ERROR_NO_SUCH_DOMAIN MUST be returned.

  • If the S flag is set in the Flags parameter:

    • The DomainControllerInfo.DomainControllerName field MUST be set to the value of the NetbiosComputerName message field.

    • The DomainControllerInfo.DomainName field MUST be set to the value of the NetbiosDomainName message field.

  • If neither the R nor S flags are set in the Flags parameter:<156>

    • The DomainControllerInfo.DomainControllerName field MUST be set to either the value of the DnsHostName message field, or to the value of the NetbiosComputerName message field.<157>

    • The DomainControllerInfo.DomainName field MUST be set to either the value of the DnsDomainName message field, or to the value of the NetbiosDomainName message field.<158>

  • If the IP address of the DC to which the message was sent is known from the underlying transport protocol, the DomainControllerInfo.DomainControllerAddress field MUST be set to that address. Otherwise, the field is set from the value of the NETLOGON_SAM_LOGON_RESPONSE_EX.DcSockAddr message field if the NETLOGON_SAM_LOGON_RESPONSE_EX.DcSockAddrSize message field is not zero.

  • If the IP address of the DC is not available because the aforementioned conditions are not met, the DomainControllerInfo.DomainControllerAddress field MUST be set to the NETLOGON_SAM_LOGON_RESPONSE_EX.NetbiosComputerName field.

  • The DomainControllerInfo.DomainControllerAddressType field MUST be set to 0x00000001 if the DomainControllerAddress field is set to the IP address of the DC. Otherwise, the DomainControllerInfo.DomainControllerAddressType field MUST be set to 0x00000002 for a NETBIOS name.

  • The DomainControllerInfo.DomainGuid field MUST be set to the NETLOGON_SAM_LOGON_RESPONSE.DomainGuid or the NETLOGON_SAM_LOGON_RESPONSE_EX.DomainGuid field.

  • The DomainControllerInfo.DnsForestName field MUST be set to the value of the NETLOGON_SAM_LOGON_RESPONSE.DnsForestName or the NETLOGON_SAM_LOGON_RESPONSE_EX.DnsForestName fields if they are present, or to NULL if the NETLOGON_SAM_LOGON_RESPONSE.DnsForestName and the NETLOGON_SAM_LOGON_RESPONSE_EX.DnsForestName fields are not present.

  • The DomainControllerInfo.Flags field MUST be set to the value of the NETLOGON_SAM_LOGON_RESPONSE.Flags or the NETLOGON_SAM_LOGON_RESPONSE_EX.Flags field. Additionally, the following flags are set in the DomainControllerInfo.Flags field:

    • The flag M MUST be set if the DomainControllerInfo.DomainControllerName field is set to the FQDN of the DC.

    • The flag N MUST be set if the DomainControllerInfo.DomainName field is set to the FQDN of the domain.

    • The flag O MUST be set if the DomainControllerInfo.DnsForestName field is set.

  • The DomainControllerInfo.DcSiteName field MUST be set to the value of the NETLOGON_SAM_LOGON_RESPONSE_EX.DcSiteName field if it is present, or to NULL if the NETLOGON_SAM_LOGON_RESPONSE_EX.DcSiteName field is not present.

  • The DomainControllerInfo.ClientSiteName field MUST be set to the value of the NETLOGON_SAM_LOGON_RESPONSE_EX.ClientSiteName field if it is present, or to NULL if the NETLOGON_SAM_LOGON_RESPONSE_EX.ClientSiteName field is not present.

    • If the NETLOGON_SAM_LOGON_RESPONSE_EX.NextClosestSiteName field is present, the value MUST be saved in the NextClosestSiteName ADM element.

If a satisfactory NETLOGON_SAM_LOGON_RESPONSE_NT40 ([MS-ADTS] section 6.3.1.7) response message is received in response to the mailslot messages, the DsrGetDcNameEx2 call populates the returned DOMAIN_CONTROLLER_INFOW structure (section 2.2.1.2.1) as follows:

  • The DomainControllerInfo.DomainControllerName field MUST be set to the NETLOGON_SAM_LOGON_RESPONSE_NT40.UnicodeLogonServer field.

  • The DomainControllerInfo.DomainControllerAddress field MUST be set to the NETLOGON_SAM_LOGON_RESPONSE_NT40.UnicodeLogonServer field.

  • The DomainControllerInfo.DomainControllerAddressType field MUST be set to 0x00000002.

  • The DomainControllerInfo.DomainGuid field MUST be set to NULL.

  • The DomainControllerInfo.DomainName field MUST be set to the NETLOGON_SAM_LOGON_RESPONSE_NT40.UnicodeLogonServer field.

  • The DomainControllerInfo.DnsForestName field MUST be set to NULL.

  • The DomainControllerInfo.Flags field MUST have the A and H flags set if the response is to a PDC query; otherwise it MUST be set to 0x00000000.

  • The DomainControllerInfo.DcSiteName field MUST be set to NULL.

  • The DomainControllerInfo.ClientSiteName field MUST be set to NULL.

If the AccountName parameter is not NULL, the response message validation adds the following check: if the DC response is received indicating the lack of an account, as specified in [MS-ADTS] sections 6.3.3 and 6.3.5, the server MUST return ERROR_NO_SUCH_USER.

If the server successfully locates a DC for the requested capabilities, it saves the result in the LocatedDCsCache. If a DC for the domain cannot be located, the server saves the result in the FailedDiscoveryCache.