Fonction de rappel PFNPROCESSGROUPPOLICY (userenv.h)

Article
08/26/2023

La fonction ProcessGroupPolicy est une fonction de rappel définie par l’application utilisée lors de l’application de la stratégie. Le type PFNPROCESSGROUPPOLICY définit un pointeur vers cette fonction de rappel. ProcessGroupPolicy est un espace réservé pour le nom de fonction défini par l’application.

Cette fonction de rappel n’est pas utile pour le traitement RSoP (Resultant Set of Policy) ; utilisez la fonction de rappel ProcessGroupPolicyEx à la place.

Syntaxe

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
)
{...}

Paramètres

[in] dwFlags

Ce paramètre peut être un ou plusieurs des indicateurs suivants.

GPO_INFO_FLAG_MACHINE

Appliquez une stratégie d’ordinateur plutôt qu’une stratégie utilisateur.

GPO_INFO_FLAG_BACKGROUND

Effectuez une actualisation en arrière-plan de la stratégie.

GPO_INFO_FLAG_ASYNC_FOREGROUND

Effectuez une actualisation asynchrone au premier plan de la stratégie. Pour plus d’informations sur l’application de stratégie de premier plan, consultez Traitement initial de stratégie de groupe.

GPO_INFO_FLAG_SLOWLINK

La stratégie est appliquée sur une liaison lente.

GPO_INFO_FLAG_VERBOSE

Écrivez une sortie détaillée dans le journal des événements.

GPO_INFO_FLAG_NOCHANGES

Aucune modification de l’objet de stratégie de groupe n’a été détectée.

GPO_INFO_FLAG_LINKTRANSITION

Une modification de la vitesse de liaison a été détectée entre les applications de stratégie.

GPO_INFO_FLAG_LOGRSOP_TRANSITION

Une modification de la journalisation RSoP a été détectée entre l’application de la stratégie précédente et l’application de la stratégie actuelle.

GPO_INFO_FLAG_FORCED_REFRESH

Une actualisation forcée de la stratégie est appliquée.

GPO_INFO_FLAG_SAFEMODE_BOOT

Indicateur de mode sans échec.

[in] hToken

Jeton pour l’utilisateur ou l’ordinateur, retourné par la fonction LogonUser, CreateRestrictedToken, DuplicateToken, OpenProcessToken ou OpenThreadToken . Ce jeton doit avoir un accès TOKEN_IMPERSONATE et TOKEN_QUERY . Pour plus d’informations, consultez Droits d’accès pour les objets Access-Token et emprunt d’identité du client.

[in] hKeyRoot

Gérez la clé de Registre HKEY_LOCAL_MACHINE ou HKEY_CURRENT_USER .

[in] pDeletedGPOList

Pointeur qui reçoit la liste des structures d’objet de stratégie de groupe supprimées. Pour plus d’informations, consultez GROUP_POLICY_OBJECT.

[in] pChangedGPOList

Pointeur qui reçoit la liste des structures d’objet de stratégie de groupe modifiées. Pour plus d’informations, consultez GROUP_POLICY_OBJECT.

[in] pHandle

Handle d’achèvement asynchrone. Si la fonction de rappel ne prend pas en charge le traitement asynchrone, ce handle est égal à zéro.

[in] pbAbort

Spécifie s’il faut continuer à traiter les objets de stratégie de groupe. Si ce paramètre a la valeur TRUE, le traitement de l’objet de stratégie de groupe cesse. Si ce paramètre a la valeur FALSE, le traitement des objets de stratégie de groupe se poursuit.

[in] pStatusCallback

Pointeur vers une fonction de rappel StatusMessageCallback qui affiche status messages. Ce paramètre peut être NULL dans certains cas. Par exemple, si le système applique la stratégie en arrière-plan, l’interface utilisateur status n’est pas présente et l’application ne peut pas envoyer status messages à afficher. Pour plus d'informations, consultez la section Notes qui suit.

Valeur retournée

Si la stratégie a été appliquée avec succès, retournez ERROR_SUCCESS. Si aucune modification n’est apportée à la liste des objets de stratégie de groupe et que l’extension doit être appelée à nouveau, retournez ERROR_OVERRIDE_NOCHANGES. Le retour ERROR_OVERRIDE_NOCHANGES garantit que l’extension est appelée à nouveau, même si la valeur de Registre NoGPOListChanges est définie. (Pour plus d’informations sur cette valeur de Registre, consultez Remarques.) Sinon, retournez un code d’erreur système.

Remarques

Pour plus d’informations, consultez Implémentation d’une extension côté client stratégie de groupe.

Le système appelle cette fonction dans le contexte du compte LocalSystem, qui dispose de privilèges étendus sur l’ordinateur local. Pour utiliser des ressources réseau, vous devez emprunter l’identité de l’utilisateur ou de l’ordinateur à l’aide du jeton fourni dans le paramètre hToken .

Pour inscrire cette fonction de rappel, créez une sous-clé sous la clé de Registre suivante :

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

La sous-clé doit être un GUID, afin qu’elle soit unique. Il doit contenir les valeurs suivantes.

Vous devez mettre à jour le message status uniquement si vous appliquez la stratégie de manière synchrone. Cela vous permet de fournir des commentaires et des diagnostics pendant une longue application de stratégie. Pour utiliser la fonction de rappel de message status, vous devez vérifier que pStatusCallback n’est pas NULL. Chargez ensuite votre ressource de chaîne de message. Lorsque vous appelez la fonction status, vous devez indiquer si la chaîne est détaillée. Si la chaîne est détaillée, la fonction de rappel vérifie que l’ordinateur est en mode détaillé et affiche le message. Pour plus d’informations, consultez StatusMessageCallback.

Avertissement N’appelez pas la fonction pStatusCallback à partir d’un thread d’arrière-plan, car vous pouvez remplacer le message status d’un autre thread.