PFNPROCESSGROUPPOLICY-Rückruffunktion (userenv.h)

Artikel
08/26/2023

Die ProcessGroupPolicy-Funktion ist eine anwendungsdefinierte Rückruffunktion, die beim Anwenden von Richtlinien verwendet wird. Der PFNPROCESSGROUPPOLICY-Typ definiert einen Zeiger auf diese Rückruffunktion. ProcessGroupPolicy ist ein Platzhalter für den anwendungsdefinierte Funktionsnamen.

Diese Rückruffunktion ist für die Verarbeitung von Richtlinienergebnissen (Resultant Set of Policy, RSoP) nicht nützlich. Verwenden Sie stattdessen die Rückruffunktion ProcessGroupPolicyEx .

Syntax

PFNPROCESSGROUPPOLICY Pfnprocessgrouppolicy;

DWORD Pfnprocessgrouppolicy(
  [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
)
{...}

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.

GPO_INFO_FLAG_ASYNC_FOREGROUND

Führen Sie eine asynchrone Vordergrundaktualisierung der Richtlinie aus. 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".

[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".

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.) 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, da Sie die status Nachricht eines anderen Threads überschreiben können.

Anforderungen

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