Функция AdjustTokenGroups (securitybaseapi.h)

Статья
08/25/2023

Функция AdjustTokenGroups включает или отключает группы, уже присутствующие в указанном маркере доступа. Доступ к TOKEN_ADJUST_GROUPS необходим для включения или отключения групп в маркере доступа.

Синтаксис

BOOL AdjustTokenGroups(
  [in]            HANDLE        TokenHandle,
  [in]            BOOL          ResetToDefault,
  [in, optional]  PTOKEN_GROUPS NewState,
  [in]            DWORD         BufferLength,
  [out, optional] PTOKEN_GROUPS PreviousState,
  [out, optional] PDWORD        ReturnLength
);

Параметры

[in] TokenHandle

Дескриптор маркера доступа, содержащего группы, которые необходимо включить или отключить. Дескриптор должен иметь TOKEN_ADJUST_GROUPS доступ к маркеру. Если параметр PreviousState не имеет значение NULL, дескриптор также должен иметь доступ к TOKEN_QUERY.

[in] ResetToDefault

Логическое значение, указывающее, следует ли задать для групп состояние "Включено" и "Отключено" по умолчанию. Если это значение равно TRUE, группам присваиваются состояния по умолчанию, а параметр NewState игнорируется. Если это значение равно FALSE, группы задаются в соответствии со сведениями, на которые указывает параметр NewState .

[in, optional] NewState

Указатель на структуру TOKEN_GROUPS , содержащую группы для включения или отключения. Если параметр ResetToDefault имеет значение FALSE, функция присваивает каждой из групп значение атрибута SE_GROUP_ENABLED этой группы в структуре TOKEN_GROUPS . Если параметр ResetToDefault имеет значение TRUE, этот параметр игнорируется.

[in] BufferLength

Размер (в байтах) буфера, на который указывает параметр PreviousState . Этот параметр может быть равен нулю, если параметр PreviousState имеет значение NULL.

[out, optional] PreviousState

Указатель на буфер, получающий TOKEN_GROUPS структуру, содержащую предыдущее состояние всех групп, которые изменяет функция. То есть, если группа была изменена этой функцией, группа и ее предыдущее состояние содержатся в структуре TOKEN_GROUPS , на которую ссылается PreviousState. Если элемент GroupCountTOKEN_GROUPS равен нулю, то эта функция не изменила ни один из групп. Этот параметр может принимать значение NULL.

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

[out, optional] ReturnLength

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

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

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

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

Сведения, полученные в параметре PreviousState, форматируются в виде TOKEN_GROUPS структуры. Это означает, что указатель на буфер можно передать в качестве параметра NewState при последующем вызове функции AdjustTokenGroups , восстанавливая исходное состояние групп.

Параметр NewState может выводить список изменяющихся групп, которые отсутствуют в маркере доступа. Это не влияет на успешное изменение групп в маркере.

Функция AdjustTokenGroups не может отключить группы с атрибутом SE_GROUP_MANDATORY в структуре TOKEN_GROUPS . Вместо этого используйте CreateRestrictedToken .

Нельзя включить группу с атрибутом SE_GROUP_USE_FOR_DENY_ONLY.

Требования


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