AdjustTokenGroups-Funktion (securitybaseapi.h)

Artikel
08/25/2023

Die Funktion AdjustTokenGroups aktiviert oder deaktiviert Gruppen, die bereits im angegebenen Zugriffstoken vorhanden sind. Der Zugriff auf TOKEN_ADJUST_GROUPS ist erforderlich, um Gruppen in einem Zugriffstoken zu aktivieren oder zu deaktivieren.

Syntax

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

Parameter

[in] TokenHandle

Ein Handle für das Zugriffstoken, das die zu aktivierenden oder deaktivierten Gruppen enthält. Das Handle muss TOKEN_ADJUST_GROUPS Zugriff auf das Token haben. Wenn der PreviousState-Parameter nicht NULL ist, muss das Handle auch über TOKEN_QUERY Zugriff verfügen.

[in] ResetToDefault

Boolescher Wert, der angibt, ob die Gruppen auf ihre standardmäßig aktivierten und deaktivierten Zustände festgelegt werden sollen. Wenn dieser Wert TRUE ist, werden die Gruppen auf ihre Standardzustände festgelegt, und der NewState-Parameter wird ignoriert. Wenn dieser Wert FALSE ist, werden die Gruppen entsprechend den Informationen festgelegt, auf die der NewState-Parameter verweist.

[in, optional] NewState

Ein Zeiger auf eine TOKEN_GROUPS Struktur, die die zu aktivierenden oder deaktivierten Gruppen enthält. Wenn der ResetToDefault-ParameterFALSE ist, legt die Funktion jede der Gruppen auf den Wert des SE_GROUP_ENABLED-Attributs dieser Gruppe in der TOKEN_GROUPS-Struktur fest. Wenn ResetToDefaultTRUE ist, wird dieser Parameter ignoriert.

[in] BufferLength

Die Größe des Puffers in Bytes, auf die der PreviousState-Parameter verweist. Dieser Parameter kann null sein, wenn der PreviousState-ParameterNULL ist.

[out, optional] PreviousState

Ein Zeiger auf einen Puffer, der eine TOKEN_GROUPS Struktur empfängt, die den vorherigen Zustand aller Gruppen enthält, die die Funktion ändert. Das heißt, wenn eine Gruppe von dieser Funktion geändert wurde, sind die Gruppe und ihr vorheriger Zustand in der TOKEN_GROUPS Struktur enthalten, auf die von PreviousState verwiesen wird. Wenn das GroupCount-Mitglied von TOKEN_GROUPS null ist, wurden von dieser Funktion keine Gruppen geändert. Dieser Parameter kann NULL sein.

Wenn ein Puffer angegeben ist, der jedoch nicht genügend Speicherplatz enthält, um die vollständige Liste der geänderten Gruppen zu empfangen, werden keine Gruppenzustände geändert, und die Funktion schlägt fehl. In diesem Fall legt die Funktion die Variable, auf die der ReturnLength-Parameter verweist, auf die Anzahl der Bytes fest, die erforderlich sind, um die vollständige Liste der geänderten Gruppen zu enthalten.

[out, optional] ReturnLength

Ein Zeiger auf eine Variable, die die tatsächliche Anzahl von Bytes empfängt, die für den Puffer benötigt werden, auf den der PreviousState-Parameter verweist. Dieser Parameter kann NULL sein und wird ignoriert, wenn PreviousStateNULL ist.

Rückgabewert

Wenn die Funktion erfolgreich ist, ist der Rückgabewert ungleich Null.

Wenn die Funktion fehlerhaft ist, ist der Rückgabewert null. Um erweiterte Fehlerinformationen zu erhalten, rufen Sie GetLastError auf.

Hinweise

Die im PreviousState-Parameter abgerufenen Informationen sind als TOKEN_GROUPS-Struktur formatiert. Dies bedeutet, dass ein Zeiger auf den Puffer als NewState-Parameter in einem nachfolgenden Aufruf der AdjustTokenGroups-Funktion übergeben werden kann, um den ursprünglichen Zustand der Gruppen wiederherzustellen.

Der NewState-Parameter kann Zu ändernde Gruppen auflisten, die nicht im Zugriffstoken vorhanden sind. Dies wirkt sich nicht auf die erfolgreiche Änderung der Gruppen im Token aus.

Die Funktion AdjustTokenGroups kann Gruppen mit dem Attribut SE_GROUP_MANDATORY in der TOKEN_GROUPS-Struktur nicht deaktivieren. Verwenden Sie stattdessen CreateRestrictedToken .

Sie können keine Gruppe aktivieren, die über das Attribut SE_GROUP_USE_FOR_DENY_ONLY verfügt.

Anforderungen


Unterstützte Mindestversion (Client)	Windows XP [Desktop-Apps \| UWP-Apps]
Unterstützte Mindestversion (Server)	Windows Server 2003 [Desktop-Apps \| UWP-Apps]
Zielplattform	Windows
Kopfzeile	securitybaseapi.h (einschließlich Windows.h)
Bibliothek	Advapi32.lib
DLL	Advapi32.dll