PFNPROCESSGROUPPOLICYEX-Rückruffunktion (userenv.h)

Artikel
03/13/2024

Die ProcessGroupPolicyEx-Funktion ist eine anwendungsdefinierte Rückruffunktion, die beim Anwenden von Richtlinien verwendet wird. Diese erweiterte Funktion unterstützt auch die Protokollierung von RSoP-Daten (Resultant Set of Policy). Der PFNPROCESSGROUPPOLICYEX-Typ definiert einen Zeiger auf diese Rückruffunktion. ProcessGroupPolicyEx ist ein Platzhalter für den anwendungsdefinierte Funktionsnamen.

Syntax

PFNPROCESSGROUPPOLICYEX Pfnprocessgrouppolicyex;

DWORD Pfnprocessgrouppolicyex(
  [in]  DWORD dwFlags,
  [in]  HANDLE hToken,
  [in]  HKEY hKeyRoot,
  [in]  PGROUP_POLICY_OBJECT pDeletedGPOList,
  [in]  PGROUP_POLICY_OBJECT pChangedGPOList,
  [in]  ASYNCCOMPLETIONHANDLE pHandle,
  [in]  BOOL *pbAbort,
  [in]  PFNSTATUSMESSAGECALLBACK pStatusCallback,
  [in]  IWbemServices *pWbemServices,
  [out] HRESULT *pRsopStatus
)
{...}

Parameter

[in] dwFlags

Dieser Parameter kann mindestens eins der folgenden Flags sein.

GPO_INFO_FLAG_MACHINE

Wenden Sie eine Computerrichtlinie anstelle einer Benutzerrichtlinie an.

GPO_INFO_FLAG_BACKGROUND

Führen Sie eine Hintergrundaktualisierung der Richtlinie aus. Weitere Informationen finden Sie im Text nach dieser Liste.

GPO_INFO_FLAG_ASYNC_FOREGROUND

Führen Sie eine asynchrone Vordergrundaktualisierung der Richtlinie aus. Weitere Informationen finden Sie im Text nach dieser Liste. Weitere Informationen zur Vordergrundrichtlinienanwendung finden Sie unter Erstverarbeitung von Gruppenrichtlinie.

GPO_INFO_FLAG_SLOWLINK

Die Richtlinie wird über eine langsame Verbindung angewendet.

GPO_INFO_FLAG_VERBOSE

Schreiben einer ausführlichen Ausgabe in das Ereignisprotokoll.

GPO_INFO_FLAG_NOCHANGES

Es wurden keine Änderungen am Gruppenrichtlinienobjekt erkannt.

GPO_INFO_FLAG_LINKTRANSITION

Zwischen Richtlinienanwendungen wurde eine Änderung der Linkgeschwindigkeit erkannt.

GPO_INFO_FLAG_LOGRSOP_TRANSITION

Zwischen der Anwendung der vorherigen Richtlinie und der Anwendung der aktuellen Richtlinie wurde eine Änderung der RSoP-Protokollierung erkannt.

GPO_INFO_FLAG_FORCED_REFRESH

Eine erzwungene Richtlinienaktualisierung wird angewendet.

GPO_INFO_FLAG_SAFEMODE_BOOT

Flag "Abgesicherter Modus".

Das GPO_INFO_FLAG_BACKGROUND-Flag und das GPO_INFO_FLAG_ASYNC_FOREGROUND-Flag können beide festgelegt werden. Da Richtlinien während einer Hintergrundaktualisierung immer asynchron angewendet werden, behandeln die meisten Erweiterungen eine asynchrone Vordergrundaktualisierung auf die gleiche Weise, wie sie eine Hintergrundaktualisierung verarbeiten. Daher müssen sie nicht nach dem GPO_INFO_FLAG_ASYNC_FOREGROUND-Flag suchen. In Fällen, in der eine Erweiterung zwischen einer Hintergrundaktualisierung der Richtlinie und einer asynchronen Aktualisierung der Richtlinie im Vordergrund unterscheiden muss, kann die Erweiterung das flag GPO_INFO_FLAG_ASYNC_FOREGROUND überprüfen.

[in] hToken

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 Clientidentitätswechsel.

[in] hKeyRoot

Handle mit dem HKEY_LOCAL_MACHINE oder HKEY_CURRENT_USER Registrierungsschlüssel.

[in] pDeletedGPOList

Zeiger, der die Liste der gelöschten Gruppenrichtlinienobjektstrukturen empfängt. Weitere Informationen finden Sie unter GROUP_POLICY_OBJECT.

[in] pChangedGPOList

Zeiger, der die Liste der geänderten Gruppenrichtlinienobjektstrukturen empfängt. Weitere Informationen finden Sie unter GROUP_POLICY_OBJECT.

