GetGPOListA-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 GetGPOListA(
  [in]  HANDLE                hToken,
  [in]  LPCSTR                lpName,
  [in]  LPCSTR                lpHostName,
  [in]  LPCSTR                lpComputerName,
  [in]  DWORD                 dwFlags,
  [out] PGROUP_POLICY_OBJECTA *pGPOList
);

Parameter

[in] hToken

Ein Token für den Benutzer oder Computer, das von der Funktion 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 lokale Computername 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 Auftrag 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 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 beabsichtigten 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 Gruppenrichtlinienobjektliste 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);
      }

Zum Abrufen einer Liste von Gruppenrichtlinienobjekten für einen Computer können Sie in der Regel GetGPOList mit dem Computernamen und dem Domänencontrollernamen aufrufen, wie im folgenden Codeausschnitt veranschaulicht.

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);
      }

Um die Liste der Gruppenrichtlinienobjekte abzurufen, die für einen bestimmten Benutzer oder Computer und eine bestimmte Erweiterung angewendet wurden, rufen Sie die GetAppliedGPOList-Funktion auf.

Hinweis

Der userenv.h-Header 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 nicht codierungsneutralem Code kann zu Nichtübereinstimmungen führen, die zu Kompilierungs- oder Laufzeitfehlern führen. Weitere Informationen finden Sie unter Konventionen für Funktionsprototypen.

Anforderungen

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