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

Статья
03/14/2023

Функция TreeSetNamedSecurityInfo задает указанные сведения о безопасности в дескрипторе безопасности указанного дерева объектов . Эта функция позволяет распространять указанный список управления доступом на уровне пользователей (DACL) или любые элементы в системном списке управления доступом (SACL) по всему дереву. Эта функция поддерживает функцию обратного вызова для отслеживания хода выполнения операции в виде дерева.

Синтаксис

DWORD TreeSetNamedSecurityInfoW(
  [in]           LPWSTR               pObjectName,
  [in]           SE_OBJECT_TYPE       ObjectType,
  [in]           SECURITY_INFORMATION SecurityInfo,
  [in, optional] PSID                 pOwner,
  [in, optional] PSID                 pGroup,
  [in, optional] PACL                 pDacl,
  [in, optional] PACL                 pSacl,
  [in]           DWORD                dwAction,
  [in]           FN_PROGRESS          fnProgress,
  [in]           PROG_INVOKE_SETTING  ProgressInvokeSetting,
  [in, optional] PVOID                Args
);

Параметры

[in] pObjectName

Указатель на строку, завершающуюся нулевым значением, которая указывает имя объекта корневого узла для объектов, которые должны получать обновленные сведения о безопасности. Поддерживаемые объекты — это разделы реестра и объекты файлов. Описание форматов строк для различных типов объектов см. в разделе SE_OBJECT_TYPE.

[in] ObjectType

Значение перечисления SE_OBJECT_TYPE , указывающее тип объекта с именем с помощью параметра pObjectName . Поддерживаются значения SE_REGISTRY_KEY и SE_FILE_OBJECT для разделов реестра и файлов, соответственно.

[in] SecurityInfo

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

[in, optional] pOwner

Указатель на структуру SID , которая определяет владельца объекта. Идентификатор безопасности должен быть идентификатором безопасности, который можно назначить в качестве идентификатора безопасности владельца дескриптора безопасности. Параметр SecurityInfo должен содержать флаг OWNER_SECURITY_INFORMATION. Чтобы задать владельца, вызывающий объект должен иметь WRITE_OWNER доступ к каждому объекту, включая корневой объект. Если идентификатор безопасности владельца не задан, этот параметр может иметь значение NULL.

[in, optional] pGroup

Указатель на структуру SID , идентифицирующая основную группу объекта. Параметр SecurityInfo должен содержать флаг GROUP_SECURITY_INFORMATION. Чтобы задать группу, вызывающий объект должен иметь WRITE_OWNER доступ к каждому объекту, включая корневой объект. Если вы не задаете идентификатор безопасности основной группы, этот параметр может иметь значение NULL.

[in, optional] pDacl

Указатель на структуру списка управления доступом (ACL), представляющую новый DACL для сбрасываемых объектов. Параметр SecurityInfo должен содержать флаг DACL_SECURITY_INFORMATION. Вызывающий объект должен иметь READ_CONTROL и WRITE_DAC доступ к каждому объекту, включая корневой объект. Если вы не задаете DACL, этот параметр может иметь значение NULL.

[in, optional] pSacl

Указатель на структуру ACL, представляющую новый saCL для сброшенных объектов. Параметр SecurityInfo должен содержать любой из следующих флагов: SACL_SECURITY_INFORMATION, LABEL_SECURITY_INFORMATION, ATTRIBUTE_SECURITY_INFORMATION, SCOPE_SECURITY_INFORMATION или BACKUP_SECURITY_INFORMATION. Если параметр SACL_SECURITY_INFORMATION или SCOPE_SECURITY_INFORMATION, у вызывающего объекта должна быть включена SE_SECURITY_NAME привилегия. Если вы не задаете SACL, этот параметр может иметь значение NULL.

[in] dwAction

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

