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

Статья
08/22/2023

Функция GetNamedSecurityInfo извлекает копию дескриптора безопасности для объекта, указанного по имени.

Синтаксис

DWORD GetNamedSecurityInfoA(
  [in]            LPCSTR               pObjectName,
  [in]            SE_OBJECT_TYPE       ObjectType,
  [in]            SECURITY_INFORMATION SecurityInfo,
  [out, optional] PSID                 *ppsidOwner,
  [out, optional] PSID                 *ppsidGroup,
  [out, optional] PACL                 *ppDacl,
  [out, optional] PACL                 *ppSacl,
  [out, optional] PSECURITY_DESCRIPTOR *ppSecurityDescriptor
);

Параметры

[in] pObjectName

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

[in] ObjectType

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

[in] SecurityInfo

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

[out, optional] ppsidOwner

Указатель на переменную, получающую указатель на идентификатор безопасности владельца в дескрипторе безопасности , возвращаемом в ppSecurityDescriptor или NULL , если дескриптор безопасности не имеет идентификатора безопасности владельца. Возвращаемый указатель действителен только в том случае, если вы задали флаг OWNER_SECURITY_INFORMATION. Кроме того, этот параметр может иметь значение NULL , если идентификатор безопасности владельца не нужен.

[out, optional] ppsidGroup

Указатель на переменную, которая получает указатель на идентификатор безопасности основной группы в возвращенном дескрипторе безопасности или значение NULL , если дескриптор безопасности не имеет идентификатора безопасности группы. Возвращаемый указатель действителен только в том случае, если задан флаг GROUP_SECURITY_INFORMATION. Кроме того, этот параметр может иметь значение NULL , если идентификатор безопасности группы не нужен.

[out, optional] ppDacl

Указатель на переменную, которая получает указатель на DACL в возвращаемом дескрипторе безопасности или ЗНАЧЕНИЕ NULL , если дескриптор безопасности не содержит DACL. Возвращаемый указатель действителен только в том случае, если задан флаг DACL_SECURITY_INFORMATION. Кроме того, этот параметр может иметь значение NULL , если не требуется DACL.

[out, optional] ppSacl

Указатель на переменную, которая получает указатель на SACL в возвращаемом дескрипторе безопасности или ЗНАЧЕНИЕ NULL , если дескриптор безопасности не имеет SACL. Возвращаемый указатель действителен только в том случае, если установлен флаг SACL_SECURITY_INFORMATION. Кроме того, этот параметр может иметь значение NULL , если saCL не требуется.

[out, optional] ppSecurityDescriptor

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

Этот параметр является обязательным, если любой из параметров ppsidOwner, ppsidGroup, ppDacl или ppSacl не имеет значения NULL.

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

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

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

Если какой-либо из параметров ppsidOwner, ppsidGroup, ppDacl или ppSacl не равен NULL, а параметр SecurityInfo указывает, что они будут получены из объекта , эти параметры будут указывать на соответствующие параметры в дескрипторе безопасности , возвращенном в ppSecurityDescriptor. Если дескриптор безопасности не содержит запрошенных сведений, соответствующий параметр будет иметь значение NULL.

Чтобы считать владельца, группу или DACL из дескриптора безопасности объекта, DACL объекта должен предоставить READ_CONTROL доступ вызывающему объекту, или вызывающий объект должен быть владельцем объекта.

Чтобы прочитать системный список управления доступом объекта, необходимо включить SE_SECURITY_NAME привилегию для вызывающего процесса. Сведения о последствиях для безопасности при включении привилегий см. в разделе Запуск с особыми привилегиями.

Функцию GetNamedSecurityInfo можно использовать со следующими типами объектов:

Локальные или удаленные файлы или каталоги в файловой системе NTFS
Локальные или удаленные принтеры
Локальные или удаленные службы Windows
Общие сетевые ресурсы
Разделы реестра
Семафоры, события, мьютексы и таймеры ожидания
Объекты сопоставления файлов
Объекты службы каталогов

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

Эта функция передает информацию в виде открытого текста. Данные, передаваемые этой функцией, подписываются, если только подпись не была отключена для системы, но шифрование не выполняется.

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

Примеры

Пример использования GetNamedSecurityInfo см. в разделе Изменение списков управления доступом объекта.

Примечание

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

Требования

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