Compartilhar via


Função AdjustTokenGroups (securitybaseapi.h)

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

Confira também

Visão geral do Controle de Acesso

AdjustTokenPrivileges

Funções básicas de Controle de Acesso

Createrestrictedtoken

GetTokenInformation

OpenProcessToken

Openthreadtoken

SetTokenInformation

TOKEN_GROUPS