Função InitializeAcl (securitybaseapi.h)

Artigo
08/25/2023

A função InitializeAcl inicializa uma nova estrutura de ACL .

Sintaxe

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

Parâmetros

[out] pAcl

Um ponteiro para uma estrutura de ACL a ser inicializada por essa função. Aloque memória para pAcl antes de chamar essa função.

[in] nAclLength

O comprimento, em bytes, do buffer apontado pelo parâmetro pAcl . Esse valor deve ser grande o suficiente para conter o cabeçalho de ACL e todas as ACEs ( entradas de controle de acesso ) a serem armazenadas na ACL. Além disso, esse valor deve ser alinhado a DWORD. Para obter mais informações sobre como calcular o tamanho de uma ACL, consulte Comentários.

[in] dwAclRevision

O nível de revisão da estrutura de ACL que está sendo criada.

Esse valor pode ser ACL_REVISION ou ACL_REVISION_DS. Use ACL_REVISION_DS se a ACL ( lista de controle de acesso ) der suporte a ACEs específicas do objeto.

Retornar valor

Se a função for bem-sucedida, a função retornará diferente de zero.

Se a função falhar, ela retornará zero. Para obter informações de erro estendidas, chame GetLastError.

Comentários

A função InitializeAcl cria uma estrutura de ACL vazia; a ACL não contém ACEs. Aplicar uma ACL vazia a um objeto nega todo o acesso a esse objeto.

O tamanho inicial da ACL depende do número de ACEs que você planeja adicionar à ACL antes de usá-la. Por exemplo, se a ACL deve conter uma ACE para um usuário e um grupo, você inicializará a ACL com base em dois ACEs. Para obter detalhes sobre como modificar uma ACL existente, consulte Modificando as ACLs de um objeto.

Para calcular o tamanho inicial de uma ACL, adicione o seguinte e alinhe o resultado ao DWORD mais próximo:

Tamanho da estrutura de ACL .
Tamanho de cada estrutura ACE que a ACL deve conter menos o membro SidStart (DWORD) do ACE.
Comprimento do SID que cada ACE deve conter.

Exemplos

O exemplo a seguir chama a função InitializeAcl . O tamanho da ACL é baseado em três ACEs de permissão de acesso. Como opção, você pode usar a SDDL ( linguagem de definição de descritor de segurança ) para criar a ACL. Para obter detalhes, consulte Criando uma DACL.

O exemplo também omite uma etapa para simplificação. Para obter mais informações, consulte o exemplo Tomando Propriedade de Objeto . Você deve chamar a função FreeSid no final do código de exemplo devido à chamada da função 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	Valor
Cliente mínimo com suporte	Windows XP [aplicativos da área de trabalho \| aplicativos UWP]
Servidor mínimo com suporte	Windows Server 2003 [aplicativos da área de trabalho \| Aplicativos UWP]
Plataforma de Destino	Windows
Cabeçalho	securitybaseapi.h (inclua Windows.h)
Biblioteca	Advapi32.lib
DLL	Advapi32.dll