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

Статья
25.08.2023

Функция AddAce добавляет одну или несколько записей управления доступом (ACE) в указанный список управления доступом (ACL).

Синтаксис

BOOL AddAce(
  [in, out] PACL   pAcl,
  [in]      DWORD  dwAceRevision,
  [in]      DWORD  dwStartingAceIndex,
  [in]      LPVOID pAceList,
  [in]      DWORD  nAceListLength
);

Параметры

[in, out] pAcl

Указатель на список ACL. Эта функция добавляет ACE в этот список ACL.

[in] dwAceRevision

Указывает уровень редакции изменяемого списка управления.

Это значение может быть ACL_REVISION или ACL_REVISION_DS. Используйте ACL_REVISION_DS, если список ACL содержит ACE для конкретных объектов. Это значение должно быть совместимо с полем AceType всех ACE в pAceList. В противном случае функция завершится сбоем и присвоит последней ошибке значение ERROR_INVALID_PARAMETER.

[in] dwStartingAceIndex

Указывает позицию в списке ACL ACE для добавления новых ACE. Нулевое значение вставляет ACE в начало списка. Значение MAXDWORD добавляет ACE в конец списка.

[in] pAceList

Указатель на список одного или нескольких ACE, добавляемых в указанный список ACL. ACE в списке должны храниться непрерывно.

[in] nAceListLength

Указывает размер входного буфера в байтах, на который указывает параметр pAceList .

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

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

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

Код возврата	Описание
ERROR_INSUFFICIENT_BUFFER	Новый ACE не помещается в список ACL. Требуется больший буфер ACL.
ERROR_INVALID_PARAMETER	Указанный список ACL неправильно сформирован.
ERROR_SUCCESS	ACE успешно добавлен.

Приложения часто используют функции FindFirstFreeAce и GetAce при использовании функции AddAce для управления ACL. Кроме того, структура ACL_SIZE_INFORMATION , извлекаемая функцией GetAclInformation , содержит размер списка ACL и количество ACE, которые он содержит.

Примеры

Пример использования этой функции см. в разделе Запуск интерактивного клиентского процесса.

Требования

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