Функция BuildSecurityDescriptorA (aclapi.h)

Статья
03/14/2023

Функция BuildSecurityDescriptor выделяет и инициализирует новый дескриптор безопасности. Эта функция может инициализировать новый дескриптор безопасности путем объединения указанных сведений о безопасности с данными в существующем дескрипторове безопасности. Если не указать существующий дескриптор безопасности, функция инициализирует новый дескриптор безопасности на основе указанных сведений о безопасности.

Функция BuildSecurityDescriptor создает самостоятельный дескриптор безопасности. Самостоятельный формат делает дескриптор безопасности пригодным для хранения в потоке.

Синтаксис

DWORD BuildSecurityDescriptorA(
  [in, optional] PTRUSTEE_A           pOwner,
  [in, optional] PTRUSTEE_A           pGroup,
  [in]           ULONG                cCountOfAccessEntries,
  [in, optional] PEXPLICIT_ACCESS_A   pListOfAccessEntries,
  [in]           ULONG                cCountOfAuditEntries,
  [in, optional] PEXPLICIT_ACCESS_A   pListOfAuditEntries,
  [in, optional] PSECURITY_DESCRIPTOR pOldSD,
  [out]          PULONG               pSizeNewSD,
  [out]          PSECURITY_DESCRIPTOR *pNewSD
);

Параметры

[in, optional] pOwner

Указатель на структуру TRUSTEE , которая определяет владельца для нового дескриптора безопасности. Если структура использует форму TRUSTEE_IS_NAME, BuildSecurityDescriptor ищет идентификатор безопасности (SID), связанный с указанным именем доверенного лица.

Если этот параметр имеет значение NULL, функция использует идентификатор безопасности владельца из исходного дескриптора безопасности, на который указывает pOldSD. Если pOldSD имеет значение NULL или идентификатор безопасности владельца в pOldSD имеет значение NULL, идентификатор безопасности владельца в новом дескрипторе безопасности имеет значение NULL .

[in, optional] pGroup

Указатель на структуру TRUSTEE , которая определяет основной идентификатор безопасности группы для нового дескриптора безопасности. Если структура использует форму TRUSTEE_IS_NAME, BuildSecurityDescriptor ищет идентификатор безопасности, связанный с указанным именем доверенного лица.

Если этот параметр имеет значение NULL, функция использует идентификатор безопасности группы из исходного дескриптора безопасности, на который указывает pOldSD. Если pOldSD имеет значение NULL или идентификатор безопасности группы в pOldSD имеет значение NULL, идентификатор безопасности группы в новом дескрипторе безопасности имеет значение NULL .

[in] cCountOfAccessEntries

Количество EXPLICIT_ACCESS структур в массиве pListOfAccessEntries .

[in, optional] pListOfAccessEntries

Указатель на массив EXPLICIT_ACCESS структур, описывающих сведения об управлении доступом для списка управления доступом (DACL) нового дескриптора безопасности. Функция создает новый DACL путем объединения сведений в массиве с DACL в pOldSD, если таковые есть. Если pOldSD имеет значение NULL или daCL в pOldSD имеет значение NULL, функция создает новый DACL исключительно на основе сведений в массиве. Описание правил создания ACL из массива EXPLICIT_ACCESS структур см. в разделе Функция SetEntriesInAcl .

Если pListOfAccessEntries имеет значение NULL, новый дескриптор безопасности получает DACL из pOldSD. В этом случае, если pOldSD имеет значение NULL или если DACL в pOldSD имеет значение NULL, то новый daCL имеет значение NULL.

[in] cCountOfAuditEntries

Количество EXPLICIT_ACCESS структур в массиве pListOfAuditEntries .

[in, optional] pListOfAuditEntries

Указатель на массив EXPLICIT_ACCESS структур, описывающих сведения об управлении аудитом для saCL нового дескриптора безопасности. Функция создает новый saCL путем объединения сведений в массиве с SACL в pOldSD, если таковые есть. Если pOldSD имеет значение NULL или saCL в pOldSD имеет значение NULL, функция создает новый saCL исключительно на основе сведений в массиве.

Если pListOfAuditEntries имеет значение NULL, новый дескриптор безопасности получает saCL из pOldSD. В этом случае, если pOldSD имеет значение NULL или saCL в pOldSD имеет значение NULL, новый saCL имеет значение NULL.

[in, optional] pOldSD

Указатель на существующую структуру SECURITY_DESCRIPTOR и связанные с ней сведения о безопасности. Функция создает новый дескриптор безопасности, объединяя указанные сведения о владельце, группе, управлении доступом и аудите с данными в этом дескрипторове безопасности. Этот параметр может принимать значение NULL.

[out] pSizeNewSD

Указатель на переменную, которая получает размер дескриптора безопасности в байтах.

[out] pNewSD

Указатель на переменную, которая получает указатель на новый дескриптор безопасности. Функция выделяет память для нового дескриптора безопасности. Чтобы освободить возвращенный буфер, необходимо вызвать функцию LocalFree .

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

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

Если функция завершается сбоем, она возвращает ненулевой код ошибки, определенный в WinError.h.

Функция BuildSecurityDescriptor предназначена для доверенных серверов, которые реализуют или предоставляют безопасность для собственных объектов. Функция использует самостоятельные дескрипторы безопасности, подходящие для сериализации в поток и хранения на диске, как это может потребоваться для доверенного сервера.

Примечание

Заголовок aclapi.h определяет BuildSecurityDescriptor в качестве псевдонима, который автоматически выбирает версию ANSI или Юникод этой функции на основе определения константы препроцессора ЮНИКОД. Использование псевдонима, не зависящий от кодирования, с кодом, который не является нейтральным для кодировки, может привести к несоответствиям, которые приводят к ошибкам компиляции или времени выполнения. Дополнительные сведения см. в разделе Соглашения для прототипов функций.

Требования

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