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, 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 el LogonUser, CreateRestrictedToken, DuplicateToken, OpenProcessTokeno función OpenThreadToken. Este token debe tener acceso TOKEN_IMPERSONATE y TOKEN_QUERY. Para obtener más información, vea Derechos de acceso para Access-Token Objetos y la sección Comentarios siguientes.

Si este parámetro es null, debe proporcionar valores para los parámetros de lpName y lpHostName.

[in] lpName

Puntero al nombre de usuario o equipo, en el formato de nombre distintivo completo (por ejemplo, "CN=usuario, OU=usuarios, DC=contoso, DC=com").

Si el parámetro hToken de 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 marcas.

Si el parámetro hToken de no es NULL, este parámetro debe ser NULL.

[in] lpComputerName

Puntero al nombre del equipo usado 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 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 ejecuta correctamente, el valor devuelto es distinto de cero.

Si se produce un error en la función, el valor devuelto es cero. Para obtener información de error extendida, llame a GetLastError.

Observaciones

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 la lista puede no ser completamente correcta para el usuario o equipo deseados.

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 leer y aplicar el acceso de directiva de grupo a todos los GPO vinculados a los sitios, el dominio o las 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 del RsopPlanningModeProvider clase WMI. 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 de 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 de equipo y el nombre del controlador de dominio, tal 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.

Requisitos

Consulte también

DsGetDcName

FreeGPOList de

GROUP_POLICY_OBJECT

funciones de directiva de grupo de

de información general de la directiva de grupo de