GetGPOListW-Funktion (userenv.h)
Die GetGPOList Funktion ruft die Liste der GPOs für den angegebenen Benutzer oder Computer ab. Diese Funktion kann auf zwei Arten aufgerufen werden: Zuerst können Sie das Token für den Benutzer oder Computer verwenden oder zweitens den Namen des Benutzers oder Computers und den Namen des Domänencontrollers verwenden.
Syntax
USERENVAPI BOOL GetGPOListW(
[in] HANDLE hToken,
[in] LPCWSTR lpName,
[in] LPCWSTR lpHostName,
[in] LPCWSTR lpComputerName,
[in] DWORD dwFlags,
[out] PGROUP_POLICY_OBJECTW *pGPOList
);
Parameter
[in] hToken
Ein Token für den Benutzer oder Computer, zurückgegeben von der LogonUser, CreateRestrictedToken, DuplicateToken, OpenProcessTokenoder OpenThreadToken Funktion. Dieses Token muss über TOKEN_IMPERSONATE und TOKEN_QUERY Zugriff verfügen. Weitere Informationen finden Sie unter Access Rights for Access-Token Objects und the following Remarks section.
Wenn dieser Parameter NULL-ist, müssen Sie Werte für die parameter lpName und lpHostName angeben.
[in] lpName
Ein Zeiger auf den Benutzer- oder Computernamen im vollqualifizierten Distinguished Name-Format (z. B. "CN=Benutzer, OU=Benutzer, DC=contoso, DC=com").
Wenn der hToken Parameter nicht NULL-ist, muss dieser Parameter NULL-sein.
[in] lpHostName
Ein DNS-Domänenname (bevorzugt) oder ein Domänencontrollername. Der Domänencontrollername kann mithilfe der DsGetDcName--Funktion abgerufen werden, wobei DS_DIRECTORY_SERVICE_REQUIRED in den Flags Parameter angegeben wird.
Wenn der hToken Parameter nicht NULL-ist, muss dieser Parameter NULL-sein.
[in] lpComputerName
Ein Zeiger auf den Namen des Computers, der zum Ermitteln des Standortstandorts verwendet wird. Das Format des Namens lautet "\\computer_name". Wenn dieser Parameter NULL-ist, wird der name des lokalen Computers verwendet.
[in] dwFlags
Ein Wert, der zusätzliche Flags angibt, die zum Steuern des Abrufs von Informationen verwendet werden. Wenn Sie GPO_LIST_FLAG_MACHINEangeben, ruft die Funktion Richtlinieninformationen für den Computer ab. Wenn Sie GPO_LIST_FLAG_MACHINEnicht angeben, ruft die Funktion Richtlinieninformationen für den Benutzer ab.
Wenn Sie angeben, GPO_LIST_FLAG_SITEONLY gibt die Funktion nur Websiteinformationen für den Computer oder Benutzer zurück.
[out] pGPOList
Ein Zeiger, der die Liste der GPO-Strukturen empfängt. Weitere Informationen finden Sie unter GROUP_POLICY_OBJECT.
Rückgabewert
Wenn die Funktion erfolgreich ist, ist der Rückgabewert ungleich Null.
Wenn die Funktion fehlschlägt, ist der Rückgabewert null. Rufen Sie GetLastErrorauf, um erweiterte Fehlerinformationen zu erhalten.
Bemerkungen
Die GetGPOList- Funktion ist für die Verwendung durch Dienste vorgesehen, die im Auftrag eines Benutzers oder Computers handeln. Der Dienst ruft diese Funktion auf, um eine Liste von GPOs abzurufen, und überprüft dann jedes Gruppenrichtlinienobjekt auf dienstspezifische Richtlinien.
Das Aufrufen dieser Funktion mit einem Token stellt die genaueste Liste bereit. Das System kann die Zugriffsüberprüfung für den Benutzer oder Computer durchführen. Das Aufrufen dieser Funktion mit dem Benutzer- oder Computernamen und dem Domänencontrollernamen ist schneller als das Aufrufen mit einem Token. Wenn das Token jedoch nicht angegeben ist, verwendet das System den Sicherheitszugriff des Aufrufers, was bedeutet, dass die Liste für den vorgesehenen Benutzer oder Computer möglicherweise nicht vollständig korrekt ist.
Um die genaueste Liste der GPOs für einen Computer beim Aufrufen von GetGPOList-abzurufen, muss der Aufrufer Lesezugriff auf jede OU und jeden Standort in der Computerdomäne haben und auch Gruppenrichtlinienzugriff auf alle Gruppenrichtlinienobjekte lesen und anwenden, die mit den Websites, Domänen oder OUs dieser Domäne verknüpft sind. Ein Beispiel für einen Aufrufer wäre ein Dienst, der auf dem Computer ausgeführt wird, dessen Name im lpName Parameter angegeben ist. Eine alternative Methode zum Abrufen einer Liste von GPOs wäre das Aufrufen der RsopCreateSession Methode der RsopPlanningModeProvider WMI-Klasse. Die Methode kann resultierende Richtliniendaten für einen Computer oder ein Benutzerkonto in einem hypothetischen Szenario generieren.
Rufen Sie die FreeGPOList Funktion auf, um die GPO-Liste freizuschalten, wenn Sie die Verarbeitung abgeschlossen haben.
Im Allgemeinen sollten Sie GetGPOList- mit einem Token aufrufen, wenn Sie eine Liste von GPOs für einen Benutzer abrufen, wie im folgenden Codebeispiel gezeigt.
LPGROUP_POLICY_OBJECT pGPOList;
if (GetGPOList (hToken, NULL, NULL, NULL, 0, &pGPOList))
{
// Perform processing here.
//
// Free the GPO list when you finish processing.
FreeGPOList (pGPOList);
}
Normalerweise können Sie zum Abrufen einer Liste von GPOs für einen Computer GetGPOList- mit dem Computernamen und dem Domänencontrollernamen aufrufen, wie im folgenden Codeausschnitt gezeigt.
LPGROUP_POLICY_OBJECT pGPOList;
if (GetGPOList (NULL, lpMachineName, lpHostName, lpMachineName, GPO_LIST_FLAG_MACHINE, &pGPOList))
{
// Perform processing here.
//
// Free the GPO list when you finish processing.
FreeGPOList (pGPOList);
}
Rufen Sie die GetAppliedGPOList-Funktion auf, um die Liste der GPOs abzurufen, die für einen bestimmten Benutzer oder Computer und eine Bestimmte Erweiterung angewendet wurden.
Anmerkung
Der Header "userenv.h" definiert GetGPOList als Alias, der automatisch die ANSI- oder Unicode-Version dieser Funktion basierend auf der Definition der UNICODE-Präprozessorkonstante auswählt. Das Mischen der Verwendung des codierungsneutralen Alias mit Code, der nicht codierungsneutral ist, kann zu Nichtübereinstimmungen führen, die zu Kompilierungs- oder Laufzeitfehlern führen. Weitere Informationen finden Sie unter Konventionen für Funktionsprototypen.
Anforderungen
| Anforderung | Wert |
|---|---|
| mindestens unterstützte Client- | Windows Vista |
| mindestens unterstützte Server- | Windows Server 2008 |
| Zielplattform- | Fenster |
| Header- | userenv.h |
| Library | Userenv.lib |
| DLL- | Userenv.dll |