Função GetGPOListA (userenv.h)

Artigo
08/26/2023

A função GetGPOList recupera a lista de GPOs para o usuário ou computador especificado. Essa função pode ser chamada de duas maneiras: primeiro, você pode usar o token para o usuário ou computador ou, segundo, você pode usar o nome do usuário ou computador e o nome do controlador de domínio.

Sintaxe

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

Um token para o usuário ou computador, retornado da função LogonUser, CreateRestrictedToken, DuplicateToken, OpenProcessToken ou OpenThreadToken . Esse token deve ter acesso TOKEN_IMPERSONATE e TOKEN_QUERY . Para obter mais informações, consulte Direitos de Acesso para objetos Access-Token e a seção Comentários a seguir.

Se esse parâmetro for NULL, você deverá fornecer valores para os parâmetros lpName e lpHostName .

[in] lpName

Um ponteiro para o nome do usuário ou do computador, no formato de nome diferenciado totalmente qualificado (por exemplo, "CN=user, OU=users, DC=contoso, DC=com").

Se o parâmetro hToken não for NULL, esse parâmetro deverá ser NULL.

[in] lpHostName

Um nome de domínio DNS (preferencial) ou um nome de controlador de domínio. O nome do controlador de domínio pode ser recuperado usando a função DsGetDcName , especificando DS_DIRECTORY_SERVICE_REQUIRED no parâmetro flags .

Se o parâmetro hToken não for NULL, esse parâmetro deverá ser NULL.

[in] lpComputerName

Um ponteiro para o nome do computador usado para determinar o local do site. O formato do nome é "\\computer_name". Se esse parâmetro for NULL, o nome do computador local será usado.

[in] dwFlags

Um valor que especifica sinalizadores adicionais que são usados para controlar a recuperação de informações. Se você especificar GPO_LIST_FLAG_MACHINE, a função recuperará informações de política para o computador. Se você não especificar GPO_LIST_FLAG_MACHINE, a função recuperará informações de política para o usuário.

Se você especificar GPO_LIST_FLAG_SITEONLY a função retornará apenas informações do site para o computador ou usuário.

[out] pGPOList

Um ponteiro que recebe a lista de estruturas de GPO. Para obter mais informações, consulte GROUP_POLICY_OBJECT.

Valor retornado

Se a função for bem-sucedida, o valor retornado será diferente de zero.

Se a função falhar, o valor retornado será zero. Para obter informações de erro estendidas, chame GetLastError.

Comentários

A função GetGPOList destina-se a ser usada por serviços que atuam em nome de um usuário ou computador. O serviço chama essa função para obter uma lista de GPOs e verifica cada GPO quanto à política específica do serviço.

Chamar essa função com um token fornece a lista mais precisa. O sistema pode executar a verificação de acesso para o usuário ou computador. Chamar essa função com o nome de usuário ou computador e o nome do controlador de domínio é mais rápido do que chamá-la com um token. No entanto, se o token não for especificado, o sistema usará o acesso de segurança do chamador, o que significa que a lista pode não estar completamente correta para o usuário ou computador pretendido.

Para obter a lista mais precisa de GPOs para um computador ao chamar GetGPOList, o chamador deve ter acesso de leitura a cada UO e site no domínio do computador e também ler e aplicar Política de Grupo acesso a todos os GPOs vinculados aos sites, domínio ou UOs desse domínio. Um exemplo de um chamador seria um serviço em execução no computador cujo nome é especificado no parâmetro lpName . Um método alternativo para obter uma lista de GPOs seria chamar o método RsopCreateSession da classe WMI RsopPlanningModeProvider . O método pode gerar dados de política resultantes para um computador ou conta de usuário em um cenário hipotético.

Chame a função FreeGPOList para liberar a lista de GPO quando terminar de processá-la.

Em geral, você deve chamar GetGPOList com um token ao recuperar uma lista de GPOs para um usuário, conforme mostrado no exemplo de código a seguir.

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 uma lista de GPOs para um computador, você pode chamar GetGPOList com o nome do computador e o nome do controlador de domínio, conforme demonstrado no snippet de código a seguir.

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 a lista de GPOs aplicados a um usuário ou computador e extensão específicos, chame a função GetAppliedGPOList .

Observação

O cabeçalho userenv.h define GetGPOList como um alias que seleciona automaticamente a versão ANSI ou Unicode dessa função com base na definição da constante de pré-processador UNICODE. Misturar o uso do alias neutro de codificação com código que não seja neutro em codificação pode levar a incompatibilidades que resultam em erros de compilação ou de runtime. Para obter mais informações, consulte Convenções para protótipos de função.

Requisitos


Cliente mínimo com suporte	Windows Vista
Servidor mínimo com suporte	Windows Server 2008
Plataforma de Destino	Windows
Cabeçalho	userenv.h
Biblioteca	Userenv.lib
DLL	Userenv.dll