Función GetGPOListA (userenv.h)
La función GetGPOList recupera la lista de GPO para el usuario o equipo especificados. Se puede llamar a esta función de dos maneras: en primer lugar, puede usar el token para el usuario o equipo, o bien, en segundo lugar, puede usar el nombre del usuario o equipo y el nombre del controlador de dominio.
Sintaxis
USERENVAPI BOOL GetGPOListA(
[in] HANDLE hToken,
[in] LPCSTR lpName,
[in] LPCSTR lpHostName,
[in] LPCSTR lpComputerName,
[in] DWORD dwFlags,
[out] PGROUP_POLICY_OBJECTA *pGPOList
);
Parámetros
[in] hToken
Token para el usuario o equipo, devuelto por la función LogonUser, CreateRestrictedToken, DuplicateToken, OpenProcessToken o OpenThreadToken . Este token debe tener acceso TOKEN_IMPERSONATE y TOKEN_QUERY . Para obtener más información, vea Derechos de acceso para objetos Access-Token y la siguiente sección Comentarios.
Si este parámetro es NULL, debe proporcionar valores para los parámetros lpName y lpHostName .
[in] lpName
Puntero al nombre de usuario o equipo, en el formato de nombre distintivo completo (por ejemplo, "CN=user, OU=users, DC=contoso, DC=com").
Si el parámetro hToken no es NULL, este parámetro debe ser NULL.
[in] lpHostName
Un nombre de dominio DNS (preferido) o un nombre de controlador de dominio. El nombre del controlador de dominio se puede recuperar mediante la función DsGetDcName , especificando DS_DIRECTORY_SERVICE_REQUIRED en el parámetro flags .
Si el parámetro hToken no es NULL, este parámetro debe ser NULL.
[in] lpComputerName
Puntero al nombre del equipo utilizado para determinar la ubicación del sitio. El formato del nombre es "\\computer_name". Si este parámetro es NULL, se usa el nombre del equipo local.
[in] dwFlags
Valor que especifica marcas adicionales que se usan para controlar la recuperación de información. Si especifica GPO_LIST_FLAG_MACHINE, la función recupera información de directiva para el equipo. Si no especifica GPO_LIST_FLAG_MACHINE, la función recupera información de directiva para el usuario.
Si especifica GPO_LIST_FLAG_SITEONLY la función devuelve solo la información del sitio para el equipo o el usuario.
[out] pGPOList
Puntero que recibe la lista de estructuras de GPO. Para obtener más información, consulte GROUP_POLICY_OBJECT.
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 función GetGPOList está pensada para su uso por los servicios que actúan en nombre de un usuario o equipo. El servicio llama a esta función para obtener una lista de GPO y, a continuación, comprueba cada GPO para la directiva específica del servicio.
Llamar a esta función con un token proporciona la lista más precisa. El sistema puede realizar la comprobación de acceso para el usuario o el equipo. Llamar a esta función con el nombre de usuario o equipo y el nombre del controlador de dominio es más rápido que llamarla con un token. Sin embargo, si no se especifica el token, el sistema usa el acceso de seguridad del autor de la llamada, lo que significa que es posible que la lista no sea completamente correcta para el usuario o equipo previstos.
Para obtener la lista más precisa de GPO de un equipo al llamar a GetGPOList, el autor de la llamada debe tener acceso de lectura a cada unidad organizativa y sitio del dominio del equipo, y también leer y aplicar directiva de grupo acceso a todos los GPO vinculados a los sitios, dominio u UNIDADES organizativas de ese dominio. Un ejemplo de un llamador sería un servicio que se ejecuta en el equipo cuyo nombre se especifica en el parámetro lpName . Un método alternativo para obtener una lista de GPO sería llamar al método RsopCreateSession de la clase WMI RsopPlanningModeProvider . El método puede generar datos de directiva resultantes para un equipo o una cuenta de usuario en un escenario hipotético.
Llame a la función FreeGPOList para liberar la lista de GPO cuando haya terminado de procesarla.
Por lo general, debe llamar a GetGPOList con un token al recuperar una lista de GPO para un usuario, como se muestra en el ejemplo de código siguiente.
LPGROUP_POLICY_OBJECT pGPOList;
if (GetGPOList (hToken, NULL, NULL, NULL, 0, &pGPOList))
{
// Perform processing here.
//
// Free the GPO list when you finish processing.
FreeGPOList (pGPOList);
}
Normalmente, para recuperar una lista de GPO para un equipo, puede llamar a GetGPOList con el nombre del equipo y el nombre del controlador de dominio, como se muestra en el siguiente fragmento de código.
LPGROUP_POLICY_OBJECT pGPOList;
if (GetGPOList (NULL, lpMachineName, lpHostName, lpMachineName, GPO_LIST_FLAG_MACHINE, &pGPOList))
{
// Perform processing here.
//
// Free the GPO list when you finish processing.
FreeGPOList (pGPOList);
}
Para recuperar la lista de GPO aplicados a un usuario o equipo y una extensión específicos, llame a la función GetAppliedGPOList .
Nota:
El encabezado userenv.h define GetGPOList como alias que selecciona automáticamente la versión ANSI o Unicode de esta función en función de la definición de la constante de preprocesador UNICODE. La combinación del uso del alias neutral de codificación con código que no es neutral de codificación puede dar lugar a errores de coincidencia que dan lugar a errores de compilación o tiempo de ejecución. Para obtener más información, vea Convenciones para prototipos de función.
Requisitos
| Cliente mínimo compatible | Windows Vista |
| Servidor mínimo compatible | Windows Server 2008 |
| Plataforma de destino | Windows |
| Encabezado | userenv.h |
| Library | Userenv.lib |
| Archivo DLL | Userenv.dll |