AddAce, fonction (securitybaseapi.h)

Article
03/04/2024

La fonction AddAce ajoute une ou plusieurs entrées de contrôle d’accès (ACL) à une liste de contrôle d’accès (ACL) spécifiée.

Syntaxe

BOOL AddAce(
  [in, out] PACL   pAcl,
  [in]      DWORD  dwAceRevision,
  [in]      DWORD  dwStartingAceIndex,
  [in]      LPVOID pAceList,
  [in]      DWORD  nAceListLength
);

Paramètres

[in, out] pAcl

Pointeur vers une liste de contrôle d’accès. Cette fonction ajoute un ACE à cette liste de contrôle d’accès.

[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. Cette valeur doit être compatible avec le champ AceType de tous les ACÉ dans pAceList. Sinon, la fonction échoue et définit la dernière erreur sur ERROR_INVALID_PARAMETER.

[in] dwStartingAceIndex

Spécifie la position dans la liste ACL des ACL à laquelle ajouter de nouveaux ACL. La valeur zéro insère les AE au début de la liste. La valeur MAXDWORD ajoute les AIC à la fin de la liste.

[in] pAceList

Pointeur vers une liste d’un ou plusieurs ACL à ajouter à la liste de contrôle d’accès spécifiée. Les ACÉ de la liste doivent être stockés de manière contiguë.

[in] nAceListLength

Spécifie la taille, en octets, de la mémoire tampon d’entrée pointée par le paramètre pAceList .

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_INSUFFICIENT_BUFFER	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_PARAMETER	La liste de contrôle d’accès spécifiée n’est pas correctement formée.
ERROR_SUCCESS	L’ACE a été ajouté avec succès.

Remarques

Les applications utilisent fréquemment les fonctions FindFirstFreeAce et GetAce lors de l’utilisation de la fonction AddAce pour manipuler une liste de contrôle d’accès. En outre, la structure ACL_SIZE_INFORMATION récupérée par la fonction GetAclInformation contient la taille de la liste de contrôle d’accès et le nombre d’ACL qu’elle contient.

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