AdjustTokenPrivileges-Funktion (securitybaseapi.h)

Die Funktion AdjustTokenPrivileges aktiviert oder deaktiviert Berechtigungen im angegebenen Zugriffstoken. Das Aktivieren oder Deaktivieren von Berechtigungen in einem Zugriffstoken erfordert TOKEN_ADJUST_PRIVILEGES Zugriff.

Syntax

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

Parameter

[in] TokenHandle

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

[in] DisableAllPrivileges

Gibt an, ob die Funktion alle Berechtigungen des Tokens deaktiviert. Wenn dieser Wert TRUE ist, deaktiviert die Funktion alle Berechtigungen und ignoriert den NewState-Parameter . Wenn es FALSE ist, ändert die Funktion Berechtigungen basierend auf den Informationen, auf die der NewState-Parameter verweist.

[in, optional] NewState

Ein Zeiger auf eine TOKEN_PRIVILEGES-Struktur , die ein Array von Berechtigungen und deren Attribute angibt. Wenn der DisableAllPrivileges-ParameterFALSE ist, aktiviert, deaktiviert oder entfernt die Funktion AdjustTokenPrivileges diese Berechtigungen für das Token. In der folgenden Tabelle wird die Aktion beschrieben, die von der Funktion AdjustTokenPrivileges basierend auf dem Berechtigungsattribut ausgeführt wird.

Wenn DisableAllPrivilegesTRUE ist, ignoriert die Funktion diesen Parameter.

[in] BufferLength

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

[out, optional] PreviousState

Ein Zeiger auf einen Puffer, den die Funktion mit einer TOKEN_PRIVILEGES-Struktur füllt, die den vorherigen Status aller Berechtigungen enthält, die die Funktion ändert. Das heißt, wenn eine Berechtigung von dieser Funktion geändert wurde, sind die Berechtigung und ihr vorheriger Zustand in der TOKEN_PRIVILEGES Struktur enthalten, auf die von PreviousState verwiesen wird. Wenn das PrivilegeCount-Element von TOKEN_PRIVILEGES null ist, wurden von dieser Funktion keine Berechtigungen geändert. Dieser Parameter kann NULL sein.

Wenn Sie einen Puffer angeben, der zu klein ist, um die vollständige Liste der geänderten Berechtigungen zu erhalten, schlägt die Funktion fehl und passt keine Berechtigungen an. 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 Berechtigungen zu enthalten.

[out, optional] ReturnLength

Ein Zeiger auf eine Variable, die die erforderliche Größe des Puffers in Bytes empfängt, auf den der PreviousState-Parameter verweist. Dieser Parameter kann NULL sein, wenn PreviousStateNULL ist.

Rückgabewert

Wenn die Funktion erfolgreich ist, ist der Rückgabewert ungleich Null. Um zu ermitteln, ob die Funktion alle angegebenen Berechtigungen angepasst hat, rufen Sie GetLastError auf, wodurch einer der folgenden Werte zurückgegeben wird, wenn die Funktion erfolgreich ist:

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

Hinweise

Die Funktion AdjustTokenPrivileges kann dem Zugriffstoken keine neuen Berechtigungen hinzufügen. Es kann nur die vorhandenen Berechtigungen des Tokens aktivieren oder deaktivieren. Um die Berechtigungen des Tokens zu bestimmen, rufen Sie die GetTokenInformation-Funktion auf.

Der NewState-Parameter kann Berechtigungen angeben, die das Token nicht besitzt, ohne dass die Funktion fehlschlägt. In diesem Fall passt die Funktion die Berechtigungen an, über die das Token verfügt, und ignoriert die anderen Berechtigungen, sodass die Funktion erfolgreich ist. Rufen Sie die GetLastError-Funktion auf, um zu ermitteln, ob die Funktion alle angegebenen Berechtigungen angepasst hat. Der PreviousState-Parameter gibt die Berechtigungen an, die angepasst wurden.

Der PreviousState-Parameter ruft eine TOKEN_PRIVILEGES-Struktur ab, die den ursprünglichen Zustand der angepassten Berechtigungen enthält. Um den ursprünglichen Zustand wiederherzustellen, übergeben Sie den PreviousState-Zeiger als NewState-Parameter in einem nachfolgenden Aufruf der AdjustTokenPrivileges-Funktion .

Beispiele

Ein Beispiel, das diese Funktion verwendet, finden Sie unter Aktivieren und Deaktivieren von Berechtigungen.

Anforderungen

Weitere Informationen

Zugriffssteuerung Übersicht

AdjustTokenGroups

Grundlegende Access Control-Funktionen

GetTokenInformation

OpenProcessToken

OpenThreadToken

SetTokenInformation

TOKEN_PRIVILEGES