Funzione AdjustTokenGroups (securitybaseapi.h)

Articolo
08/25/2023

La funzione AdjustTokenGroups abilita o disabilita i gruppi già presenti nel token di accesso specificato. L'accesso a TOKEN_ADJUST_GROUPS è necessario per abilitare o disabilitare i gruppi in un token di accesso.

Sintassi

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

Parametri

[in] TokenHandle

Handle per il token di accesso che contiene i gruppi da abilitare o disabilitare. L'handle deve avere TOKEN_ADJUST_GROUPS l'accesso al token. Se il parametro PreviousState non è NULL, l'handle deve avere anche accesso TOKEN_QUERY.

[in] ResetToDefault

Valore booleano che indica se i gruppi devono essere impostati sui relativi stati predefiniti abilitati e disabilitati. Se questo valore è TRUE, i gruppi vengono impostati sui relativi stati predefiniti e il parametro NewState viene ignorato. Se questo valore è FALSE, i gruppi vengono impostati in base alle informazioni a cui fa riferimento il parametro NewState .

[in, optional] NewState

Puntatore a una struttura TOKEN_GROUPS che contiene i gruppi da abilitare o disabilitare. Se il parametro ResetToDefault è FALSE, la funzione imposta ognuno dei gruppi sul valore dell'attributo SE_GROUP_ENABLED del gruppo nella struttura TOKEN_GROUPS . Se ResetToDefault è TRUE, questo parametro viene ignorato.

[in] BufferLength

Dimensione, in byte, del buffer a cui punta il parametro PreviousState . Questo parametro può essere zero se il parametro PreviousState è NULL.

[out, optional] PreviousState

Puntatore a un buffer che riceve una struttura TOKEN_GROUPS contenente lo stato precedente di tutti i gruppi che la funzione modifica. Ovvero, se un gruppo è stato modificato da questa funzione, il gruppo e il relativo stato precedente sono contenuti nella struttura TOKEN_GROUPS a cui fa riferimento PreviousState. Se il membro GroupCount di TOKEN_GROUPS è zero, questa funzione non ha modificato alcun gruppo. Questo parametro può essere NULL.

Se viene specificato un buffer ma non contiene spazio sufficiente per ricevere l'elenco completo dei gruppi modificati, non vengono modificati stati di gruppo e la funzione ha esito negativo. In questo caso, la funzione imposta la variabile a cui punta il parametro ReturnLength sul numero di byte necessari per contenere l'elenco completo dei gruppi modificati.

[out, optional] ReturnLength

Puntatore a una variabile che riceve il numero effettivo di byte necessari per il buffer a cui punta il parametro PreviousState . Questo parametro può essere NULL e viene ignorato se PreviousState è NULL.

Valore restituito

Se la funzione ha esito positivo, il valore restituito è diverso da zero.

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

Commenti

Le informazioni recuperate nel parametro PreviousState vengono formattate come struttura TOKEN_GROUPS . Ciò significa che un puntatore al buffer può essere passato come parametro NewState in una chiamata successiva alla funzione AdjustTokenGroups , ripristinando lo stato originale dei gruppi.

Il parametro NewState può elencare i gruppi da modificare che non sono presenti nel token di accesso. Ciò non influisce sulla corretta modifica dei gruppi nel token.

La funzione AdjustTokenGroups non può disabilitare i gruppi con l'attributo SE_GROUP_MANDATORY nella struttura TOKEN_GROUPS . Usare invece CreateRestrictedToken .

Non è possibile abilitare un gruppo con l'attributo SE_GROUP_USE_FOR_DENY_ONLY.

Requisiti


Client minimo supportato	Windows XP [app desktop \| App UWP]
Server minimo supportato	Windows Server 2003 [app desktop \| App UWP]
Piattaforma di destinazione	Windows
Intestazione	securitybaseapi.h (include Windows.h)
Libreria	Advapi32.lib
DLL	Advapi32.dll