Función AdjustTokenGroups (securitybaseapi.h)

Artículo
08/25/2023

La función AdjustTokenGroups habilita o deshabilita los grupos que ya están presentes en el token de acceso especificado. Se requiere acceso a TOKEN_ADJUST_GROUPS para habilitar o deshabilitar grupos en un token de acceso.

Sintaxis

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

Parámetros

[in] TokenHandle

Identificador del token de acceso que contiene los grupos que se van a habilitar o deshabilitar. El identificador debe tener TOKEN_ADJUST_GROUPS acceso al token. Si el parámetro PreviousState no es NULL, el identificador también debe tener acceso TOKEN_QUERY.

[in] ResetToDefault

Valor booleano que indica si los grupos deben establecerse en sus estados habilitados y deshabilitados predeterminados. Si este valor es TRUE, los grupos se establecen en sus estados predeterminados y se omite el parámetro NewState . Si este valor es FALSE, los grupos se establecen según la información a la que apunta el parámetro NewState .

[in, optional] NewState

Puntero a una estructura TOKEN_GROUPS que contiene los grupos que se van a habilitar o deshabilitar. Si el parámetro ResetToDefault es FALSE, la función establece cada uno de los grupos en el valor del atributo SE_GROUP_ENABLED de ese grupo en la estructura TOKEN_GROUPS . Si ResetToDefault es TRUE, se omite este parámetro.

[in] BufferLength

Tamaño, en bytes, del búfer al que apunta el parámetro PreviousState . Este parámetro puede ser cero si el parámetro PreviousState es NULL.

[out, optional] PreviousState

Puntero a un búfer que recibe una estructura de TOKEN_GROUPS que contiene el estado anterior de cualquier grupo que modifica la función. Es decir, si esta función ha modificado un grupo, el grupo y su estado anterior se encuentran en la estructura TOKEN_GROUPS a la que hace referencia PreviousState. Si el miembro GroupCount de TOKEN_GROUPS es cero, esta función no ha cambiado ningún grupo. Este parámetro puede ser NULL.

Si se especifica un búfer pero no contiene suficiente espacio para recibir la lista completa de grupos modificados, no se cambia ningún estado de grupo y se produce un error en la función. En este caso, la función establece la variable a la que apunta el parámetro ReturnLength en el número de bytes necesarios para contener la lista completa de grupos modificados.

[out, optional] ReturnLength

Puntero a una variable que recibe el número real de bytes necesarios para el búfer al que apunta el parámetro PreviousState . Este parámetro puede ser NULL y se omite si PreviousState es NULL.

Valor devuelto

Si la función se realiza correctamente, el valor devuelto es distinto de cero.

Si la función no se realiza correctamente, el valor devuelto es cero. Para obtener información de error extendida, llame a GetLastError.

Comentarios

La información recuperada en el parámetro PreviousState tiene el formato de estructura TOKEN_GROUPS . Esto significa que se puede pasar un puntero al búfer como parámetro NewState en una llamada posterior a la función AdjustTokenGroups , restaurando el estado original de los grupos.

El parámetro NewState puede enumerar los grupos que se van a cambiar que no están presentes en el token de acceso. Esto no afecta a la modificación correcta de los grupos del token.

La función AdjustTokenGroups no puede deshabilitar los grupos con el atributo SE_GROUP_MANDATORY en la estructura TOKEN_GROUPS . En su lugar, use CreateRestrictedToken .

No se puede habilitar un grupo que tenga el atributo SE_GROUP_USE_FOR_DENY_ONLY.

Requisitos


Cliente mínimo compatible	Windows XP [aplicaciones de escritorio \| aplicaciones para UWP]
Servidor mínimo compatible	Windows Server 2003 [aplicaciones de escritorio \| aplicaciones para UWP]
Plataforma de destino	Windows
Encabezado	securitybaseapi.h (incluya Windows.h)
Library	Advapi32.lib
Archivo DLL	Advapi32.dll