Fonction de rappel PFNPROCESSGROUPPOLICYEX (userenv.h)

Article
08/26/2023

La fonction ProcessGroupPolicyEx est une fonction de rappel définie par l’application utilisée lors de l’application de la stratégie. Cette fonction étendue prend également en charge la journalisation des données RSoP (Resultant Set of Policy). Le type PFNPROCESSGROUPPOLICYEX définit un pointeur vers cette fonction de rappel. ProcessGroupPolicyEx est un espace réservé pour le nom de fonction défini par l’application.

Syntaxe

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

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. Pour plus d’informations, consultez le texte suivant cette liste.

GPO_INFO_FLAG_ASYNC_FOREGROUND

Effectuez une actualisation asynchrone au premier plan de la stratégie. Pour plus d’informations, consultez le texte suivant cette liste. 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 un lien lent.

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.

L’indicateur GPO_INFO_FLAG_BACKGROUND et l’indicateur GPO_INFO_FLAG_ASYNC_FOREGROUND peuvent être définis. Étant donné que les stratégies sont toujours appliquées de manière asynchrone pendant une actualisation en arrière-plan, la plupart des extensions gèrent une actualisation de premier plan asynchrone de la même manière qu’elles gèrent une actualisation en arrière-plan. Par conséquent, ils n’ont pas besoin de case activée pour l’indicateur GPO_INFO_FLAG_ASYNC_FOREGROUND. Dans les cas où une extension doit faire la distinction entre une actualisation en arrière-plan de la stratégie et une actualisation asynchrone au premier plan de la stratégie, l’extension peut case activée pour l’indicateur GPO_INFO_FLAG_ASYNC_FOREGROUND.

[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 l’emprunt d’identité client.

[in] hKeyRoot

Gérez la HKEY_LOCAL_MACHINE ou la clé de Registre 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 de saisie semi-automatique 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 des objets de stratégie de groupe cesse. Si ce paramètre a la valeur FALSE, le traitement des objets de stratégie de groupe continue.

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

[in] pWbemServices

Spécifie un pointeur de services WMI vers l’espace de noms RSoP dans lequel les données de stratégie doivent être écrites. Ce paramètre a la valeur NULL lorsque la journalisation RSoP est désactivée, ce qui indique que l’extension ne doit pas journaliser les données RSoP.

[out] pRsopStatus

Pointeur vers un code de retour HRESULT qui indique si la journalisation RSoP a réussi.

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

Retourne ERROR_SYNC_FOREGROUND_REFRESH_REQUIRED si la fonction a été appelée pour une actualisation asynchrone au premier plan de la stratégie, mais que la stratégie n’a pas pu être appliquée pendant l’actualisation asynchrone. Le retour ERROR_SYNC_FOREGROUND_REFRESH_REQUIRED indique que la fonction doit être appelée à nouveau pour une actualisation synchrone au premier plan de la stratégie.

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 ou vous pouvez remplacer le message status d’un autre thread.