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

  • Статья

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

#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.

Комментарии

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

Если вызывающий объект не содержит необходимых привилегий и разрешений для поддержки запрошенных обновлений владельца, группы, 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 или Юникод этой функции на основе определения константы препроцессора UNICODE. Сочетание использования псевдонима, не зависящий от кодировки, с кодом, не зависящим от кодировки, может привести к несоответствиям, которые приводят к ошибкам компиляции или среды выполнения. Дополнительные сведения см. в разделе Соглашения для прототипов функций.

Требования

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