Fonction AdjustTokenGroups (securitybaseapi.h)

Article
08/25/2023

La fonction AdjustTokenGroups active ou désactive les groupes déjà présents dans le jeton d’accès spécifié. L’accès à TOKEN_ADJUST_GROUPS est nécessaire pour activer ou désactiver des groupes dans un jeton d’accès.

Syntaxe

BOOL AdjustTokenGroups(
  [in]            HANDLE        TokenHandle,
  [in]            BOOL          ResetToDefault,
  [in, optional]  PTOKEN_GROUPS NewState,
  [in]            DWORD         BufferLength,
  [out, optional] PTOKEN_GROUPS PreviousState,
  [out, optional] PDWORD        ReturnLength
);

Paramètres

[in] TokenHandle

Handle du jeton d’accès qui contient les groupes à activer ou désactiver. Le handle doit avoir TOKEN_ADJUST_GROUPS accès au jeton. Si le paramètre PreviousState n’est pas NULL, le handle doit également avoir un accès TOKEN_QUERY.

[in] ResetToDefault

Valeur booléenne qui indique si les groupes doivent être définis sur leurs états activés et désactivés par défaut. Si cette valeur est TRUE, les groupes sont définis sur leurs états par défaut et le paramètre NewState est ignoré. Si cette valeur est FALSE, les groupes sont définis en fonction des informations pointées par le paramètre NewState .

[in, optional] NewState

Pointeur vers une structure de TOKEN_GROUPS qui contient les groupes à activer ou désactiver. Si le paramètre ResetToDefault a la valeur FALSE, la fonction affecte à chacun des groupes la valeur de l’attribut SE_GROUP_ENABLED de ce groupe dans la structure TOKEN_GROUPS . Si ResetToDefault a la valeur TRUE, ce paramètre est ignoré.

[in] BufferLength

Taille, en octets, de la mémoire tampon pointée vers le paramètre PreviousState . Ce paramètre peut être égal à zéro si le paramètre PreviousState a la valeur NULL.

[out, optional] PreviousState

Pointeur vers une mémoire tampon qui reçoit une structure TOKEN_GROUPS contenant l’état précédent de tous les groupes modifiés par la fonction. Autrement dit, si un groupe a été modifié par cette fonction, le groupe et son état précédent sont contenus dans la structure TOKEN_GROUPS référencée par PreviousState. Si le membre GroupCount de TOKEN_GROUPS est égal à zéro, cela signifie qu’aucun groupe n’a été modifié par cette fonction. Ce paramètre peut être NULL.

Si une mémoire tampon est spécifiée mais qu’elle ne contient pas suffisamment d’espace pour recevoir la liste complète des groupes modifiés, aucun état de groupe n’est modifié et la fonction échoue. Dans ce cas, la fonction définit la variable pointée par le paramètre ReturnLength sur le nombre d’octets requis pour contenir la liste complète des groupes modifiés.

[out, optional] ReturnLength

Pointeur vers une variable qui reçoit le nombre réel d’octets nécessaires pour la mémoire tampon vers laquelle pointe le paramètre PreviousState . Ce paramètre peut être NULL et est ignoré si PreviousState a la valeur NULL.

Valeur retournée

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étaillées sur l’erreur, appelez GetLastError.

Notes

Les informations récupérées dans le paramètre PreviousState sont mises en forme en tant que structure TOKEN_GROUPS . Cela signifie qu’un pointeur vers la mémoire tampon peut être passé en tant que paramètre NewState dans un appel suivant à la fonction AdjustTokenGroups , en restaurant l’état d’origine des groupes.

Le paramètre NewState peut répertorier les groupes à modifier qui ne sont pas présents dans le jeton d’accès. Cela n’affecte pas la modification réussie des groupes dans le jeton.

La fonction AdjustTokenGroups ne peut pas désactiver les groupes avec l’attribut SE_GROUP_MANDATORY dans la structure TOKEN_GROUPS . Utilisez Plutôt CreateRestrictedToken .

Vous ne pouvez pas activer un groupe qui a l’attribut SE_GROUP_USE_FOR_DENY_ONLY.

Spécifications


Client minimal pris en charge	Windows XP [applications de bureau \| applications UWP]
Serveur minimal pris en charge	Windows Server 2003 [applications de bureau \| applications UWP]
Plateforme cible	Windows
En-tête	securitybaseapi.h (inclure Windows.h)
Bibliothèque	Advapi32.lib
DLL	Advapi32.dll