Função AdjustTokenGroups (securitybaseapi.h)

Artigo
08/25/2023

A função AdjustTokenGroups habilita ou desabilita grupos já presentes no token de acesso especificado. O acesso a TOKEN_ADJUST_GROUPS é necessário para habilitar ou desabilitar grupos em um token de acesso.

Sintaxe

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

Parâmetros

[in] TokenHandle

Um identificador para o token de acesso que contém os grupos a serem habilitados ou desabilitados. O identificador deve ter TOKEN_ADJUST_GROUPS acesso ao token. Se o parâmetro PreviousState não for NULL, o identificador também deverá ter TOKEN_QUERY acesso.

[in] ResetToDefault

Valor booliano que indica se os grupos devem ser definidos como seus estados padrão habilitados e desabilitados. Se esse valor for TRUE, os grupos serão definidos como seus estados padrão e o parâmetro NewState será ignorado. Se esse valor for FALSE, os grupos serão definidos de acordo com as informações apontadas pelo parâmetro NewState .

[in, optional] NewState

Um ponteiro para uma estrutura TOKEN_GROUPS que contém os grupos a serem habilitados ou desabilitados. Se o parâmetro ResetToDefault for FALSE, a função definirá cada um dos grupos como o valor do atributo SE_GROUP_ENABLED desse grupo na estrutura TOKEN_GROUPS . Se ResetToDefault for TRUE, esse parâmetro será ignorado.

[in] BufferLength

O tamanho, em bytes, do buffer apontado pelo parâmetro PreviousState . Esse parâmetro poderá ser zero se o parâmetro PreviousState for NULL.

[out, optional] PreviousState

Um ponteiro para um buffer que recebe uma estrutura TOKEN_GROUPS que contém o estado anterior de qualquer grupo modificado pela função. Ou seja, se um grupo tiver sido modificado por essa função, o grupo e seu estado anterior estarão contidos na estrutura TOKEN_GROUPS referenciada por PreviousState. Se o membro GroupCount de TOKEN_GROUPS for zero, nenhum grupo foi alterado por essa função. Este parâmetro pode ser NULL.

Se um buffer for especificado, mas não contiver espaço suficiente para receber a lista completa de grupos modificados, nenhum estado de grupo será alterado e a função falhará. Nesse caso, a função define a variável apontada pelo parâmetro ReturnLength como o número de bytes necessários para manter a lista completa de grupos modificados.

[out, optional] ReturnLength

Um ponteiro para uma variável que recebe o número real de bytes necessários para o buffer apontado pelo parâmetro PreviousState . Esse parâmetro pode ser NULL e será ignorado se PreviousState for NULL.

Valor retornado

Se a função for bem-sucedida, o valor retornado será diferente de zero.

Se a função falhar, o valor retornado será zero. Para obter informações de erro estendidas, chame GetLastError.

Comentários

As informações recuperadas no parâmetro PreviousState são formatadas como uma estrutura TOKEN_GROUPS . Isso significa que um ponteiro para o buffer pode ser passado como o parâmetro NewState em uma chamada subsequente para a função AdjustTokenGroups , restaurando o estado original dos grupos.

O parâmetro NewState pode listar grupos a serem alterados que não estão presentes no token de acesso. Isso não afeta a modificação bem-sucedida dos grupos no token.

A função AdjustTokenGroups não pode desabilitar grupos com o atributo SE_GROUP_MANDATORY na estrutura TOKEN_GROUPS . Em vez disso, use CreateRestrictedToken .

Não é possível habilitar um grupo que tenha o atributo SE_GROUP_USE_FOR_DENY_ONLY.

Requisitos


Cliente mínimo com suporte	Windows XP [aplicativos da área de trabalho \| aplicativos UWP]
Servidor mínimo com suporte	Windows Server 2003 [aplicativos da área de trabalho \| Aplicativos UWP]
Plataforma de Destino	Windows
Cabeçalho	securitybaseapi.h (inclua Windows.h)
Biblioteca	Advapi32.lib
DLL	Advapi32.dll