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

Artigo
08/26/2023

A função ProcessGroupPolicy é uma função de retorno de chamada definida pelo aplicativo usada ao aplicar a política. O tipo PFNPROCESSGROUPPOLICY define um ponteiro para essa função de retorno de chamada. ProcessGroupPolicy é um espaço reservado para o nome da função definida pelo aplicativo.

Essa função de retorno de chamada não é útil para o processamento do RSoP (Conjunto de Políticas Resultante) ; use a função de retorno de chamada ProcessGroupPolicyEx .

Sintaxe

PFNPROCESSGROUPPOLICY Pfnprocessgrouppolicy;

DWORD Pfnprocessgrouppolicy(
  [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
)
{...}

Parâmetros

[in] dwFlags

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

GPO_INFO_FLAG_MACHINE

Aplique a política do computador em vez da política de usuário.

GPO_INFO_FLAG_BACKGROUND

Execute uma atualização em segundo plano da política.

GPO_INFO_FLAG_ASYNC_FOREGROUND

Execute uma atualização de primeiro plano assíncrona da política. 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 o aplicativo 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.

[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 de 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 os GPOs devem continuar processando. 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, o status interface do usuário 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.

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 esteja definido. (Para obter mais informações sobre esse valor do Registro, consulte Comentários.) Caso contrário, retorne um código de erro do sistema.

Comentários

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

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, para que seja exclusiva. Ele deve conter os valores a seguir.

Você deverá atualizar a mensagem de 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 aplicativo de política longo. Para usar a função de retorno de chamada de mensagem status, você deve verificar 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 porque você pode substituir a mensagem de 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