Fonction AdjustTokenPrivileges (securitybaseapi.h)

La fonction AdjustTokenPrivileges active ou désactive les privilèges dans le jeton d’accès spécifié. L’activation ou la désactivation des privilèges dans un jeton d’accès nécessite un accès TOKEN_ADJUST_PRIVILEGES.

Syntaxe

BOOL AdjustTokenPrivileges(
  [in]            HANDLE            TokenHandle,
  [in]            BOOL              DisableAllPrivileges,
  [in, optional]  PTOKEN_PRIVILEGES NewState,
  [in]            DWORD             BufferLength,
  [out, optional] PTOKEN_PRIVILEGES PreviousState,
  [out, optional] PDWORD            ReturnLength
);

Paramètres

[in] TokenHandle

Handle du jeton d’accès qui contient les privilèges à modifier. Le handle doit avoir TOKEN_ADJUST_PRIVILEGES accès au jeton. Si le paramètre PreviousState n’a pas la valeur NULL, le handle doit également disposer d’un accès TOKEN_QUERY.

[in] DisableAllPrivileges

Spécifie si la fonction désactive tous les privilèges du jeton. Si cette valeur est TRUE, la fonction désactive tous les privilèges et ignore le paramètre NewState . Si elle est FALSE, la fonction modifie les privilèges en fonction des informations pointées par le paramètre NewState .

[in, optional] NewState

Pointeur vers une structure de TOKEN_PRIVILEGES qui spécifie un tableau de privilèges et leurs attributs. Si le paramètre DisableAllPrivileges a la valeur FALSE, la fonction AdjustTokenPrivileges active, désactive ou supprime ces privilèges pour le jeton. Le tableau suivant décrit l’action effectuée par la fonction AdjustTokenPrivileges , en fonction de l’attribut privilege.

Si DisableAllPrivileges a la valeur TRUE, la fonction ignore ce paramètre.

[in] BufferLength

Spécifie la 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 que la fonction remplit avec une structure TOKEN_PRIVILEGES qui contient l’état précédent de tous les privilèges modifiés par la fonction. Autrement dit, si un privilège a été modifié par cette fonction, le privilège et son état précédent sont contenus dans la structure TOKEN_PRIVILEGES référencée par PreviousState. Si le membre PrivilegeCount de TOKEN_PRIVILEGES est égal à zéro, cette fonction n’a modifié aucun privilège. Ce paramètre peut être NULL.

Si vous spécifiez une mémoire tampon trop petite pour recevoir la liste complète des privilèges modifiés, la fonction échoue et n’ajuste aucun privilège. Dans ce cas, la fonction définit la variable pointée vers le paramètre ReturnLength sur le nombre d’octets requis pour contenir la liste complète des privilèges modifiés.

[out, optional] ReturnLength

Pointeur vers une variable qui reçoit la taille requise, en octets, de la mémoire tampon vers laquelle pointe le paramètre PreviousState . Ce paramètre peut avoir la valeur NULL si PreviousState a la valeur NULL.

Valeur retournée

Si la fonction réussit, la valeur de retour est différente de zéro. Pour déterminer si la fonction a ajusté tous les privilèges spécifiés, appelez GetLastError, qui retourne l’une des valeurs suivantes lorsque la fonction réussit :

Si la fonction échoue, la valeur de retour est égale à zéro. Pour obtenir des informations détaillées sur l’erreur, appelez GetLastError.

Remarques

La fonction AdjustTokenPrivileges ne peut pas ajouter de nouveaux privilèges au jeton d’accès. Il peut uniquement activer ou désactiver les privilèges existants du jeton. Pour déterminer les privilèges du jeton, appelez la fonction GetTokenInformation .

Le paramètre NewState peut spécifier des privilèges que le jeton n’a pas, sans provoquer l’échec de la fonction. Dans ce cas, la fonction ajuste les privilèges dont dispose le jeton et ignore les autres privilèges afin que la fonction réussisse. Appelez la fonction GetLastError pour déterminer si la fonction a ajusté tous les privilèges spécifiés. Le paramètre PreviousState indique les privilèges qui ont été ajustés.

Le paramètre PreviousState récupère une structure TOKEN_PRIVILEGES qui contient l’état d’origine des privilèges ajustés. Pour restaurer l’état d’origine, transmettez le pointeur PreviousState comme paramètre NewState dans un appel suivant à la fonction AdjustTokenPrivileges .

Exemples

Pour obtenir un exemple qui utilise cette fonction, consultez Activation et désactivation des privilèges.

Configuration requise

Voir aussi

Vue d’ensemble du contrôle d’accès

AjusterTokenGroups

Fonctions Access Control de base

GetTokenInformation

OpenProcessToken

OpenThreadToken

SetTokenInformation

TOKEN_PRIVILEGES