[in] pHandle

Asynchrones Vervollständigungshandle. Wenn die Rückruffunktion die asynchrone Verarbeitung nicht unterstützt, ist dieses Handle null.

[in] pbAbort

Gibt an, ob die Verarbeitung von Gruppenrichtlinienobjekten fortgesetzt werden soll. Wenn dieser Parameter TRUE ist, wird die GPO-Verarbeitung beendet. Wenn dieser Parameter FALSE ist, wird die GPO-Verarbeitung fortgesetzt.

[in] pStatusCallback

Zeiger auf eine StatusMessageCallback-Rückruffunktion, die status Nachrichten anzeigt. Dieser Parameter kann in bestimmten Fällen NULL sein. Wenn das System beispielsweise eine Richtlinie im Hintergrund anwendet, ist die status Benutzeroberfläche nicht vorhanden, und die Anwendung kann keine status anzuzeigenden Nachrichten senden. Weitere Informationen finden Sie im folgenden Abschnitt "Hinweise".

[in] pWbemServices

Gibt einen WMI-Dienstzeiger auf den RSoP-Namespace an, in den die Richtliniendaten geschrieben werden sollen. Dieser Parameter ist NULL , wenn die RSoP-Protokollierung deaktiviert ist, was angibt, dass die Erweiterung RSoP-Daten nicht protokollieren sollte.

[out] pRsopStatus

Zeiger auf einen HRESULT-Rückgabecode , der angibt, ob die RSoP-Protokollierung erfolgreich war.

Rückgabewert

Wenn die Richtlinie erfolgreich angewendet wurde, geben Sie ERROR_SUCCESS zurück. Wenn keine Änderungen an der GPO-Liste vorgenommen werden und die Erweiterung erneut aufgerufen werden soll, geben Sie ERROR_OVERRIDE_NOCHANGES zurück. Durch die Rückgabe ERROR_OVERRIDE_NOCHANGES wird sichergestellt, dass die Erweiterung erneut aufgerufen wird, auch wenn der Registrierungswert NoGPOListChanges festgelegt ist. (Weitere Informationen zu diesem Registrierungswert finden Sie unter Hinweise.)

Gibt ERROR_SYNC_FOREGROUND_REFRESH_REQUIRED zurück, wenn die Funktion für eine asynchrone Vordergrundaktualisierung der Richtlinie aufgerufen wurde, die Richtlinie während der asynchronen Aktualisierung jedoch nicht angewendet werden konnte. Die Rückgabe ERROR_SYNC_FOREGROUND_REFRESH_REQUIRED gibt an, dass die Funktion für eine synchrone Vordergrundaktualisierung der Richtlinie erneut aufgerufen werden muss.

Andernfalls wird ein Systemfehlercode zurückgegeben.

Hinweise

Weitere Informationen finden Sie unter Implementieren einer clientseitigen Gruppenrichtlinie-Erweiterung.

Das System ruft diese Funktion im Kontext des LocalSystem-Kontos auf, das über umfangreiche Berechtigungen auf dem lokalen Computer verfügt. Um Netzwerkressourcen zu verwenden, müssen Sie die Identität des Benutzers oder Computers annehmen, indem Sie das im hToken-Parameter angegebene Token verwenden.

Um diese Rückruffunktion zu registrieren, erstellen Sie einen Unterschlüssel unter dem folgenden Registrierungsschlüssel:

HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows NT\Currentversion\Winlogon\GPExtensions\ClientExtensionGuid

Der Unterschlüssel sollte eine GUID sein, sodass er eindeutig ist. Sie sollte die folgenden Werte enthalten.

Sie sollten die status Meldung nur aktualisieren, wenn Sie die Richtlinie synchron anwenden. Auf diese Weise können Sie während einer langwierigen Richtlinienanwendung Feedback und Diagnose geben. Um die status Nachrichtenrückruffunktion zu verwenden, müssen Sie überprüfen, ob pStatusCallback nicht NULL ist. Laden Sie dann Ihre Nachrichtenzeichenfolgenressource. Wenn Sie die status-Funktion aufrufen, müssen Sie angeben, ob die Zeichenfolge ausführlich ist. Wenn die Zeichenfolge ausführlich ist, überprüft die Rückruffunktion, ob sich der Computer im ausführlichen Modus befindet, und zeigt die Meldung an. Weitere Informationen finden Sie unter StatusMessageCallback.

Warnung Rufen Sie die pStatusCallback-Funktion nicht aus einem Hintergrundthread auf, oder Sie können die status Nachricht eines anderen Threads überschreiben.

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Windows Vista
Unterstützte Mindestversion (Server)	Windows Server 2008
Zielplattform	Windows
Kopfzeile	userenv.h