Compartilhar via


Função AdjustTokenPrivileges (securitybaseapi.h)

A função AdjustTokenPrivileges habilita ou desabilita privilégios no token de acesso especificado. Habilitar ou desabilitar privilégios em um token de acesso requer acesso TOKEN_ADJUST_PRIVILEGES.

Sintaxe

BOOL AdjustTokenPrivileges(
  [in]            HANDLE            TokenHandle,
  [in]            BOOL              DisableAllPrivileges,
  [in, optional]  PTOKEN_PRIVILEGES NewState,
  [in]            DWORD             BufferLength,
  [out, optional] PTOKEN_PRIVILEGES PreviousState,
  [out, optional] PDWORD            ReturnLength
);

Parâmetros

[in] TokenHandle

Um identificador para o token de acesso que contém os privilégios a serem modificados. O identificador deve ter TOKEN_ADJUST_PRIVILEGES acesso ao token. Se o parâmetro PreviousState não for NULL, o identificador também deverá ter acesso TOKEN_QUERY.

[in] DisableAllPrivileges

Especifica se a função desabilita todos os privilégios do token. Se esse valor for TRUE, a função desabilitará todos os privilégios e ignorará o parâmetro NewState . Se for FALSE, a função modificará privilégios com base nas informações apontadas pelo parâmetro NewState .

[in, optional] NewState

Um ponteiro para uma estrutura TOKEN_PRIVILEGES que especifica uma matriz de privilégios e seus atributos. Se o parâmetro DisableAllPrivileges for FALSE, a função AdjustTokenPrivileges habilitará, desabilitará ou removerá esses privilégios para o token. A tabela a seguir descreve a ação executada pela função AdjustTokenPrivileges , com base no atributo privilege.

Valor Significado
SE_PRIVILEGE_ENABLED
A função habilita o privilégio.
SE_PRIVILEGE_REMOVED
O privilégio é removido da lista de privilégios no token. Os outros privilégios na lista são reordenados para permanecer contíguos.

SE_PRIVILEGE_REMOVED substitui SE_PRIVILEGE_ENABLED.

Como o privilégio foi removido do token, as tentativas de reabilitar o privilégio resultam no aviso ERROR_NOT_ALL_ASSIGNED como se o privilégio nunca tivesse existido.

Tentar remover um privilégio que não existe no token resulta em ERROR_NOT_ALL_ASSIGNED sendo retornado.

Verificações de privilégios para privilégios removidos resultam em STATUS_PRIVILEGE_NOT_HELD. Falha no privilégio marcar auditoria ocorre normalmente.

A remoção do privilégio é irreversível, portanto, o nome do privilégio removido não é incluído no parâmetro PreviousState após uma chamada para AdjustTokenPrivileges.

Windows XP com SP1: A função não pode remover privilégios. Não há suporte para esse valor.

Nenhuma
A função desabilita o privilégio.
 

Se DisableAllPrivileges for TRUE, a função ignorará esse parâmetro.

[in] BufferLength

Especifica 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 a função preenche com uma estrutura TOKEN_PRIVILEGES que contém o estado anterior de quaisquer privilégios modificados pela função. Ou seja, se um privilégio tiver sido modificado por essa função, o privilégio e seu estado anterior estarão contidos na estrutura TOKEN_PRIVILEGES referenciada por PreviousState. Se o membro PrivilegeCount de TOKEN_PRIVILEGES for zero, nenhum privilégio foi alterado por essa função. Este parâmetro pode ser NULL.

Se você especificar um buffer muito pequeno para receber a lista completa de privilégios modificados, a função falhará e não ajustará nenhum privilégio. 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 privilégios modificados.

[out, optional] ReturnLength

Um ponteiro para uma variável que recebe o tamanho necessário, em bytes, do buffer apontado pelo parâmetro PreviousState . Esse parâmetro poderá ser NULL se PreviousState for NULL.

Valor retornado

Se a função for bem-sucedida, o valor retornado será diferente de zero. Para determinar se a função ajustou todos os privilégios especificados, chame GetLastError, que retorna um dos seguintes valores quando a função é bem-sucedida:

Código de retorno Descrição
ERROR_SUCCESS
A função ajustou todos os privilégios especificados.
ERROR_NOT_ALL_ASSIGNED
O token não tem um ou mais dos privilégios especificados no parâmetro NewState . A função pode ter êxito com esse valor de erro mesmo que nenhum privilégio tenha sido ajustado. O parâmetro PreviousState indica os privilégios que foram ajustados.
 

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

Comentários

A função AdjustTokenPrivileges não pode adicionar novos privilégios ao token de acesso. Ele só pode habilitar ou desabilitar os privilégios existentes do token. Para determinar os privilégios do token, chame a função GetTokenInformation .

O parâmetro NewState pode especificar privilégios que o token não tem, sem causar falha na função. Nesse caso, a função ajusta os privilégios que o token tem e ignora os outros privilégios para que a função seja bem-sucedida. Chame a função GetLastError para determinar se a função ajustou todos os privilégios especificados. O parâmetro PreviousState indica os privilégios que foram ajustados.

O parâmetro PreviousState recupera uma estrutura TOKEN_PRIVILEGES que contém o estado original dos privilégios ajustados. Para restaurar o estado original, passe o ponteiro PreviousState como o parâmetro NewState em uma chamada subsequente para a função AdjustTokenPrivileges .

Exemplos

Para obter um exemplo que usa essa função, consulte Habilitando e desabilitando privilégios.

Requisitos

Requisito Valor
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

AdjustTokenGroups

Funções de Controle de Acesso básicas

GetTokenInformation

OpenProcessToken

Openthreadtoken

SetTokenInformation

TOKEN_PRIVILEGES