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 TOKEN_ADJUST_PRIVILEGES accès.

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’est pas NULL, le handle doit également avoir TOKEN_QUERY accès.

[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 . S’il s’agit de 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 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 de privilège.

Valeur Signification
SE_PRIVILEGE_ENABLED
La fonction active le privilège.
SE_PRIVILEGE_REMOVED
Le privilège est supprimé de la liste des privilèges dans le jeton. Les autres privilèges de la liste sont réorganisés pour rester contigus.

SE_PRIVILEGE_REMOVED remplace SE_PRIVILEGE_ENABLED.

Étant donné que le privilège a été supprimé du jeton, les tentatives de réinitialisation du privilège entraînent l’avertissement ERROR_NOT_ALL_ASSIGNED comme si le privilège n’avait jamais existé.

Toute tentative de suppression d’un privilège qui n’existe pas dans le jeton entraîne ERROR_NOT_ALL_ASSIGNED être retourné.

Les vérifications de privilèges pour les privilèges supprimés entraînent STATUS_PRIVILEGE_NOT_HELD. L’audit de vérification des privilèges ayant échoué se produit normalement.

La suppression du privilège est irréversible. Par conséquent, le nom du privilège supprimé n’est pas inclus dans le paramètre PreviousState après un appel à AdjustTokenPrivileges.

Windows XP avec SP1 : La fonction ne peut pas supprimer les privilèges. Cette valeur n’est pas prise en charge.

Aucun
La fonction désactive le privilège.
 

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 par 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, aucun privilège n’a été modifié par cette fonction. 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 pas les privilèges. 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 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 être 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 :

Code de retour Description
ERROR_SUCCESS
La fonction a ajusté tous les privilèges spécifiés.
ERROR_NOT_ALL_ASSIGNED
Le jeton n’a pas un ou plusieurs privilèges spécifiés dans le paramètre NewState . La fonction peut réussir avec cette valeur d’erreur même si aucun privilège n’a été ajusté. Le paramètre PreviousState indique les privilèges qui ont été ajustés.
 

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

La fonction AdjustTokenPrivileges ne peut pas ajouter de nouveaux privilèges au jeton d’accès. Il ne peut activer ou désactiver que 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 dont le jeton n’a pas, sans provoquer l’échec de la fonction. Dans ce cas, la fonction ajuste les privilèges dont le jeton dispose 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 en tant que paramètre NewState dans un appel ultérieur à la fonction AdjustTokenPrivileges .

Exemples

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

Configuration requise

   
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

Voir aussi

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

AdjustTokenGroups

Fonctions de Access Control de base

GetTokenInformation

OpenProcessToken

OpenThreadToken

SetTokenInformation

TOKEN_PRIVILEGES