InitializeAcl-Funktion (securitybaseapi.h)

Artikel
08/25/2023

Die InitializeAcl-Funktion initialisiert eine neue ACL-Struktur .

Syntax

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

Parameter

[out] pAcl

Ein Zeiger auf eine ACL-Struktur , die von dieser Funktion initialisiert werden soll. Ordnen Sie vor dem Aufrufen dieser Funktion Arbeitsspeicher für pAcl zu.

[in] nAclLength

Die Länge des Puffers in Bytes, auf den der pAcl-Parameter verweist. Dieser Wert muss groß genug sein, um den ACL-Header und alle Zugriffssteuerungseinträge (Access Control Entries , ACEs) zu enthalten, die in der ACL gespeichert werden sollen. Darüber hinaus muss dieser Wert DWORD-ausgerichtet sein. Weitere Informationen zum Berechnen der Größe einer ACL finden Sie unter Hinweise.

[in] dwAclRevision

Die Revisionsebene der zu erstellenden ACL-Struktur .

Dieser Wert kann ACL_REVISION oder ACL_REVISION_DS sein. Verwenden Sie ACL_REVISION_DS, wenn die Zugriffssteuerungsliste objektspezifische ACEs unterstützt.

Rückgabewert

Wenn die Funktion erfolgreich ist, gibt die Funktion nonzero zurück.

Wenn die Funktion fehlschlägt, gibt sie null zurück. Um erweiterte Fehlerinformationen zu erhalten, rufen Sie GetLastError auf.

Hinweise

Die InitializeAcl-Funktion erstellt eine leere ACL-Struktur . die ACL enthält keine ACEs. Wenn Sie eine leere ACL auf ein Objekt anwenden, wird jeglicher Zugriff auf dieses Objekt verweigert.

Die anfängliche Größe der ACL hängt von der Anzahl der ACEs ab, die Sie der ACL hinzufügen möchten, bevor Sie sie verwenden. Wenn die ACL beispielsweise ein ACE für einen Benutzer und eine Gruppe enthalten soll, würden Sie die ACL basierend auf zwei ACEs initialisieren. Ausführliche Informationen zum Ändern einer vorhandenen Zugriffssteuerungsliste finden Sie unter Ändern der ACLs eines Objekts.

Um die anfängliche Größe einer ACL zu berechnen, fügen Sie Folgendes zusammen, und richten Sie das Ergebnis dann an der nächstgelegenen DWORD aus:

Größe der ACL-Struktur .
Größe jeder ACE-Struktur , die die ACL enthalten soll, abzüglich des SidStart-Members (DWORD) des ACE.
Länge der SID, die jeder ACE enthalten soll.

Beispiele

Im folgenden Beispiel wird die InitializeAcl-Funktion aufgerufen. Die Größe der ACL basiert auf drei Zugriffsberechtigungs-ACEs. Optional können Sie die Sicherheitsdeskriptordefinitionssprache (SDDL) verwenden, um die ACL zu erstellen. Ausführliche Informationen finden Sie unter Erstellen einer DACL.

Im Beispiel wird auch ein Schritt zur Vereinfachung weggelassen. Weitere Informationen finden Sie im Beispiel Zum Übernehmen von Objektbesitz . Sie müssen die FreeSid-Funktion am Ende des Beispielcodes aufrufen, da die Funktion AllocateAndInitializeSid aufgerufen wird.

#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.
}

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Windows XP [Desktop-Apps \| UWP-Apps]
Unterstützte Mindestversion (Server)	Windows Server 2003 [Desktop-Apps \| UWP-Apps]
Zielplattform	Windows
Kopfzeile	securitybaseapi.h (einschließlich Windows.h)
Bibliothek	Advapi32.lib
DLL	Advapi32.dll