Fonction InitializeAcl (securitybaseapi.h)

Article
03/04/2024

La fonction InitializeAcl initialise une nouvelle structure ACL .

Syntaxe

BOOL InitializeAcl(
  [out] PACL  pAcl,
  [in]  DWORD nAclLength,
  [in]  DWORD dwAclRevision
);

Paramètres

[out] pAcl

Pointeur vers une structure ACL à initialiser par cette fonction. Allouez de la mémoire pour pAcl avant d’appeler cette fonction.

[in] nAclLength

Longueur, en octets, de la mémoire tampon pointée vers le paramètre pAcl . Cette valeur doit être suffisamment grande pour contenir l’en-tête ACL et toutes les entrées de contrôle d’accès (AES) pour être stockées dans la liste de contrôle d’accès. En outre, cette valeur doit être alignée sur DWORD. Pour plus d’informations sur le calcul de la taille d’une liste de contrôle d’accès, consultez Remarques.

[in] dwAclRevision

Niveau de révision de la structure ACL en cours de création.

Cette valeur peut être ACL_REVISION ou ACL_REVISION_DS. Utilisez ACL_REVISION_DS si la liste de contrôle d’accès (ACL) prend en charge les AIC spécifiques aux objets.

Valeur retournée

Si la fonction réussit, la fonction retourne une valeur différente de zéro.

Si la fonction échoue, elle retourne zéro. Pour obtenir des informations détaillées sur l’erreur, appelez GetLastError.

Remarques

La fonction InitializeAcl crée une structure ACL vide ; la liste de contrôle d’accès ne contient pas d’AE. L’application d’une liste de contrôle d’accès vide à un objet refuse tout accès à cet objet.

La taille initiale de la liste de contrôle d’accès dépend du nombre d’ACÉ que vous prévoyez d’ajouter à la liste de contrôle d’accès avant de l’utiliser. Par exemple, si l’ACL doit contenir un ACE pour un utilisateur et un groupe, vous initialisez la liste de contrôle d’accès en fonction de deux AE. Pour plus d’informations sur la modification d’une liste de contrôle d’accès existante, consultez Modification des listes de contrôle d’accès d’un objet.

Pour calculer la taille initiale d’une liste de contrôle d’accès, ajoutez les éléments suivants, puis alignez le résultat sur le DWORD le plus proche :

Taille de la structure ACL .
Taille de chaque structure ACE que l’ACL doit contenir moins le membre SidStart (DWORD) de l’ACE.
Longueur du SID que chaque ACE doit contenir.

Exemples

L’exemple suivant appelle la fonction InitializeAcl . La taille de la liste de contrôle d’accès est basée sur trois AE d’accès autorisé. En option, vous pouvez utiliser le langage de définition de descripteur de sécurité (SDDL) pour créer l’ACL. Pour plus d’informations, consultez Création d’une liste dacl.

L’exemple omet également une étape de simplification. Pour plus d’informations, consultez l’exemple Prise de propriété d’objet . Vous devez appeler la fonction FreeSid à la fin de l’exemple de code en raison de l’appel de la fonction AllocateAndInitializeSid .

#include <windows.h>
#include <Winbase.h>
#pragma comment(lib, "duser.lib")

#define NUM_OF_ACES 3

void main()
{
    PACL pAcl = NULL;
    DWORD cbAcl = 0;
    PSID psids[NUM_OF_ACES];

    // Allocate and initialize SIDs.
    // Step omitted - See Taking Object Ownership example.

    // Add the SID for each ACE to psids. 
    cbAcl = sizeof(ACL) + 
        ((sizeof(ACCESS_ALLOWED_ACE)) * NUM_OF_ACES);
    for (int i = 0; i < NUM_OF_ACES; i++)
    {
        cbAcl += GetLengthSid(psids[i]) - sizeof(DWORD);
    }

    // Align cbAcl to a DWORD.
    cbAcl = (cbAcl + (sizeof(DWORD) - 1)) & 0xfffffffc;

    pAcl = (ACL*)LocalAlloc(LPTR, cbAcl);
    if (pAcl)
    {
        if (InitializeAcl(pAcl, cbAcl, ACL_REVISION))
        {

            // Add the ACEs to the ACL.
            // Add the ACL to the object's security descriptor.
        }
        else
        {

            // Handle error.
        }
    }
    {

        // Handle error.
    }

    // Free pAcl when finished.
    // Call FreeSid when finished.
}

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