Значение	Значение
TREE_SEC_INFO_SET 0x00000001	Сведения о безопасности задаются для объекта, заданного параметром pObjectName , и дерева дочерних объектов этого объекта. Если списки управления доступом указаны в параметрах pDacl или pSacl , дескрипторы безопасности связываются с объектом . Дескрипторы безопасности распространяются на дерево дочерних объектов на основе их свойств наследования.
TREE_SEC_INFO_RESET 0x00000002	Сведения о безопасности сбрасываются для объекта, указанного параметром pObjectName , и дерева дочерних объектов этого объекта. Все существующие сведения о безопасности удаляются из всех объектов в дереве. Если какой-либо объект в дереве не предоставляет вызывающему объекту соответствующие разрешения на изменение дескриптора безопасности объекта, то распространение сведений о безопасности на этот конкретный узел дерева и его объекты пропускается. Операция продолжается в остальной части дерева в объекте, указанном параметром pObjectName .
TREE_SEC_INFO_RESET_KEEP_EXPLICIT 0x00000003	Сведения о безопасности сбрасываются для объекта, указанного параметром pObjectName , и дерева дочерних объектов этого объекта. Все существующие унаследованные сведения о безопасности удаляются из всех объектов в дереве. Сведения о безопасности, явно заданные для объектов в дереве, не изменяются. Если какой-либо объект в дереве не предоставляет вызывающему объекту соответствующие разрешения на изменение дескриптора безопасности объекта, то распространение сведений о безопасности на этот конкретный узел дерева и его объекты пропускается. Операция продолжается в остальной части дерева в объекте, указанном параметром pObjectName .

[in] fnProgress

Указатель на функцию, используемую для отслеживания хода выполнения функции TreeSetNamedSecurityInfo . Прототип функции progress:

#include <windows.h>
#include <Aclapi.h>
#pragma comment(lib, "Advapi32.lib")

typedef VOID (*FN_PROGRESS) (
  IN LPWSTR pObjectName,              // Name of object just processed
  IN DWORD Status,                    // Status of operation on object
  IN OUT PPROG_INVOKE_SETTING
                      pInvokeSetting, // When to set
  IN PVOID Args,                      // Caller specific data
  IN BOOL SecuritySet                 // Whether security was set
);

Функция progress предоставляет вызывающей объекту сведения о ходе выполнения и об ошибке при обработке узлов. Вызывающий объект указывает функцию хода выполнения в fnProgress, а во время операции дерева TreeSetNamedSecurityInfo передает имя последнего обработанного объекта, состояние ошибки этой операции и текущее значение PROG_INVOKE_SETTING. Вызывающий объект может изменить значение PROG_INVOKE_SETTING с помощью pInvokeSetting.

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

[in] ProgressInvokeSetting

Значение перечисления PROG_INVOKE_SETTING , указывающее начальное значение для функции хода выполнения.

[in, optional] Args

Указатель на VOID для аргументов функции хода выполнения, заданных вызывающим объектом.

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

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

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

Если вызывающий объект не содержит необходимых привилегий и разрешений для поддержки запрошенных обновлений владельца, группы, DACL и SACL, ни одно из обновлений не выполняется.

Эта функция предоставляет те же функциональные возможности, что и функция SetNamedSecurityInfo , если для параметра dwAction задано значение TREE_SEC_INFO_SET, для параметра ProgressInvokeSetting задано значение ProgressInvokePrePostError, а функция, на которую указывает параметр fnProgress , устанавливает для параметра pInvokeSetting значение ProgressInvokePrePostError.

Эта функция аналогична функции TreeResetNamedSecurityInfo :

Если параметру dwActionобъекта TreeSetNamedSecurityInfo присвоено значение TREE_SEC_INFO_RESET_KEEP_EXPLICIT, то функция эквивалентна TreeResetNamedSecurityInfo , а для параметра KeepExplicit задано значение TRUE.
Если параметру dwActionобъекта TreeSetNamedSecurityInfo присвоено значение TREE_SEC_INFO_RESET, то функция эквивалентна TreeResetNamedSecurityInfo , а для параметра KeepExplicit задано значение FALSE.

Примечание

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

Требования

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

Поделиться через

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

Синтаксис

Параметры

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

Комментарии

Требования

Обратная связь

Дополнительные ресурсы