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

Статья
11/20/2024

Эта версия этой функции не поддерживается. Поддерживается широкая версия этой функции, TreeSetNamedSecurityInfoW.

Синтаксис

DWORD TreeSetNamedSecurityInfoA(
  [in]           LPSTR                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

Указатель на строку null-terminated, указывающую имя объекта корневого узла для объектов, которые должны получать обновленные сведения о безопасности. Поддерживаемые объекты — это разделы реестра и объекты файлов. Описание строковых форматов для различных типов объектов см. в 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

Указатель на структуру идентификатора безопасности , которая определяет основную группу объекта. Параметр 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 привилегии. Если этот параметр не задан, этот параметр можно NULL.

[in] dwAction

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

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

[in] fnProgress

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

#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
);

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

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

[in] ProgressInvokeSetting

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

[in, optional] Args

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

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

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

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

Замечания

Настройка null владельца, группы, DACL или SACL не поддерживается этой функцией.

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

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

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

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

Заметка

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

Требования

Требование	Ценность
минимальные поддерживаемые клиентские	Windows Vista [только классические приложения]
минимальный поддерживаемый сервер	Windows Server 2008 [только классические приложения]
целевая платформа	Виндоус
заголовка	aclapi.h
библиотеки	Advapi32.lib
DLL	Advapi32.dll

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