GetGPOListW-Funktion (userenv.h)

Die GetGPOList-Funktion ruft die Liste der Gruppenrichtlinienobjekte für den angegebenen Benutzer oder Computer ab. Diese Funktion kann auf zwei Arten aufgerufen werden: Erstens können Sie das Token für den Benutzer oder Computer verwenden, oder zweitens können Sie 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, das von den Funktionen LogonUser, CreateRestrictedToken, DuplicateToken, OpenProcessToken oder OpenThreadToken zurückgegeben wird. Dieses Token muss über TOKEN_IMPERSONATE und TOKEN_QUERY Zugriff verfügen. Weitere Informationen finden Sie unter Zugriffsrechte für Access-Token-Objekte und im folgenden Abschnitt "Hinweise".

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=user, OU=users, 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 Name des Domänencontrollers kann mithilfe der DsGetDcName-Funktion abgerufen werden, wobei DS_DIRECTORY_SERVICE_REQUIRED im 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 Standorts verwendet wird. Das Format des Namens ist "\\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 Informationsabrufs verwendet werden. Wenn Sie GPO_LIST_FLAG_MACHINE angeben, ruft die Funktion Richtlinieninformationen für den Computer ab. Wenn Sie GPO_LIST_FLAG_MACHINE nicht angeben, ruft die Funktion Richtlinieninformationen für den Benutzer ab.

Wenn Sie GPO_LIST_FLAG_SITEONLY gibt die Funktion nur Standortinformationen für den Computer oder Benutzer zurück.

[out] pGPOList

Ein Zeiger, der die Liste der Gruppenrichtlinienobjektstrukturen 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 fehlerhaft ist, ist der Rückgabewert null. Um erweiterte Fehlerinformationen zu erhalten, rufen Sie GetLastError auf.

Hinweise

Die GetGPOList-Funktion ist für die Verwendung durch Dienste vorgesehen, die im Namen eines Benutzers oder Computers handeln. Der Dienst ruft diese Funktion auf, um eine Liste von Gruppenrichtlinienobjekten abzurufen, und überprüft dann jedes Gruppenrichtlinienobjekt auf dienstspezifische Richtlinien.

Das Aufrufen dieser Funktion mit einem Token bietet die genaueste Liste. Das System kann eine 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 der Aufruf 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 beim Aufrufen von GetGPOList die genaueste Liste der Gruppenrichtlinienobjekte für einen Computer zu erhalten, muss der Aufrufer Lesezugriff auf jede Organisationseinheit und jeden Standort in der Computerdomäne haben und außerdem Gruppenrichtlinie Zugriff auf alle Gruppenrichtlinienobjekte lesen und anwenden, die mit den Websites, Domänen oder Organisationseinheiten 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 Gruppenrichtlinienobjekten wäre das Aufrufen der RsopCreateSession-Methode der RsopPlanningModeProvider WMI-Klasse. Die -Methode kann in einem hypothetischen Szenario resultierende Richtliniendaten für einen Computer oder ein Benutzerkonto generieren.

Rufen Sie die FreeGPOList-Funktion auf, um die GPO-Liste frei zu geben, wenn Sie die Verarbeitung abgeschlossen haben.

Im Allgemeinen sollten Sie GetGPOList mit einem Token aufrufen, wenn Sie eine Liste von Gruppenrichtlinienobjekten 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);
      }

In der Regel können Sie GetGPOList mit dem Computernamen und dem Domänencontrollernamen aufrufen, wie im folgenden Codeausschnitt veranschaulicht, um eine Liste von Gruppenrichtlinienobjekten für einen Computer abzurufen.

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 Gruppenrichtlinienobjekte abzurufen, die für einen bestimmten Benutzer oder Computer und die Erweiterung angewendet wurden.

Hinweis

Der Userenv.h-Header definiert GetGPOList als Alias, der die ANSI- oder Unicode-Version dieser Funktion basierend auf der Definition der UNICODE-Präprozessorkonstante automatisch 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
Unterstützte Mindestversion (Client)	Windows Vista
Unterstützte Mindestversion (Server)	Windows Server 2008
Zielplattform	Windows
Kopfzeile	userenv.h
Bibliothek	Userenv.lib
DLL	Userenv.dll

Weitere Informationen

Dsgetdcname

FreeGPOList

GROUP_POLICY_OBJECT

Gruppenrichtlinie-Funktionen

Übersicht über Gruppenrichtlinien