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

Статья
03/15/2023

Функция AddAccessAllowedObjectAce добавляет запись управления доступом (ACE) в конец списка управления доступом на уровне пользователей (DACL). Новый ACE может предоставлять доступ к объекту, набору свойств или свойству объекта. Вы также можете использовать AddAccessAllowedObjectAce для добавления ACE, который может наследовать только указанный тип дочернего объекта.

Синтаксис

BOOL AddAccessAllowedObjectAce(
  [in, out]      PACL  pAcl,
  [in]           DWORD dwAceRevision,
  [in]           DWORD AceFlags,
  [in]           DWORD AccessMask,
  [in, optional] GUID  *ObjectTypeGuid,
  [in, optional] GUID  *InheritedObjectTypeGuid,
  [in]           PSID  pSid
);

Параметры

[in, out] pAcl

Указатель на DACL. Функция AddAccessAllowedObjectAce добавляет разрешенный доступ ACE в конец этого DACL. ACE имеет форму структуры ACCESS_ALLOWED_OBJECT_ACE .

[in] dwAceRevision

Указывает уровень редакции изменяемого списка DACL. Это значение должно быть ACL_REVISION_DS. Если уровень редакции DACL ниже ACL_REVISION_DS, функция изменяет его на ACL_REVISION_DS.

[in] AceFlags

Набор битовых флагов, управляющих наследованием ACE. Функция задает эти флаги в элементе AceFlagsACE_HEADER структуры нового ACE. Этот параметр может быть сочетанием следующих значений.

Значение	Значение
CONTAINER_INHERIT_ACE	ACE наследуется объектами контейнера.
INHERIT_ONLY_ACE	ACE не применяется к объекту, которому назначен список управления доступом ( ACL), но он может быть унаследован дочерними объектами.
INHERITED_ACE	Указывает наследуемый элемент ACE. Этот флаг позволяет операциям, изменяющим безопасность в дереве объектов, изменять унаследованные ACE, при этом не изменяя ACE, которые были непосредственно применены к объекту.
NO_PROPAGATE_INHERIT_ACE	Биты OBJECT_INHERIT_ACE и CONTAINER_INHERIT_ACE не распространяются на унаследованный ACE.
OBJECT_INHERIT_ACE	ACE наследуется неконтейнерными объектами.

[in] AccessMask

Набор битовых флагов, использующих формат ACCESS_MASK . Эти флаги указывают права доступа, которые новый ACE разрешает для указанного идентификатора безопасности (SID).

[in, optional] ObjectTypeGuid

Указатель на структуру GUID , которая определяет тип объекта, набор свойств или свойство, защищенное новым ACE. Если этот параметр имеет значение NULL, новый ACE защищает объект, которому назначен daCL.

[in, optional] InheritedObjectTypeGuid

Указатель на структуру GUID , которая определяет тип объекта, который может наследовать новый ACE. Если этот параметр не равен NULL, наследовать ACE может только указанный тип объекта. При значении NULL любой тип дочернего объекта может наследовать ACE. В любом случае наследование также управляется значением параметра AceFlags , а также любой защитой от наследования дочерних объектов.

[in] pSid

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

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

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

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

Код возврата	Описание
ERROR_ALLOTTED_SPACE_EXCEEDED	Новый ACE не помещается в список ACL. Требуется больший буфер ACL.
ERROR_INVALID_ACL	Указанный список ACL неправильно сформирован.
ERROR_INVALID_FLAGS	Недопустимый параметр AceFlags .
ERROR_INVALID_SID	Указанный идентификатор безопасности не является структурно допустимым.
ERROR_REVISION_MISMATCH	Указанная редакция неизвестна или несовместима с редакцией ACL.
ERROR_SUCCESS	ACE успешно добавлен.

Если objectTypeGuid и InheritedObjectTypeGuid имеют значение NULL, используйте функцию AddAccessAllowedAceEx вместо AddAccessAllowedObjectAce. Это объясняется тем, что ACCESS_ALLOWED_ACE меньше и эффективнее , чем ACCESS_ALLOWED_OBJECT_ACE.

Вызывающий объект должен убедиться, что ACE добавлены в DACL в правильном порядке. Дополнительные сведения см. в разделе Порядок ACE в DACL.

Требования

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