Función InitializeAcl (securitybaseapi.h)

Artículo
08/25/2023

La función InitializeAcl inicializa una nueva estructura de ACL .

Sintaxis

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

Parámetros

[out] pAcl

Puntero a una estructura de ACL que esta función va a inicializar. Asigne memoria para pAcl antes de llamar a esta función.

[in] nAclLength

Longitud, en bytes, del búfer al que apunta el parámetro pAcl . Este valor debe ser lo suficientemente grande como para contener el encabezado ACL y todas las entradas de control de acceso (ACA) que se almacenarán en la ACL. Además, este valor debe estar alineado con DWORD. Para obtener más información sobre cómo calcular el tamaño de una ACL, vea Comentarios.

[in] dwAclRevision

Nivel de revisión de la estructura de ACL que se va a crear.

Este valor puede ser ACL_REVISION o ACL_REVISION_DS. Use ACL_REVISION_DS si la lista de control de acceso (ACL) admite ACE específicas del objeto.

Valor devuelto

Si la función se ejecuta correctamente, la función devuelve un valor distinto de cero.

Si se produce un error en la función, devuelve cero. Para obtener información de error extendida, llame a GetLastError.

Comentarios

La función InitializeAcl crea una estructura de ACL vacía; la ACL no contiene ACE. Aplicar una ACL vacía a un objeto deniega todo el acceso a ese objeto.

El tamaño inicial de la ACL depende del número de ACL que planee agregar a la ACL antes de usarlo. Por ejemplo, si la ACL contiene una ACE para un usuario y un grupo, inicializaría la ACL basada en dos ACL. Para obtener más información sobre cómo modificar una ACL existente, consulte Modificación de las ACL de un objeto.

Para calcular el tamaño inicial de una ACL, agregue lo siguiente juntos y, a continuación, alinee el resultado con el DWORD más cercano:

Tamaño de la estructura de la ACL .
Tamaño de cada estructura ACE que la ACL debe contener menos el miembro SidStart (DWORD) de la ACE.
Longitud del SID que cada ACE va a contener.

Ejemplos

En el ejemplo siguiente se llama a la función InitializeAcl . El tamaño de la ACL se basa en tres ACE de acceso permitido. Como opción, puede usar el lenguaje de definición de descriptores de seguridad (SDDL) para crear la ACL. Para obtener más información, consulte Creación de una DACL.

En el ejemplo también se omite un paso para simplificar. Para obtener más información, vea el ejemplo De toma de propiedad del objeto . Debe llamar a la función FreeSid al final del código de ejemplo debido a llamar a la función 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.
}

Requisitos

Requisito	Value
Cliente mínimo compatible	Windows XP [aplicaciones de escritorio \| aplicaciones para UWP]
Servidor mínimo compatible	Windows Server 2003 [aplicaciones de escritorio \| aplicaciones para UWP]
Plataforma de destino	Windows
Encabezado	securitybaseapi.h (incluya Windows.h)
Library	Advapi32.lib
Archivo DLL	Advapi32.dll