Opsommen van domeincontrollers

In eerdere versies van Windows kon een toepassing slechts één domeincontroller in een domein verkrijgen door DsGetDcNameaan te roepen. Er was geen manier om te voorspellen welke domeincontroller zou worden opgehaald of om een lijst met de domeincontrollers te verkrijgen. Met Windows kan een toepassing de domeincontrollers in een domein inventariseren met behulp van de functies DsGetDcOpen, DsGetDcNexten DsGetDcClose.

Als u een domeincontroller wilt inventariseren, roept u DsGetDcOpenaan. Deze functie gebruikt parameters die het domein definiëren om te inventariseren en andere opsommingsopties. DsGetDcOpen biedt een contextgreep voor domeininventarisatie die wordt gebruikt om de opsommingsbewerking te identificeren wanneer DsGetDcNext- en DsGetDcClose- worden aangeroepen.

De DsGetDcNext--functie wordt aangeroepen met de contextgreep voor domeinumeratie om de volgende domeincontroller op te halen in de opsomming. De eerste keer dat deze functie wordt aangeroepen, wordt de eerste domeincontroller in de opsomming opgehaald. De tweede keer dat deze functie wordt aangeroepen, wordt de tweede domeincontroller in de opsomming opgehaald. Dit proces wordt herhaald totdat DsGetDcNext-ERROR_NO_MORE_ITEMSretourneert, dat het einde van de opsomming aangeeft.

De functie DsGetDcNext inventariseert de domeincontrollers in twee groepen. De eerste groep bevat de domeincontrollers die betrekking hebben op de site van de computer waarop de functie wordt uitgevoerd en de tweede groep bevat de domeincontrollers die niet betrekking hebben op de site van de computer waarop de functie wordt uitgevoerd. Als de vlag DS_NOTIFY_AFTER_SITE_RECORDS is opgegeven in de parameter OptionFlags in DsGetDcOpen, retourneert de functie DsGetDcNextERROR_FILEMARK_DETECTED nadat alle sitespecifieke domeincontrollers zijn opgehaald. DsGetDcNext- begint vervolgens met het inventariseren van de tweede groep, die alle domeincontrollers in het domein bevat, inclusief de sitespecifieke domeincontrollers in de eerste groep.

Domeincontrollers die de site verwerken van de computer waarop de functie wordt uitgevoerd, worden eerst geïnventariseerd, gevolgd door de domeincontrollers die de site van de computer waarop de functie wordt uitgevoerd, niet bedekt. Een domeincontroller wordt gezegd om een site te dekken als de domeincontroller is geconfigureerd om zich op die site te bevinden of als de domeincontroller zich op een site bevindt die het dichtst bij de betreffende site ligt in termen van de geconfigureerde kosten voor de koppeling tussen sites. Als er domeincontrollers zijn in zowel de groep domeincontrollers die betrekking hebben op als de groep domeincontrollers die niet op de computersite vallen, worden domeincontrollers binnen de groep geretourneerd in volgorde van hun geconfigureerde prioriteiten en gewichten die zijn opgegeven in DNS. Domeincontrollers met een lagere numerieke prioriteit worden eerst binnen een groep geretourneerd. Als er binnen een sitegerelateerde groep een subgroep van verschillende domeincontrollers met dezelfde prioriteit is, worden domeincontrollers geretourneerd in een gewogen willekeurige volgorde waarbij domeincontrollers met een hoger gewicht eerst meer kans hebben om als eerste te worden geretourneerd. De sites, prioriteiten en gewichten worden geconfigureerd door de domeinbeheerder om effectieve prestaties en taakverdeling te bereiken tussen meerdere domeincontrollers die beschikbaar zijn in het domein. Als gevolg hiervan profiteren toepassingen die gebruikmaken van de DsGetDcOpen/DsGetDcNext/DsGetDcClose functies automatisch van deze optimalisaties.

Wanneer de opsomming is voltooid of niet meer vereist is, moet de opsomming worden gesloten door DsGetDcClose- aan te roepen met de contextgreep voor domeininventarisatie.

Als u de opsomming opnieuw wilt instellen, moet u de huidige opsomming sluiten door DsGetDcClose- aan te roepen en de opsomming vervolgens opnieuw te openen door DsGetDcOpen opnieuw aan te roepen.

Voorbeeld

In het volgende codevoorbeeld ziet u hoe u deze functies gebruikt om de domeincontrollers in het lokale domein op te sommen.

DWORD dwRet;
PDOMAIN_CONTROLLER_INFO pdcInfo;

// Get a domain controller for the domain this computer is on.
dwRet = DsGetDcName(NULL, NULL, NULL, NULL, 0, &pdcInfo);
if(ERROR_SUCCESS == dwRet)
{
    HANDLE hGetDc;
    
    // Open the enumeration.
    dwRet = DsGetDcOpen(    pdcInfo->DomainName,
                            DS_NOTIFY_AFTER_SITE_RECORDS,
                            NULL,
                            NULL,
                            NULL,
                            0,
                            &hGetDc);
    if(ERROR_SUCCESS == dwRet)
    {
        LPTSTR pszDnsHostName;

        /*
        Enumerate each domain controller and print its name to the 
        debug window.
        */
        while(TRUE)
        {
            ULONG ulSocketCount;
            LPSOCKET_ADDRESS rgSocketAddresses;

            dwRet = DsGetDcNext(
                hGetDc, 
                &ulSocketCount, 
                &rgSocketAddresses, 
                &pszDnsHostName);
            
            if(ERROR_SUCCESS == dwRet)
            {
                OutputDebugString(pszDnsHostName);
                OutputDebugString(TEXT("\n"));
                
                // Free the allocated string.
                NetApiBufferFree(pszDnsHostName);

                // Free the socket address array.
                LocalFree(rgSocketAddresses);
            }
            else if(ERROR_NO_MORE_ITEMS == dwRet)
            {
                // The end of the list has been reached.
                break;
            }
            else if(ERROR_FILEMARK_DETECTED == dwRet)
            {
                /*
                DS_NOTIFY_AFTER_SITE_RECORDS was specified in 
                DsGetDcOpen and the end of the site-specific 
                records was reached.
                */
                OutputDebugString(
                  TEXT("End of site-specific domain controllers\n"));
                continue;
            }
            else
            {
                // Some other error occurred.
                break;
            }
        }
        
        // Close the enumeration.
        DsGetDcClose(hGetDc);
    }
    
    // Free the DOMAIN_CONTROLLER_INFO structure. 
    NetApiBufferFree(pdcInfo);
}