Función AdjustTokenGroups (securitybaseapi.h)
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 |
Consulte también
Información general del control de acceso