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

Статья
11/20/2024

Функция 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 ищет идентификатор безопасности , связанный с указанным именем доверенного лица.

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

[in, optional] pGroup

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

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

[in] cCountOfAccessEntries

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

[in, optional] pListOfAccessEntries

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

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

[in] cCountOfAuditEntries

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

[in, optional] pListOfAuditEntries

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

Если pListOfAuditEntriesnull, новый дескриптор безопасности получает saCL из pOldSD. В этом случае, если pOldSDNULLили SACL в pOldSDNULL, новый 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 [только классические приложения]
целевая платформа	Виндоус
заголовка	aclapi.h
библиотеки	Advapi32.lib
DLL	Advapi32.dll