AddAccessAllowedAce, fonction (securitybaseapi.h)

Article
03/04/2024

La fonction AddAccessAllowedAce ajoute une entrée de contrôle d’accès autorisé (ACE) à une liste de contrôle d’accès (ACL). L’accès est accordé à un identificateur de sécurité (SID) spécifié.

Pour contrôler si la nouvelle ACE peut être héritée par des objets enfants, utilisez la fonction AddAccessAllowedAceEx .

Syntaxe

BOOL AddAccessAllowedAce(
  [in, out] PACL  pAcl,
  [in]      DWORD dwAceRevision,
  [in]      DWORD AccessMask,
  [in]      PSID  pSid
);

Paramètres

[in, out] pAcl

Pointeur vers une liste de contrôle d’accès. Cette fonction ajoute un ace autorisé à l’accès à la fin de cette liste de contrôle d’accès. L’ACE se présente sous la forme d’une structure ACCESS_ALLOWED_ACE .

[in] dwAceRevision

Spécifie le niveau de révision de la liste de contrôle d’accès en cours de modification.

Cette valeur peut être ACL_REVISION ou ACL_REVISION_DS. Utilisez ACL_REVISION_DS si la liste de contrôle d’accès contient des AE spécifiques à l’objet.

[in] AccessMask

Spécifie le masque des droits d’accès à accorder au SID spécifié.

[in] pSid

Pointeur vers le SID représentant un utilisateur, un groupe ou un compte d’ouverture de session auquel l’accès est accordé.

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. Voici les valeurs d’erreur possibles.

Code de retour	Description
ERROR_ALLOTTED_SPACE_EXCEEDED	Le nouvel ACE ne tient pas dans la liste de contrôle d’accès. Une mémoire tampon ACL plus grande est requise.
ERROR_INVALID_ACL	La liste de contrôle d’accès spécifiée n’est pas correctement formée.
ERROR_INVALID_SID	Le SID spécifié n’est pas structurellement valide.
ERROR_REVISION_MISMATCH	La révision spécifiée n’est pas connue ou est incompatible avec celle de l’ACL.
ERROR_SUCCESS	L’ACE a été ajouté avec succès.

Remarques

L’ajout d’une ace autorisée par accès à une liste de contrôle d’accès est la forme la plus courante de modification de la liste de contrôle d’accès.

Les fonctions AddAccessAllowedAce et AddAccessDeniedAce ajoutent un nouvel ACE à la fin de la liste des ACL. Ces fonctions ne placent pas automatiquement le nouvel ACE dans l’ordre canonique approprié. Il incombe à l’appelant de s’assurer que la liste de contrôle d’accès est dans l’ordre canonique en ajoutant des AE dans l’ordre approprié.

La structure ACE_HEADER placée dans l’ace par la fonction AddAccessAllowedAce spécifie un type et une taille, mais ne fournit aucun héritage ni aucun indicateur ACE.

Exemples

Pour obtenir un exemple qui utilise cette fonction, consultez Démarrage d’un processus client interactif.

Configuration requise

Condition requise	Valeur
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