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

Статья
11/20/2024

Функция 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
Сетевые ресурсы
Разделы реестра
Семафоры, события, мьютексы и ожидающие таймеры
Объекты сопоставления файлов
Объекты службы каталогов

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

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

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

Примеры

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

Заметка

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

Требования

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