Funzione InitializeAcl (securitybaseapi.h)

Articolo
08/25/2023

La funzione InitializeAcl inizializza una nuova struttura ACL .

Sintassi

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

Parametri

[out] pAcl

Puntatore a una struttura ACL da inizializzare tramite questa funzione. Allocare memoria per pAcl prima di chiamare questa funzione.

[in] nAclLength

Lunghezza, in byte, del buffer a cui punta il parametro pAcl . Questo valore deve essere sufficientemente grande da contenere l'intestazione ACL e tutte le voci di controllo di accesso (ACL) da archiviare nell'ACL. Inoltre, questo valore deve essere allineato a DWORD. Per altre informazioni sul calcolo delle dimensioni di un elenco di controllo di accesso, vedere Osservazioni.

[in] dwAclRevision

Livello di revisione della struttura ACL in fase di creazione.

Questo valore può essere ACL_REVISION o ACL_REVISION_DS. Usare ACL_REVISION_DS se l'elenco di controllo di accesso (ACL) supporta gli ACL specifici dell'oggetto.

Valore restituito

Se la funzione ha esito positivo, la funzione restituisce un valore diverso da zero.

Se la funzione ha esito negativo, restituisce zero. Per informazioni dettagliate sull'errore, chiamare GetLastError.

Commenti

La funzione InitializeAcl crea una struttura ACL vuota; L'ACL non contiene ACL. L'applicazione di un ACL vuoto a un oggetto nega l'accesso a tale oggetto.

Le dimensioni iniziali dell'ACL dipendono dal numero di ACL che si prevede di aggiungere all'ACL prima di usarlo. Ad esempio, se l'ACL deve contenere un ace per un utente e un gruppo, inizializzare l'ACL in base a due ACL. Per informazioni dettagliate sulla modifica di un elenco di controllo di accesso esistente, vedere Modifica degli ACL di un oggetto.

Per calcolare le dimensioni iniziali di un ACL, aggiungere gli elementi seguenti e quindi allineare il risultato al DWORD più vicino:

Dimensioni della struttura ACL .
Dimensioni di ogni struttura ACE che l'ACL deve contenere meno il membro SidStart (DWORD) dell'ACE.
Lunghezza del SID che ogni ACE deve contenere.

Esempio

Nell'esempio seguente viene chiamata la funzione InitializeAcl . Le dimensioni dell'ACL si basano su tre ACL di accesso consentito. Come opzione, è possibile usare sdDL ( Security Descriptor Definition Language ) per creare l'ACL. Per informazioni dettagliate, vedere Creazione di un DACL.

Nell'esempio viene omesso anche un passaggio per la semplificazione. Per altre informazioni, vedere l'esempio Di proprietà dell'oggetto di acquisizione. È necessario chiamare la funzione FreeSid alla fine del codice di esempio a causa della chiamata alla funzione 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.
}

Requisiti

Requisito	Valore
Client minimo supportato	Windows XP [app desktop \| App UWP]
Server minimo supportato	Windows Server 2003 [app desktop \| App UWP]
Piattaforma di destinazione	Windows
Intestazione	securitybaseapi.h (include Windows.h)
Libreria	Advapi32.lib
DLL	Advapi32.dll