GetGPOListA, fonction (userenv.h)
La fonction GetGPOList récupère la liste des objets de stratégie de groupe pour l’utilisateur ou l’ordinateur spécifié. Cette fonction peut être appelée de deux façons : tout d’abord, vous pouvez utiliser le jeton pour l’utilisateur ou l’ordinateur, ou, deuxièmement, vous pouvez utiliser le nom de l’utilisateur ou de l’ordinateur et le nom du contrôleur de domaine.
Syntaxe
USERENVAPI BOOL GetGPOListA(
[in] HANDLE hToken,
[in] LPCSTR lpName,
[in] LPCSTR lpHostName,
[in] LPCSTR lpComputerName,
[in] DWORD dwFlags,
[out] PGROUP_POLICY_OBJECTA *pGPOList
);
Paramètres
[in] hToken
Jeton pour l’utilisateur ou l’ordinateur, retourné à partir duLogonUser
Si ce paramètre est NULL, vous devez fournir des valeurs pour les paramètres lpName et lpHostName.
[in] lpName
Pointeur vers le nom de l’utilisateur ou de l’ordinateur, au format de nom unique complet (par exemple, « CN=utilisateur , OU =utilisateurs, DC=contoso, DC=com»).
Si le paramètre hToken
[in] lpHostName
Nom de domaine DNS (préféré) ou nom de contrôleur de domaine. Le nom du contrôleur de domaine peut être récupéré à l’aide de la fonction DsGetDcName
Si le paramètre hToken
[in] lpComputerName
Pointeur vers le nom de l’ordinateur utilisé pour déterminer l’emplacement du site. Le format du nom est « \\computer_name». Si ce paramètre est NULL, le nom de l’ordinateur local est utilisé.
[in] dwFlags
Valeur qui spécifie des indicateurs supplémentaires utilisés pour contrôler la récupération des informations. Si vous spécifiez GPO_LIST_FLAG_MACHINE, la fonction récupère les informations de stratégie de l’ordinateur. Si vous ne spécifiez pas GPO_LIST_FLAG_MACHINE, la fonction récupère les informations de stratégie pour l’utilisateur.
Si vous spécifiez GPO_LIST_FLAG_SITEONLY la fonction retourne uniquement des informations de site pour l’ordinateur ou l’utilisateur.
[out] pGPOList
Pointeur qui reçoit la liste des structures d’objets de stratégie de groupe. Pour plus d’informations, consultez GROUP_POLICY_OBJECT.
Valeur de retour
Si la fonction réussit, la valeur de retour est différente de zéro.
Si la fonction échoue, la valeur de retour est égale à zéro. Pour obtenir des informations d’erreur étendues, appelez GetLastError.
Remarques
La fonction GetGPOList est destinée à être utilisée par des services agissant au nom d’un utilisateur ou d’un ordinateur. Le service appelle cette fonction pour obtenir une liste d’objets de stratégie de groupe, puis vérifie chaque objet de stratégie de groupe pour la stratégie spécifique au service.
L’appel de cette fonction avec un jeton fournit la liste la plus précise. Le système peut effectuer la vérification d’accès pour l’utilisateur ou l’ordinateur. L’appel de cette fonction avec le nom d’utilisateur ou d’ordinateur et le nom du contrôleur de domaine est plus rapide que de l’appeler avec un jeton. Toutefois, si le jeton n’est pas spécifié, le système utilise l’accès de sécurité de l’appelant, ce qui signifie que la liste peut ne pas être complètement correcte pour l’utilisateur ou l’ordinateur prévu.
Pour obtenir la liste la plus précise des objets de stratégie de groupe pour un ordinateur lors de l’appel de GetGPOList, l’appelant doit disposer d’un accès en lecture à chaque unité d’organisation et site dans le domaine de l’ordinateur, et également lire et appliquer l’accès aux stratégies de groupe à tous les objets de stratégie de groupe liés aux sites, au domaine ou aux unités d’organisation de ce domaine. Un exemple d’appelant serait un service s’exécutant sur l’ordinateur dont le nom est spécifié dans le paramètre lpName. Une autre méthode d’obtention d’une liste d’objets de stratégie de groupe consiste à appeler la méthode RsopCreateSession de la RsopPlanningModeProvider classe WMI. La méthode peut générer des données de stratégie résultantes pour un ordinateur ou un compte d’utilisateur dans un scénario hypothétique.
Appelez la fonction FreeGPOList pour libérer la liste des objets de stratégie de groupe lorsque vous avez terminé de le traiter.
En règle générale, vous devez appeler GetGPOList avec un jeton lors de la récupération d’une liste d’objets de stratégie de groupe pour un utilisateur, comme indiqué dans l’exemple de code suivant.
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);
}
En règle générale, pour récupérer une liste d’objets de stratégie de groupe pour un ordinateur, vous pouvez appeler GetGPOList avec le nom de l’ordinateur et le nom du contrôleur de domaine, comme illustré dans l’extrait de code suivant.
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);
}
Pour récupérer la liste des objets de stratégie de groupe appliqués à un utilisateur ou un ordinateur et une extension spécifiques, appelez la fonction GetAppliedGPOList.
Note
L’en-tête userenv.h définit GetGPOList comme alias qui sélectionne automatiquement la version ANSI ou Unicode de cette fonction en fonction de la définition de la constante de préprocesseur UNICODE. Le mélange de l’utilisation de l’alias neutre en encodage avec du code qui n’est pas neutre en encodage peut entraîner des incompatibilités qui entraînent des erreurs de compilation ou d’exécution. Pour plus d’informations, consultez Conventions pour les prototypes de fonction.
Exigences
| Exigence | Valeur |
|---|---|
| client minimum pris en charge | Windows Vista |
| serveur minimum pris en charge | Windows Server 2008 |
| plateforme cible | Windows |
| d’en-tête | userenv.h |
| bibliothèque | Userenv.lib |
| DLL | Userenv.dll |