Função de retorno de chamada PFNPROCESSGROUPPOLICYEX (userenv.h)

Artigo
08/26/2023

A função ProcessGroupPolicyEx é uma função de retorno de chamada definida pelo aplicativo usada ao aplicar a política. Essa função estendida também dá suporte ao registro em log de dados do RSoP (Conjunto resultante de política). O tipo PFNPROCESSGROUPPOLICYEX define um ponteiro para essa função de retorno de chamada. ProcessGroupPolicyEx é um espaço reservado para o nome da função definida pelo aplicativo.

Sintaxe

PFNPROCESSGROUPPOLICYEX Pfnprocessgrouppolicyex;

DWORD Pfnprocessgrouppolicyex(
  [in]  DWORD dwFlags,
  [in]  HANDLE hToken,
  [in]  HKEY hKeyRoot,
  [in]  PGROUP_POLICY_OBJECT pDeletedGPOList,
  [in]  PGROUP_POLICY_OBJECT pChangedGPOList,
  [in]  ASYNCCOMPLETIONHANDLE pHandle,
  [in]  BOOL *pbAbort,
  [in]  PFNSTATUSMESSAGECALLBACK pStatusCallback,
  [in]  IWbemServices *pWbemServices,
  [out] HRESULT *pRsopStatus
)
{...}

Parâmetros

[in] dwFlags

Esse parâmetro pode ser um ou mais dos sinalizadores a seguir.

GPO_INFO_FLAG_MACHINE

Aplicar política de computador em vez de política de usuário.

GPO_INFO_FLAG_BACKGROUND

Execute uma atualização em segundo plano da política. Para obter mais informações, consulte o texto que segue esta lista.

GPO_INFO_FLAG_ASYNC_FOREGROUND

Execute uma atualização de primeiro plano assíncrona da política. Para obter mais informações, consulte o texto que segue esta lista. Para obter mais informações sobre o aplicativo de política em primeiro plano, consulte Processamento Inicial de Política de Grupo.

GPO_INFO_FLAG_SLOWLINK

A política está sendo aplicada em um link lento.

GPO_INFO_FLAG_VERBOSE

Gravar saída detalhada no log de eventos.

GPO_INFO_FLAG_NOCHANGES

Nenhuma alteração no GPO foi detectada.

GPO_INFO_FLAG_LINKTRANSITION

Uma alteração na velocidade do link foi detectada entre aplicativos de política.

GPO_INFO_FLAG_LOGRSOP_TRANSITION

Foi detectada uma alteração no log RSoP entre o aplicativo da política anterior e a aplicação da política atual.

GPO_INFO_FLAG_FORCED_REFRESH

Uma atualização de política forçada está sendo aplicada.

GPO_INFO_FLAG_SAFEMODE_BOOT

Sinalizador de modo de segurança.

O sinalizador GPO_INFO_FLAG_BACKGROUND e o sinalizador GPO_INFO_FLAG_ASYNC_FOREGROUND podem ser definidos. Como as políticas são sempre aplicadas de forma assíncrona durante uma atualização em segundo plano, a maioria das extensões lida com uma atualização de primeiro plano assíncrona da mesma maneira em que lidam com uma atualização em segundo plano. Portanto, eles não precisam marcar para o sinalizador GPO_INFO_FLAG_ASYNC_FOREGROUND. Em instâncias em que uma extensão deve distinguir entre uma atualização em segundo plano da política e uma atualização de primeiro plano assíncrona da política, a extensão pode marcar para o sinalizador de GPO_INFO_FLAG_ASYNC_FOREGROUND.

[in] hToken

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 representação do cliente.

[in] hKeyRoot

Manipule para o HKEY_LOCAL_MACHINE ou HKEY_CURRENT_USER chave do Registro.

[in] pDeletedGPOList

Ponteiro que recebe a lista de estruturas de GPO excluídas. Para obter mais informações, consulte GROUP_POLICY_OBJECT.

[in] pChangedGPOList

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

[in] pHandle

Identificador de conclusão assíncrona. Se a função de retorno de chamada não der suporte ao processamento assíncrono, esse identificador será zero.

[in] pbAbort

Especifica se deseja continuar processando GPOs. Se esse parâmetro for TRUE, o processamento de GPO cessará. Se esse parâmetro for FALSE, o processamento de GPO continuará.

[in] pStatusCallback

Ponteiro para uma função de retorno de chamada StatusMessageCallback que exibe mensagens status. Esse parâmetro pode ser NULL em determinados casos. Por exemplo, se o sistema estiver aplicando a política em segundo plano, a interface do usuário status não estará presente e o aplicativo não poderá enviar status mensagens a serem exibidas. Para obter mais informações, consulte a seção Comentários a seguir.

[in] pWbemServices

Especifica um ponteiro de serviços WMI para o namespace RSoP no qual os dados de política devem ser gravados. Esse parâmetro é NULL quando o log RSoP está desabilitado, indicando que a extensão não deve registrar dados RSoP em log.

[out] pRsopStatus

Ponteiro para um código de retorno HRESULT que indica se o registro em log RSoP foi bem-sucedido.

Retornar valor

Se a política tiver sido aplicada com êxito, retorne ERROR_SUCCESS. Se não houver alterações na lista de GPO e a extensão for chamada novamente, retorne ERROR_OVERRIDE_NOCHANGES. Retornar ERROR_OVERRIDE_NOCHANGES garante que a extensão seja chamada novamente, mesmo que o valor do registro NoGPOListChanges seja definido. (Para obter mais informações sobre esse valor do Registro, consulte Comentários.)

Retorne ERROR_SYNC_FOREGROUND_REFRESH_REQUIRED se a função foi chamada para uma atualização de primeiro plano assíncrona da política, mas a política não pôde ser aplicada durante a atualização assíncrona. Retornar ERROR_SYNC_FOREGROUND_REFRESH_REQUIRED indica que a função deve ser chamada novamente para uma atualização de primeiro plano síncrona da política.

Caso contrário, retorne um código de erro do sistema.

Comentários

Para obter mais informações, consulte Implementando uma extensão do lado do cliente Política de Grupo.

O sistema chama essa função no contexto da conta LocalSystem, que tem privilégios extensos no computador local. Para usar recursos de rede, você deve representar o usuário ou o computador usando o token fornecido no parâmetro hToken .

Para registrar essa função de retorno de chamada, crie uma subchave na seguinte chave do Registro:

HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\\ Windows NT CurrentVersion\Winlogon\GPExtensions\ClientExtensionGuid

A subchave deve ser um GUID, de modo que seja exclusivo. Ele deve conter os valores a seguir.

Você deverá atualizar a mensagem status somente se estiver aplicando a política de forma síncrona. Isso permite que você forneça comentários e diagnóstico durante um longo aplicativo de política. Para usar a função de retorno de chamada status mensagem, verifique se pStatusCallback não é NULL. Em seguida, carregue o recurso de cadeia de caracteres de mensagem. Ao chamar a função status, você deve indicar se a cadeia de caracteres é detalhada. Se a cadeia de caracteres for detalhada, a função de retorno de chamada verificará se o computador está no modo detalhado e exibirá a mensagem. Para obter mais informações, consulte StatusMessageCallback.

Aviso Não chame a função pStatusCallback de um thread em segundo plano ou você pode substituir a mensagem status de outro thread.

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