Функция InitializeAcl (securitybaseapi.h)

Статья
08/25/2023

Функция InitializeAcl инициализирует новую структуру ACL .

Синтаксис

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

Параметры

[out] pAcl

Указатель на структуру ACL , инициализируемый этой функцией. Выделите память для pACL перед вызовом этой функции.

[in] nAclLength

Длина (в байтах) буфера, на который указывает параметр pACL . Это значение должно быть достаточно большим, чтобы содержать заголовок ACL и все записи управления доступом (ACE) для хранения в списке управления доступом. Кроме того, это значение должно быть выровнено по DWORD. Дополнительные сведения о вычислении размера ACL см. в разделе Примечания.

[in] dwAclRevision

Уровень редакции создаваемой структуры ACL .

Это значение может быть ACL_REVISION или ACL_REVISION_DS. Используйте ACL_REVISION_DS, если список управления доступом (ACL) поддерживает ACE для конкретных объектов.

Возвращаемое значение

Если функция выполнена успешно, функция возвращает ненулевое значение.

Если функция завершается сбоем, она возвращает ноль. Дополнительные сведения об ошибке можно получить, вызвав GetLastError.

Первоначальный размер ACL зависит от количества ACL, которые вы планируете добавить в ACL перед его использованием. Например, если ACL содержит ACE для пользователя и группы, необходимо инициализировать список управления доступом на основе двух ACE. Дополнительные сведения об изменении существующего списка управления доступом см. в разделе Изменение списков управления доступом объекта .

Чтобы вычислить начальный размер списка ACL, добавьте следующее, а затем выровняйте результат по ближайшему DWORD:

Размер структуры ACL .
Размер каждой структуры ACE , в которой должен содержаться список ACL , за вычетом элемента SidStart (DWORD) ACE.
Длина идентификатора безопасности, который будет содержать каждый ACE .

Примеры

В следующем примере вызывается функция InitializeAcl . Размер ACL зависит от трех ACE с разрешенным доступом. В качестве варианта можно использовать язык определения дескриптора безопасности (SDDL) для создания ACL. Дополнительные сведения см. в разделе Создание DACL.

В примере также пропускает шаг для упрощения. Дополнительные сведения см. в примере принятия прав владения объектом . Необходимо вызвать функцию FreeSid в конце примера кода из-за вызова функции 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.
}

Требования

Требование	Значение
Минимальная версия клиента	Windows XP [классические приложения \| Приложения UWP]
Минимальная версия сервера	Windows Server 2003 [классические приложения \| Приложения UWP]
Целевая платформа	Windows
Header	securitybaseapi.h (включая Windows.h)
Библиотека	Advapi32.lib
DLL	Advapi32.dll