Funzione AdjustTokenPrivileges (securitybaseapi.h)

La funzione AdjustTokenPrivileges abilita o disabilita i privilegi nel token di accesso specificato. L'abilitazione o la disabilitazione dei privilegi in un token di accesso richiede TOKEN_ADJUST_PRIVILEGES accesso.

Sintassi

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

Parametri

[in] TokenHandle

Handle per il token di accesso che contiene i privilegi da modificare. L'handle deve avere TOKEN_ADJUST_PRIVILEGES accesso al token. Se il parametro PreviousState non è NULL, l'handle deve avere anche accesso TOKEN_QUERY.

[in] DisableAllPrivileges

Specifica se la funzione disabilita tutti i privilegi del token. Se questo valore è TRUE, la funzione disabilita tutti i privilegi e ignora il parametro NewState . Se è FALSE, la funzione modifica i privilegi in base alle informazioni a cui punta il parametro NewState .

[in, optional] NewState

Puntatore a una struttura TOKEN_PRIVILEGES che specifica una matrice di privilegi e i relativi attributi. Se il parametro DisableAllPrivileges è FALSE, la funzione AdjustTokenPrivileges abilita, disabilita o rimuove questi privilegi per il token. La tabella seguente descrive l'azione eseguita dalla funzione AdjustTokenPrivileges , in base all'attributo dei privilegi.

Se DisableAllPrivileges è TRUE, la funzione ignora questo parametro.

[in] BufferLength

Specifica le dimensioni, in byte, del buffer a cui fa riferimento il parametro PreviousState . Questo parametro può essere zero se il parametro PreviousState è NULL.

[out, optional] PreviousState

Puntatore a un buffer che la funzione riempie con una struttura TOKEN_PRIVILEGES contenente lo stato precedente di tutti i privilegi che la funzione modifica. Ovvero, se un privilegio è stato modificato da questa funzione, il privilegio e il relativo stato precedente sono contenuti nella struttura TOKEN_PRIVILEGES a cui fa riferimento PreviousState. Se il membro PrivilegeCount di TOKEN_PRIVILEGES è zero, non sono stati modificati privilegi da questa funzione. Questo parametro può essere NULL.

Se si specifica un buffer troppo piccolo per ricevere l'elenco completo dei privilegi modificati, la funzione non riesce e non modifica i privilegi. In questo caso, la funzione imposta la variabile puntata dal parametro ReturnLength al numero di byte necessari per contenere l'elenco completo dei privilegi modificati.

[out, optional] ReturnLength

Puntatore a una variabile che riceve le dimensioni necessarie, in byte, del buffer a cui punta il parametro PreviousState . Questo parametro può essere NULL se PreviousState è NULL.

Valore restituito

Se la funzione ha esito positivo, il valore restituito è diverso da zero. Per determinare se la funzione ha modificato tutti i privilegi specificati, chiamare GetLastError, che restituisce uno dei valori seguenti quando la funzione ha esito positivo:

Se la funzione ha esito negativo, il valore restituito è zero. Per informazioni dettagliate sull'errore, chiamare GetLastError.

Commenti

La funzione AdjustTokenPrivileges non può aggiungere nuovi privilegi al token di accesso. Può abilitare o disabilitare solo i privilegi esistenti del token. Per determinare i privilegi del token, chiamare la funzione GetTokenInformation .

Il parametro NewState può specificare i privilegi che il token non ha, senza causare l'esito negativo della funzione. In questo caso, la funzione regola i privilegi che il token ha e ignora gli altri privilegi in modo che la funzione abbia esito positivo. Chiamare la funzione GetLastError per determinare se la funzione ha modificato tutti i privilegi specificati. Il parametro PreviousState indica i privilegi modificati.

Il parametro PreviousState recupera una struttura TOKEN_PRIVILEGES che contiene lo stato originale dei privilegi modificati. Per ripristinare lo stato originale, passare il puntatore PreviousState come parametro NewState in una chiamata successiva alla funzione AdjustTokenPrivileges .

Esempio

Per un esempio che usa questa funzione, vedere Abilitazione e disabilitazione dei privilegi.

Requisiti

Vedi anche

Panoramica Controllo di accesso

AdjustTokenGroups

Funzioni di base Controllo di accesso

GetTokenInformation

OpenProcessToken

OpenThreadToken

SetTokenInformation

TOKEN_PRIVILEGES