Função GetGPOListW (userenv.h)
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 GetGPOListW(
[in] HANDLE hToken,
[in] LPCWSTR lpName,
[in] LPCWSTR lpHostName,
[in] LPCWSTR lpComputerName,
[in] DWORD dwFlags,
[out] PGROUP_POLICY_OBJECTW *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 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 nome do 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 ao uso 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, em seguida, 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 do usuário ou do 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 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
| Requisito | Valor |
|---|---|
| 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 |